API Reference

class qlayers.quant_layers.QLayers(mask_img, thickness=1, fill_ml=10, pelvis_dist=0, space='map')[source]

This class takes in a mask of a kidney and calculates the depth of each voxel from the surface of the kidney. The kidney is then divided into layers of a specified thickness that can be used as regions of interest. It can then be used to add maps of other quantitative parameters to the kidney and generate dataframes of these parameters with depth/layer.

Parameters:

  • mask_img (nibabel.nifti1.Nifti1Image) – Binary mask of kidney

  • thickness (float, optional) – Default 1 Thickness of layers to use when quantising depth, in millimeters

  • fill_ml (float, optional) – Default 10 Volume of holes in the mask to fill (usually cycst), in cubic centimeters (ml)

  • pelvis_dist (float, optional) – Default 0 Voxels within pelvis_dist of the renal pelvis are excluded from the resulting depth/layer calculations. If 0, no pelvis segmentation is performed

  • space ({"map", "layers"}, optional) – Default “map” If “map”, the depth map is resampled to the space of the depth/layers are resampled to the space of the quantitative map. If “layers”, the quantitative map is resampled to the space of the layers/depth. “map” gives more accurate quantitative results as the map is not resampled however “layers” allows for the output of a wide dataframe where each row contains the depth, layer and all quantitative measurements for a voxel.

add_map(map_img, name, norm=False)[source]

Add a quantitative map to the object. The either map or layers will be resampled to a common space depending on the space parameter of the QLayers object.

Parameters:

  • map_img (nibabel.nifti1.Nifti1Image) – Quantitative map to be added to the object

  • name (str) – Name of the quantitative map to be added. This name will be used as a column name in the output dataframe.

  • norm (bool, optional) – Default False If True, the map will be normalized to have a mean of 0 and a standard deviation of 1 before being added to the object.

add_tissue(tissue_img, tissue_labels=None)[source]

Add a tissue segmentation image to the object. This segmentation should contain integer labels for each tissue type in the kidney where 0 is background. The labels will be used in the output dataframe. The tissue segmentation will be resampled to the space of the layers if the space parameter of the QLayers object is set to “layers” or the space of the quantitative maps added if the space parameter is set to “map”.

Parameters:

  • tissue_img (nibabel.nifti1.Nifti1Image) – Tissue segmentation image to be added to the object

  • tissue_labels (list of str, optional) – Default None List of text labels for each tissue type in the segmentation e.g. [“cortex”, “medulla”] if 1 in tissue_img represents renal cortex and 2 represents medulla. If None, the integer labels from tissue_img will be used.

get_depth()[source]

Returns distance from each voxel to the surface of the kidney as a numpy array.

Returns:

Distance from each voxel to the surface of the kidney

Return type:

numpy.ndarray

get_df(format='long')[source]

Returns a dataframe of all the quantitative maps added to the object with the depth/layer of each voxel.

Parameters:

format ({"wide", "long"}, optional) – Default “long” If “long”, the dataframe is returned in a long format where each row contains the depth, layer and a single quantitative measurement for a voxel. If “wide”, the dataframe is returned in a wide format where each row contains the depth, layer and all quantitative measurements for a voxel. This option is only available if the space parameter of the QLayers object is set to “layers”.

Returns:

Dataframe of all quantitative maps added to the object with the depth/layer of each voxel.

Return type:

pandas.DataFrame

get_layers()[source]

Returns layer of each voxel in the kidney as a numpy array.

Returns:

Layer of each voxel

Return type:

numpy.ndarray

remove_all_maps()[source]

Removes all quantitative maps from the object and resets the dataframe to only contain depth/layer information.

save_depth(fname)[source]

Saves the depth map as a nifti file.

Parameters:

fname (str) – Filename to save the depth map to.

save_layers(fname)[source]

Saves the layers as a nifti file.

Parameters:

fname (str) – Filename to save the layers to.

save_pelvis(fname)[source]

Saves the pelvis segmentation as a nifti file.

Parameters:

fname (str) – Filename to save the pelvis segmentation to.

save_surface(fname)[source]

Saves the kidney surface as a stl file.

Parameters:

fname (str) – Filename to save the kidney surface to.

to_pickle(fname)[source]

Saves the QLayers object as a pickle file.

Warning: The ability to import pickle files between Python versions is not guaranteed, as such this is not recommended for long term storage of QLayers objects!

Parameters:

fname (str) – Filename to save the QLayers to.

qlayers.quant_layers.load_pickle(fname)[source]

