API Guide

Here we outline the modules, classes, and key functions to use in the MIAAIM workflow in Python.

Image Preparation (HDIprep)

hdi_prep

hdiprep.HDIprep.hdi_prep.CreateDataset(list_of_paths, mask=None, **kwargs)

Create an intramodality imaging dataset based on a given list of paths for imaging files.

list_of_paths: list of length n_samples.

Input data to concatenate into a single dataset. Each input dataset is of the class HDIreader from the hdiutils python package.

data: class object.

Dataset with concatenated image data.

class hdiprep.HDIprep.hdi_prep.IntraModalityDataset(list_of_HDIimports)

Merge HDIreader classes storing imaging datasets.

list_of_HDIimports: list of length (n_samples)

Merges input HDIreader objects to be merged into single class.

Initialized class objects:

• self.set_dict: dictionary

  Dictionary containing each input samples filename as the key.

• self.umap_object: object of class UMAP

  Stores any UMAP class objects after running UMAP.

• self.umap_embeddings: dictionary

  Dictionary storing UMAP embeddings for each input sample.

• self.umap_optimal_dim: integer

  Specifies steady state embedding dimensionality for UMAP.

• self.processed_images_export: None or dictionary after ExportNifti1

  Dictionary that links input file names with new export file names.

• self.landmarks: integer

  Specifies number of landmarks to use for steady state embedding dimensionality estimation.

ApplyManualMask()

Apply input mask to image. This function is primarily used on histology images and images that do not need dimension reduction. Dimension reduction with a mask will by default zero all other pixels in the image outside of the mask, but do not use this function if performing dimension reduction.

ApplyMask()

Apply mask to image. This function is primarily used on histology images and images that do not need dimension reduction. Should be used after a series of morphological operations. This applies the resulting mask of thresholding and morphological operations.

Close(disk_size, parallel=False)

Morphological closing on boolean array (i.e., a mask). A circular disk is used for the filtering.

filter_size: integer

Size of disk to use for the median filter.

parallel: Bool (Default: False)

Use parallel processing with all available CPUs.

ExportNifti1(output_dir, padding=None, target_size=None)

Export processed images resulting from UMAP and spatially mapping UMAP, or exporting processed histology images.

output_dir: string

Path to output directory to store processed nifti image.

padding: string of tuple of type integer (padx,pady; Default: None)

Indicates height and length padding to add to the image before exporting.

target_size: string of tuple of type integer (sizex,sizey; Default: None)

Resize image using bilinear interpolation before exporting.

Fill()

Morphological filling on a binary mask. Fills holes in the given mask.

MedianFilter(filter_size, parallel=False)

Median filtering of images to remove salt and pepper noise. A circular disk is used for the filtering. Images that are not single channel are automatically converted to grayscale prior to filtering.

filter_size: integer

Size of disk to use for the median filter.

parallel: Bool (Default: False)

Use parallel processing with all available CPUs.

NonzeroBox()

Use a nonzero indices of a binary mask to create a bounding box for the mask itself and for the original image. This isused so that a controlled amount of padding can be added to the edges of the images in a consistent manner.

Open(disk_size, parallel=False)

Morphological opening on boolean array (i.e., a mask). A circular disk is used for the filtering.

filter_size: integer

Size of disk to use for the median filter.

parallel: Bool (Default: False)

Use parallel processing with all available CPUs.

RunOptimalParametricUMAP(dim_range=(1, 11), landmarks=3000, export_diagnostics=False, output_dir=None, n_jobs=1, **kwargs)

Run parametric UMAP over a range of dimensions to choose steady state embedding by fitting an exponential regression model to the fuzzy set cross entropy curve.

dim_range: tuple (low_dim, high_dim; Default: (1,11))

Indicates a range of embedding dimensions.

landmarks: integer (Default: 3000)

Specifies number of landmarks to use for steady state embedding dimensionality estimation.

export_diagnostics: Bool (Default: False)

Indicates whether or not to export a csv file and jpeg image showing steady state embedding dimensionality reports. These report the normalized (0-1 range) fuzzy set cross entropy across the range of indicated dimensionalities.

output_dir: string (Default: None)

Path to export data to if exporting diagnostic images and plots.

n_jobs: integer (Default: 1)

Path to export data to if exporting diagnostic images and plots.

kwargs: key word arguments passed to UMAP.

Important arguments:

• n_neighbors: integer

  Specifies number of nearest neighbors.

• random_state: integer

  Specifies random state for reproducibility.

RunOptimalUMAP(dim_range=(1, 11), landmarks=3000, export_diagnostics=False, output_dir=None, n_jobs=1, **kwargs)

