Core API (dosma.core)

MedicalVolume

dosma.MedicalVolume

The class for medical images.

Numpy Routines

Numpy operations that are supported on MedicalVolumes.

dosma.core.numpy_routines.all_np	See numpy.all().
dosma.core.numpy_routines.amax	See numpy.amax().
dosma.core.numpy_routines.amin	See numpy.amin().
dosma.core.numpy_routines.any_np	See numpy.any().
dosma.core.numpy_routines.argmax	See numpy.argmax().
dosma.core.numpy_routines.argmin	See numpy.argmin().
dosma.core.numpy_routines.around	Round medical image pixel data (and optionally affine) to the given number of decimals.
dosma.core.numpy_routines.clip	Clip the values in the array.
dosma.core.numpy_routines.concatenate	Concatenate medical images.
dosma.core.numpy_routines.expand_dims	Expand across non-spatial dimensions.
dosma.core.numpy_routines.may_share_memory	Determine if two medical volumes may share memory.
dosma.core.numpy_routines.mean_np	See numpy.mean().
dosma.core.numpy_routines.nan_to_num	See numpy.nan_to_num().
dosma.core.numpy_routines.nanargmax	See numpy.nanargmax().
dosma.core.numpy_routines.nanargmin	See numpy.nanargmin().
dosma.core.numpy_routines.nanmax	See numpy.nanmax().
dosma.core.numpy_routines.nanmean	See numpy.nanmean().
dosma.core.numpy_routines.nanmin	See numpy.nanmin().
dosma.core.numpy_routines.nanstd	See numpy.nanstd().
dosma.core.numpy_routines.nansum	See numpy.nansum().
dosma.core.numpy_routines.ones_like	See numpy.ones_like().
dosma.core.numpy_routines.pad	Implementation of numpy.pad() for MedicalVolume.
dosma.core.numpy_routines.shares_memory	Determine if two medical volumes share memory.
dosma.core.numpy_routines.squeeze	Squeeze non-spatial dimensions.
dosma.core.numpy_routines.stack	Stack medical images across non-spatial dimensions.
dosma.core.numpy_routines.std	See numpy.std().
dosma.core.numpy_routines.sum_np	See numpy.sum().
dosma.core.numpy_routines.where	See numpy.where().
dosma.core.numpy_routines.zeros_like	See numpy.zeros_like().

Standard universal functions that act element-wise on the array are also supported. A (incomplete) list is shown below:

numpy.power	numpy.sign	numpy.remainder	numpy.mod	numpy.abs
numpy.log	numpy.exp	numpy.sqrt	numpy.square	numpy.reciprocal
numpy.sin	numpy.cos	numpy.tan	numpy.bitwise_and	numpy.bitwise_or
numpy.isfinite	numpy.isinf	numpy.isnan	numpy.floor	numpy.ceil

Image I/O

dosma.read	Read MedicalVolume(s) from file.
dosma.write	Write MedicalVolume to file.
dosma.NiftiReader	A class for reading NIfTI files.
dosma.NiftiWriter	A class for writing volumes in NIfTI format.
dosma.DicomReader	A class for reading DICOM files.
dosma.DicomWriter	A class for writing volumes in DICOM format.

Image Orientation

Standardized orientation convention and utilities.

Medical image orientation convention is library and image format (DICOM, NIfTI, etc.) dependent and is often difficult to interpret. This makes it challenging to intelligently and rapidly reformat images.

We adopt a human readable orientation representation for the dimensions and define utilities to convert between different orientation formats from current libraries (Nibabel, PyDicom, ITK, etc).

Orientations are represented by string axis codes:

• "LR": left to right; "RL": right to left

• "PA": posterior to anterior; "AP": anterior to posterior

• "IS": inferior to superior; "SI": superior to inferior

A MedicalVolume object with orientation ("SI", "AP", "LR") has an array where the first dimension spans superior -> inferior, the second dimension spans anterior -> posterior, and the third dimension spans left -> right. Voxel at (i,j,k) index (0,0,0) would be the (superior, anterior, left) corner.

