Core API¶

MedicalVolume¶

dosma.data_io.MedicalVolume

The class for medical images.

Image I/O¶

`dosma.data_io.NiftiReader`	A class for reading NIfTI files.
`dosma.data_io.NiftiWriter`	A class for writing volumes in NIfTI format.
`dosma.data_io.DicomReader`	A class for reading DICOM files.
`dosma.data_io.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 easily interpretable 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.data_io.MedicalVolume.

`dosma.data_io.orientation.get_transpose_inds`	Get indices for reordering planes from `curr_orientation` to `new_orientation`.
`dosma.data_io.orientation.get_flip_inds`	Get indices to flip from `curr_orientation` to `new_orientation`.
`dosma.data_io.orientation.orientation_nib_to_standard`	Convert Nibabel orientation to the standard dosma orientation format.
`dosma.data_io.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.utils.registration.register`	Register moving image(s) to the target.
`dosma.utils.registration.apply_warp`	Apply transform(s) to moving image using transformix.
`dosma.utils.registration.symlink_elastix`	Symlinks elastix/transformix files to the dosma library.
`dosma.utils.registration.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.utils.fits.curve_fit`	Use non-linear least squares to fit a function `func` to data.
`dosma.utils.fits.monoexponential`	Function: \(f(x) = a * e^{b*x}\).
`dosma.utils.fits.biexponential`	Function: \(f(x) = a1e^{b1x} + a2e^{b2x}\).

Quantitative MR Fitter classes:

dosma.utils.fits.MonoExponentialFit

Fit quantitative values using mono-exponential fit of model \(a*exp(t/tc)\).