Load a pickle file containing a QLayers object.

Parameters:

fname (str) – Filename of the pickle file to load.

Returns:

The QLayers object stored in the pickle file.

Return type:

QLayers

qlayers.regression.slope(qlayers, maps='all', outer=5.0, inner=15.0, unit='mm', agg=<function nanmedian>)[source]

Explore the profiles produced by the layers algorithm. Calculate summary statistics for the outer layers, inner layers and the gradient between the two, these are similar to cortex, medulla and cortical-medullary difference respectively.

Parameters:

  • qlayers (QLayers) – The QLayers object containing the depth and quantitative map data.

  • maps (str or list of str, optional) – Default “all” The names of the maps to calculate the slope for. If “all”, all maps in the QLayers object are used.

  • outer (float, optional) – Default 5.0 The outer boundary of the depth range to calculate the slope within. This should be approximately the depth of the cortex. It can be specified in mm, percent of the maximum depth (i.e. between 0 and 100) or as a proportion of the maximum depth (i.e. between 0 and 1).

  • inner (float, optional) – Default 15.0 The inner boundary of the depth range to calculate the slope within. It can be specified in mm, percent of the maximum depth (i.e. between 0 and 100) or as a proportion of the maximum depth (i.e. between 0 and 1).

  • unit (str, optional) –

    The unit of the outer and inner parameters. Can be “mm”, “percent”,

    or “prop”. Default is “mm”.

  • agg (function, optional) – The aggregation function to use when calculating the summary value for the outer and inner regions. Default is np.median.

Returns:

A DataFrame containing the calculated slopes and other statistics for each map.

Return type:

pandas.DataFrame

qlayers.thickness.cortical_thickness(qlayers, est_error=False)[source]

Computes the cortical thickness of the kidneys.

Parameters:

  • qlayers (object) – The QLayers object.

  • est_error (bool, optional) – Default False If True, estimate the error in the cortical thickness, this is done using a stochastic approach. Lots of samples are drawn from the estimated parameters and the cortical thickness is calculated for each sample. The mean and standard deviation of the cortical thickness is returned. Estimating errors is therefore slow and off by default.

Returns:

  • thickness (float) – The cortical depth.

  • thickness_err (float) – The uncertainty in the cortical depth.

qlayers.thickness.equation_system(variable, L, x0, k, a, b, c)[source]

Equation system for logistic and Gaussian functions.

Parameters:

  • variable (float) – The variable to solve for.

  • L (float) – The curve’s maximum value for logistic function.

  • k (float) – The logistic growth rate or steepness of the curve for logistic function.

  • x0 (float) – The x-value of the sigmoid’s midpoint for logistic function.

  • a (float) – The height of the curve’s peak for Gaussian function.

  • b (float) – The position of the center of the peak for Gaussian function.

  • c (float) – Controls the width of the curve for Gaussian function.

Returns:

The difference between logistic and Gaussian functions.

Return type:

float

qlayers.thickness.estimate_gaussian_params(x, y)[source]

Estimates the parameters of a Gaussian function based on some sample data.

Parameters:

  • x (numpy.ndarray) – The x data.

  • y (numpy.ndarray) – The y data.

Returns:

  • params (numpy.ndarray) – The estimated parameters [a, b, c].

  • err (numpy.ndarray) – The uncertainty in the estimated parameters.

qlayers.thickness.estimate_logistic_params(x, y)[source]

Estimates the parameters of a logistic function based on some sample data.

Parameters:

  • x (numpy.ndarray) – The x data.

  • y (numpy.ndarray) – The y data.

Returns:

  • params (numpy.ndarray) – The estimated parameters [L, x0, k].

  • err (numpy.ndarray) – The uncertainty in the estimated parameters.

qlayers.thickness.gaussian(x, a, b, c)[source]

Gaussian function.

Parameters:

  • x (numpy.ndarray) – The input array.

  • a (float) – The height of the curve’s peak.

  • b (float) – The position of the center of the peak.

  • c (float) – Controls the width of the curve.

Returns:

The Gaussian function applied to x.

Return type:

numpy.ndarray

qlayers.thickness.logistic(x, L, x0, k)[source]

Logistic function.

Parameters:

  • x (numpy.ndarray) – The input array.

  • L (float) – The curve’s maximum value.

  • x0 (float) – The x-value of the sigmoid’s midpoint.

  • k (float) – The logistic growth rate or steepness of the curve.

Returns:

The logistic function applied to x.

Return type:

numpy.ndarray