Run UMAP over a range of dimensions to choose steady state embedding by fitting an exponential regression model to the fuzzy set cross entropy curve.

dim_range: tuple (low_dim, high_dim; Default: (1,11))

Indicates a range of embedding dimensions.

landmarks: integer (Default: 3000)

Specifies number of landmarks to use for steady state embedding dimensionality estimation.

export_diagnostics: Bool (Default: False)

Indicates whether or not to export a csv file and jpeg image showing steady state embedding dimensionality reports. These report the normalized (0-1 range) fuzzy set cross entropy across the range of indicated dimensionalities.

output_dir: string (Default: None)

Path to export data to if exporting diagnostic images and plots.

n_jobs: integer (Default: 1)

Path to export data to if exporting diagnostic images and plots.

kwargs: key word arguments passed to UMAP.

Important arguments:

• n_neighbors: integer

  Specifies number of nearest neighbors.

• random_state: integer

  Specifies random state for reproducibility.

RunParametricUMAP(**kwargs)

Creates an embedding of high-dimensional imaging data using UMAP parametrized by neural network. Each pixel will be represented by its coordinates in the UMAP projection space.

kwargs: key word arguments passed to UMAP.

Important arguments:

• n_neighbors: integer

  Specifies number of nearest neighbors.

• random_state: integer

  Specifies random state for reproducibility.

self.umap_embeddings: dictionary

Stores umap coordinates for each input file as the dictionary key.

RunUMAP(**kwargs)

Creates an embedding of high-dimensional imaging data. Each pixel will be represented by its coordinates in the UMAP projection space.

kwargs: arguments passed to UMAP.

Important arguments:

• n_neighbors: integer

  Specifies number of nearest neighbors.

• random_state: integer

  Specifies random state for reproducibility.

self.umap_embeddings: dictionary

Stores umap coordinates for each input file as the dictionary key.

SpatiallyMapUMAP(method='rectangular', save_mem=True)

Map UMAP projections into the spatial domain (2-dimensional) using each pixel’s original XY positions.

method: string (Default: “rectangular”)

Type of mapping to use for reconstructing an image from the UMAP embeddings.

Options include:

• “rectangular”

  Use for images that do not have an associated mask with them. This is the fastest option for spatial reconstruction.

• “coordinate”

  Use each pixel’s XY coordinate to fill an array one pixel at a time. This must be used for images that contain masks or are not stored as rectangular arrays.

save_mem: Bool (Default: True)

Save memory by deleting reserves of full images and intermediate steps.

Threshold(type='otsu', thresh_value=None, correction=1.0)

Threshold grayscale images. Produces a sparse boolean mask.

type: string (Default: “otsu”)

Type of thresholding to use.

Options include:

• “otsu”

  Otsu automated thresholding.

• “manual”

  Set manual threshold value.

thresh_value: float (Default: None)

Manual threshold to use if type is set to “manual”

correction: float (Default: 1.0)

Correct factor to multiply threshold by for more stringent thresholding.

utils

hdiprep.HDIprep.utils.CreateHyperspectralImage(embedding, array_size, coordinates, scale=True)

Fill a hyperspectral image from n-dimensional embedding of high-dimensional imaging data by rescaling each channel from 0-1 (optional). All coordinates in the image not listed in coordinates object will be masked and set to 0 (background).

embedding: Pandas DataFrame

Indicates embedding coordinates from UMAP or another method.

array_size: tuple

Indicates size of image.

coordinates: 1-indexed list of tuples

Indicates pixel coordinates of image.

scale: Bool (Default: True)

Rescale pixel intensities on the range of 0-1.

im: array

Reconstructed image.

hdiprep.HDIprep.utils.CreateHyperspectralImageRectangular(embedding, array_size, coordinates, scale=True)

Fill a hyperspectral image from n-dimensional embedding of high-dimensional imaging data by rescaling each channel from 0-1 (optional). All coordinates in the image not listed in coordinates object will be masked and set to 0 (background). This function assumes that the data you want to reconstruct can be automatically reshaped into a rectangular array.

embedding: Pandas DataFrame

Indicates embedding coordinates from UMAP or another method.

array_size: tuple

Indicates size of image.

coordinates: 1-indexed list of tuples

Indicates pixel coordinates of image.

scale: Bool (Default: True)

Rescale pixel intensities on the range of 0-1.

im: array

Reconstructed image.

hdiprep.HDIprep.utils.Exp(x, a, b, c)

Exponential function to use for regression.

hdiprep.HDIprep.utils.ExportNifti(image, filename, padding=None, target_size=None)

Export processed images resulting from UMAP and spatially mapping UMAP, or exporting processed histology images.

image: array

Array that represents image to export.

filename: string