In many cases, images are not acquired in the standard plane convention, but rather in a rotated frame. In this case, the orientations correspond to the closest axis the a particular dimension.

Two general conventions are followed:

• All orientations are in patient voxel coordinates. Image data from (i, j, k) corresponds to the voxel at array position arr[i,j,k].

• Left: corresponds to patient (not observer) left, right: corresponds to patient (not observer) right.

We adopt the RAS+ standard (as defined by NIfTI) for orienting our images. The + in RAS+ indicates that all directions point to the increasing direction. i.e. from -x to x:.

Image spacing, direction, and global origin are represented by a 4x4 affine matrix (\(A\)) and is identical to the nibabel affine matrix (see nibabel). The affine matrix converts pixel coordinates (i, j, k) into world (NIfTI) coordinates (x, y, z).

\[\begin{split}\begin{bmatrix} x\\y\\z\\1\end{bmatrix} = A \begin{bmatrix} i\\j\\k\\1\end{bmatrix}\end{split}\]

For example,

\[\begin{split}\begin{bmatrix} x\\y\\z\\1 \end{bmatrix} = \begin{bmatrix} 0 & 0 & 1.5 & -61.6697\\-0.3125 & 0 & 0 & 50.8516\\ 0 & -0.3125 & 0 & 88.5876\\0 & 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} i\\j\\k\\1\end{bmatrix}\end{split}\]

For details on how the affine matrix is used for reformatting see dosma.core.MedicalVolume.

dosma.core.orientation.to_affine	Convert orientation, spacing, and origin data into affine matrix.
dosma.core.orientation.get_transpose_inds	Get indices for reordering planes from curr_orientation to new_orientation.
dosma.core.orientation.get_flip_inds	Get indices to flip from curr_orientation to new_orientation.
dosma.core.orientation.orientation_nib_to_standard	Convert Nibabel orientation to the standard dosma orientation format.
dosma.core.orientation.orientation_standard_to_nib	Convert standard dosma orientation format to Nibabel orientation.

Image Registration

For details on using registration, see the Registration Guide.

dosma.register	Register moving image(s) to the target.
dosma.apply_warp	Apply transform(s) to moving image using transformix.
dosma.symlink_elastix	Symlinks elastix/transformix files to the dosma library.
dosma.unlink_elastix	Unlinks all elastix/transformix files in the dosma library.

Fitting

For details on using fitting functions, see the Fitting Guide.

General fitting functions:

dosma.curve_fit	Use non-linear least squares to fit a function func to data.
dosma.polyfit	Use linear least squares to fit a polynomial of degree deg to data.
dosma.core.fitting.monoexponential	Function: \(f(x) = a * e^{b*x}\).
dosma.core.fitting.biexponential	Function: \(f(x) = a1*e^{b1*x} + a2*e^{b2*x}\).

Fitter classes:

dosma.CurveFitter	The class using non-linear least squares to fit a function to data.
dosma.PolyFitter	The class using linear least squares to fit a polynomial to data.
dosma.MonoExponentialFit	Fit quantitative values using mono-exponential fit of model \(y=a*exp(-x/tc)\).

Device

dosma.Device	Device class.
dosma.get_device	Get Device from input array.
dosma.to_device	Move input to device.

Preferences

dosma.defaults._Preferences	A pseudo-Singleton class implementation to track preferences.
dosma.preferences	A pseudo-Singleton class implementation to track preferences.

(BETA) Quantitative Values

Utilities for different quantitative parameters. Note, this feature is in beta and will likely change in future releases.

dosma.core.quant_vals.QuantitativeValue	This class handles tracking volumes associated with different quantitative values.
dosma.core.quant_vals.T1Rho	T1Rho MRI parameter.
dosma.core.quant_vals.T2	T2 MRI parameter.
dosma.core.quant_vals.T2Star	T2Star MRI parameter.