Path, including filename, to export processed nifti image to.

padding: string of tuple of type integer (padx,pady; Default: None)

Indicates height and length padding to add to the image before exporting.

target_size: string of tuple of type integer (sizex,sizey; Default: None)

Resize image using bilinear interpolation before exporting.

Image Registration (HDIreg)

elastix

class hdireg.HDIreg.elastix.Elastix(fixed, moving, out_dir, p, fp=None, mp=None, fMask=None)

Elastix image registration class.

fixed: string

Path to fixed (reference) image.

moving: string

Path to moving image (image to be transformed).

out_dir: string

Path to output directory.

p: list (length number of registration parameter files)

Path to elastix image registration parameter files (in order of application).

fp: string (*.txt)

Path to fixed image landmark points for manual guidance registration.

mp: string (*.txt)

Path to moving image landmark points for manual guidance registration.

fMask: string (*.nii)

Path to fixed image mask that defines region on image to draw samples from during registration.

hdireg.HDIreg.elastix.RunElastix(command)

Run the elastix registration. You must be able to call elastix from your command shell to use this. You must also have your parameter text files set before running (see elastix parameter files).

command: string

Sent to the system for elastix running (see elastix command line implementation).

transformix

hdireg.HDIreg.transformix.CreateCompositeTransforms(tps, out_dir)

Apply a series of transformations to an image using transformix. Prior results show that composing transforms in elastix do not yield the same result as appying each transformation in series. This will take more time but will give the expected result. A new copy of transform parameters will be created and exported to the out_dir

tps: list (length number of transformation parameter files)

Path to elastix image registration transform parameter files (in order of application).

out_dir: string

Path to output directory for transform parameters and output results.

transform_calls: list

List of transform parameters to insert into the transformix command “–tp”.

init_trans_list: list

List of initial transformations in the tranform parameter files. These are part of the actual transform parameter .txt files.

hdireg.HDIreg.transformix.CropROI(coords, full_img, target_size=None)

Extract region of interest from full image array.

coords: list

Returned from GetCropCoords

full_img: array

Contains the image to be cropped from.

target_size: tuple of type integer (sizex,sizey; Default: None)

Resize image using bilinear interpolation before exporting.

nifti_ROI: object of class nibabel.Nifti1Image

Returns nibabel nifti object that is the cropped region to be exported.

hdireg.HDIreg.transformix.ExtractROIcrop(coords_csv, full_img, target_size=None, correction=80)

Combine CropROI and GetCropCoords to return a nifti object available for export.

coords_csv: string.

Path to csv file containing coordinates.

full_img: array

Contains the image to be cropped from.

target_size: tuple of type integer (sizex,sizey; Default: None)

Resize image using bilinear interpolation before exporting.

correction: integer (Default: 80)

Extra pixels to take on each side of the crop contour for buffer.

crop_im: object of class nibabel.Nifti1Image

Returns nibabel nifti object that is the cropped region to be exported.

hdireg.HDIreg.transformix.GetCropCoords(coords_csv, correction=80)

Read csv file containing coordinates for rectangular crop through FIJI and return the coordinates as a list.

coords_csv: string.

Path to csv file containing coordinates.

correction: integer (Default: 80)

Extra pixels to take on each side of the crop contour for buffer.

list with min row, max row, min col, max col coordinates of bounding box.

hdireg.HDIreg.transformix.MultiTransformix(in_im, out_dir, tps)

Applies multiple transform files in sequence to an image.

in_im: string

Input image path.

tps: list (length number of transformation parameter files)

Path to elastix image registration transform parameter files (in order of application).

out_dir: string

Path to output directory for transform parameters and output results.

hdireg.HDIreg.transformix.RunTransformix(command)

Run the transfomix transformation. You must be able to call transformix from your command shell to use this. You must also have your transformation parameter files set before running (see transformix parameter files).

command: string

Sent to the system for transformix running (see elastix command line implementation).

command: string

Same string as above.

class hdireg.HDIreg.transformix.Transformix(in_im, out_dir, tps, target_size=None, pad=None, trim=None, crops=None, out_ext='.nii')

Python implementation of Transformix with automated image pre-processing.

in_im: string

Input image path.

out_dir: string

Path to output directory for transform parameters and output results.

tps: list (length number of transformation parameter files)

Path to elastix image registration transform parameter files (in order of application).

target_size: tuple of type integer (sizex,sizey; Default: None)

Resize image using bilinear interpolation before exporting.

pad: tuple of type integer (padx,pady; Default: None)

Indicates height and length padding to add to the image before exporting.

trim: tuple of type integer (trimx,trimy; Default: None)

Indicates height and length trimming to remove from the image before exporting.

crops: dictionary (Default: None)

Dictionary of dictionaries containing {crop_name(s): {coords_csv: , target_size: , correction: , tp: , fixed_pad: }}. All arguments for each cropped region (i.e., region of interest) are performed only on the given crop.

• coords_csv: string.

  Path to csv file containing coordinates.

• target_size: tuple of type integer (sizex,sizey; Default: None)

  Resize image using bilinear interpolation before exporting.

• correction: integer

  Extra pixels to take on each side of the crop contour for buffer.

• tp: list (length number of transformation parameter files)

  Path to elastix image registration transform parameter files (in order of application) for this crop.

• fixed_pad: integer

  Indicates trim to remove from the cropped image before exporting. This should be the same value as the amount of padding applied to the cropped region’s corresponding fixed image that was used for registration.

utils

hdireg.HDIreg.utils.GetFinalTransformParameters(dir=None)

Extract Transform Parameter files from elastix in order.

dir: string (Default: None, will search in current working directory)

Directory to search for files in.

full_list: list

Transform paramter files as pathlib objects in order.

hdireg.HDIreg.utils.ParseElastix(input, par)

Parse an elastix parameter file or elastix.log file and extract a number associated with the given string parameter.

input: string

Path to input file.

par: string

String indicating the parameter in the files to extract.

number: string

Orginal string found in the given file. This will be converted to an integer or a floating point number.

num: integer or float

Number corresponding to the parameter specified.

hdireg.HDIreg.utils.SearchDir(ending='.txt', dir=None)

Search only in given directory for files that end with the specified suffix.

ending: string (Default: “.txt”)

Ending to search for in the given directory

dir: string (Default: None, will search in current working directory)

Directory to search for files in.

full_list: list

List of pathlib objects for each file found with the given suffix.

hdireg.HDIreg.utils.TraverseDir(ending='.txt', dir=None)

Traverse a directory to search for files that end with the specified suffix.

ending: string (Default: “.txt”)

Ending to search for in the given directory

dir: string (Default: None, will search in current working directory)

Directory to search for files in.

full_list: list

List of pathlib objects for each file found with the given suffix.

Tissue State Modeling (PatchMAP)

patchmap.patchmap_.compute_cobordism(X_list, **kwargs)

Patch multiple umap models (simplicial sets) to create a cobordism.

X_list: list of arrays

Objects to be passed to umap.fit(). As of now, all of these arrays must have the same number of variables.

stacked: sparse graph

Stitched together simplicial set that represents a cobordism.

patchmap.patchmap_.embed_cobordism(X_list, patched_simplicial_set, n_components=2, n_epochs=200, gamma=1, initial_alpha=1.0, **kwargs)

Embed cobordism.

X_list: list of arrays

Objects to be passed to umap.fit(). As of now, all of these arrays must have the same number of variables.

patched_simplicial_set: sparse graph

Stitched together simplicial set that represents a cobordism.

n_components: integer (Default: 2)

Number of embedding components.

embed: array

Embedding array.

Cross-System/Tissue Information Transfer (i-PatchMAP)

patchmap.patchmap_.compute_i_patchmap_cobordism(dat, new_dat, random_state, n_neighbors, **kwargs)

Create cobordism between reference and query data for information transfer.

dat: array

Reference data set.

new_dat: array

Query data set.

random_state: integer

Random state to set the seed for reproducibility.

n_neighbors: integer

Number of neighbors to use for constructing the cobordism.

kwargs: key word arguments

Passes to UMAP.

out: sparse graph

Output cobordism.

lt_ind: tuple

Specifies the indices of the reference data set in the resulting cobordism.

rt_ind: tuple

Specifies the indices of the query data set in the resulting cobordism.

patchmap.patchmap_.i_patchmap(dat, overlay, new_dat, random_state, n_neighbors, prune=None, all_markov=False, **kwargs)

i-PatchMAP workflow for transferring data across cobordism geodesics.

dat: array

Reference data set.

overlay: array (n_samples,n_features)

Array representing reference data that will be interpolated to the query data.

new_dat: array

Query data set.

random_state: integer

Random state to set the seed for reproducibility.

n_neighbors: integer

Number of neighbors to use for constructing the cobordism.

prune: float (Default: None)

Value in the interval [0-1] that specifies a threshold for edge weights in the cobordism. Any values lower than the set threshold will be pruned.

all_markov: Bool

Compute L1 normalization across all cobordism instead of reference to query data.

kwargs: key word arguments to pass to UMAP.

projections: sparse array

Interpolated measures in the query data set from the reference overlay data.

rt: sparse graph

L1 normalized graph used to transfer data from reference to query data.

out: sparse graph

Output cobordism.