dosma.tissues package

Submodules

dosma.tissues.femoral_cartilage module

class dosma.tissues.femoral_cartilage.FemoralCartilage(weights_dir=None, medial_to_lateral=None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for femoral cartilage.

This class extends functionality from Tissue.

For visualization, the femoral cartilage is unrolled onto a 2D plane using angular binning [1].

References

[1] Monu UD, Jordan CD, Samuelson BL, Hargreaves BA, Gold GE, McWalter EJ. Cluster analysis of quantitative MRI T2 and \(T1\rho\) relaxation times of cartilage identifies differences between healthy and ACL-injured individuals at 3T.” Osteoarthritis and cartilage 2017;25(4):513-520.

ACP_BOUNDARY = None

FULL_NAME = 'femoral cartilage'

ID = 1

ML_BOUNDARY = None

STR_ID = 'fc'

T1_EXPECTED = 1200

save_data(save_dirpath, data_format: dosma.data_io.format_io.ImageDataFormat = <ImageDataFormat.nifti: 1>)

Save data for tissue.

Saves mask and quantitative values associated with this tissue.

Override in subclasses to save additional data. When overriding in subclasses, call super().save_data(save_dirpath) first to save mask and quantitative values by default. See dosma.tissues.femoral_cartilage for details.

Parameters

• save_dirpath (str) – Directory path where all data is stored.

• data_format (ImageDataFormat, optional) – Format to save data.

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Mask is cleaned by selecting the largest connected component from the mask.

Femoral cartilage is expected to be single connected tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map: numpy.ndarray, thickness_divisor=0.5, num_bins=72, theta=(- 270, 90))

Split volume into anatomical regions.

Pixels corresponding to femoral cartilage are divided across 3 planes:

• Coronal: Posterior, Central, or Anterior

• Sagittal: Medial, Lateral

• Axial: Deep, Superficial

For example, a pixel could correspond to the Posterior Lateral Deep region of

femoral cartilage.

Parameters

base_map (np.ndarray) – 3D numpy array typically corresponding to volume to split.

Returns

4D numpy array (region, height, width, depth).

Saved in variable self.regions.

Return type

np.ndarray

unroll(qv_map: numpy.ndarray, regions_mask: numpy.ndarray, theta_bins)

Unroll femoral cartilage 3D quantitative value (qv) maps to 2D for visualization.

The function multiplies a 3D segmentation mask to a 3D qv map to produce a 3D femoral cartilage qv (fc_qv) map. It then fits a circle to the collapsed sagittal projection of the fc_qv map. Each slice is binned into bins of 5 degree sizes

The unrolled map is then divided into deep and superficial cartilage.

Parameters

qv_map (np.ndarray) – 3D array (slices last) of sagittal knee describing quantitative parameter values regions_mask (np.ndarray): regions_mask

Returns

(row, column) format

1. 2D Total unrolled cartilage (slices, degrees) - average of superficial

   and deep layers

2. Superficial unrolled cartilage (slices, degrees) - superficial layer

3. Deep unrolled cartilage (slices, degrees) - deep layer

Return type

tuple

dosma.tissues.meniscus module

Analysis for meniscus.

ivar ~dosma.tissues.meniscus.BOUNDS

Upper bounds for quantitative values.

vartype ~dosma.tissues.meniscus.BOUNDS

dict

class dosma.tissues.meniscus.Meniscus(weights_dir: Optional[str] = None, medial_to_lateral: Optional[bool] = None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for meniscus.

This class extends functionality from Tissue.

For visualization, the meniscus is unrolled across the axial plane.

FULL_NAME = 'meniscus'

ID = 2

STR_ID = 'men'

T1_EXPECTED = 1000

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Split mask into anatomical regions.

Parameters

base_map (np.ndarray) – 3D numpy array typically corresponding to volume to split.

Returns

4D numpy array (region, height, width, depth).

Saved in variable self.regions.

Return type

np.ndarray

unroll_axial(quant_map: numpy.ndarray)

Unroll meniscus in axial direction.

Parameters

quant_map (np.ndarray) – Map to roll out.

dosma.tissues.patellar_cartilage module

Analysis for patellar cartilage.

ivar ~dosma.tissues.patellar_cartilage.BOUNDS

Upper bounds for quantitative values.

vartype ~dosma.tissues.patellar_cartilage.BOUNDS

dict

class dosma.tissues.patellar_cartilage.PatellarCartilage(weights_dir: Optional[str] = None, medial_to_lateral: Optional[bool] = None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for patellar cartilage.

FULL_NAME = 'patellar cartilage'

ID = 3

STR_ID = 'pc'

T1_EXPECTED = 1000

set_mask(mask)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Split patellar cartilage into deep/superficial regions.

For patellar cartilage, the superficial/deep transition occurs in the anterior/posterior (A/P) direction. The boundary is determined for each non-zero 1D column spanning independently by the local center-of-mass (COM). The medial/lateral (M/L) plane is computed using the global COM.

Parameters

base_map (ndarray) – Binary 3D mask with orientation (SI, AP, ML/LM). If self.medial_to_lateral, last dimension should be ML.

unroll_coronal(quant_map: numpy.ndarray)

Unroll patellar cartilage in the coronal direction.

Because patellar cartilage is flat, “unrolling” is projecting the patellar cartilage onto the coronal axis.

Parameters

quant_map (np.ndarray) –

dosma.tissues.tibial_cartilage module

Analysis for tibial cartilage.

ivar ~dosma.tissues.tibial_cartilage.BOUNDS

Upper bounds for quantitative values.

vartype ~dosma.tissues.tibial_cartilage.BOUNDS

dict

class dosma.tissues.tibial_cartilage.TibialCartilage(weights_dir=None, medial_to_lateral=None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for tibial cartilage.

FULL_NAME = 'tibial cartilage'

ID = 4

STR_ID = 'tc'

T1_EXPECTED = 1000

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Generate subregions for tibial cartilage.

Tibial cartilage is split into subregions along the 3 major axes: superior/inferior (S/I), anterior/posterior (A/P), medial/lateral (M/L). M/L plateaus are computed with respect to the center of mass (COM) in the sagittal direction. A/C/P divisions are computed independently for each plateau using thirds of the distance between the minimum/maximum pixel in the A/P direction. S/I divisions are computed based on local COM for each 1D column with tissues in the S/I direction.

The output is stored in self.regions_mask.

Note

Previously, COM was used to split A/P subregions. However, COM is not as robust to split the data into 3 subregions. We use the method described in the reference below: A/C/P are split by thirds of the distance between the minimum/maximum pixel in the A/P direction. Note the minimum/maximum pixel method may not be a robust if there are a sufficient number of erroneous pixels. We do not sufficiently correct for erroneous pixels.

Parameters

base_map (ndarray) – Binary 3D mask with orientation (SI, AP, ML/LM). If self.medial_to_lateral, last dimension should be ML.

References

Black, MS et al. Detecting Early Changes in ACL-Reconstructed Knees: Cluster Analysis of T2 Relaxation Times from 3 Months to 18 Months Post-Surgery. 28th Annual Meeting of ISMRM, Sydney, Australia 2020.

unroll_axial(quant_map)

dosma.tissues.tissue module

class dosma.tissues.tissue.Tissue(weights_dir: Optional[str] = None, medial_to_lateral: Optional[bool] = None)

Bases: abc.ABC

Abstract class for tissues.

Tissues are defined loosely as any tissue structures (bones, soft tissue, etc.).

Parameters

• weights_dir (str) – Directory to all segmentation weights.

• medial_to_lateral (bool, optional) – If True, anatomy is from medial_to_lateral.

Variables

• FULL_NAME (str) – Full name of tissue ‘femoral cartilage’ for femoral cartilage.

• ID (int) – Unique integer ID for tissue. Should be unique to all tissues, and should not change.

• STR_ID (str) – Short hand string id such as ‘fc’ for femoral cartilage.

• T1_EXPECTED (float) – Expected T1 value (in milliseconds).

• medial_to_lateral (bool) – If True, mask is in medial to lateral direction.

• pid (str) – Patient/subject ID. Should be anonymized.

• quant_vals (dict[str, tuple[np.ndarray, pd.DataFrame]]) – Mapping from quantitative value name (t2, t1-rho, etc.) to tuple of unrolled map and DataFrame containing measurement values.

• weights_filepath (str) – File path to weights directory for neural network segmentation.

FULL_NAME = ''

ID = -1

STR_ID = ''

T1_EXPECTED = None

add_quantitative_value(qv_new: dosma.quant_vals.QuantitativeValue)

Add quantitative value to the tissue.

Parameters

qv_new (QuantitativeValue) – Quantitative value to add to tissue.

calc_quant_vals()

Calculate quantitative values for pixels corresponding to the tissue.

Requires mask to be set for this tissue.

find_weights(weights_dir: str)

Search for weights file in weights directory.

Parameters

weights_dir (str) – Directory where weights are stored.

Returns

File path to weights corresponding to tissue.

Return type

str

Raises

ValueError – If multiple weights files exists for the tissue or no valid weights file found.

get_mask()

Returns

Binary mask of segmented tissue.

Return type

MedicalVolume

load_data(load_dir_path: str)

Load data for tissue.

All tissue information is based on the mask. If mask for tissue doesn’t exist, there is no information to load.

Parameters

load_dir_path (str) – Directory path where all data is stored.

save_data(save_dirpath: str, data_format: dosma.data_io.format_io.ImageDataFormat = <ImageDataFormat.nifti: 1>)

Save data for tissue.

Saves mask and quantitative values associated with this tissue.

Override in subclasses to save additional data. When overriding in subclasses, call super().save_data(save_dirpath) first to save mask and quantitative values by default. See dosma.tissues.femoral_cartilage for details.

Parameters

• save_dirpath (str) – Directory path where all data is stored.

• data_format (ImageDataFormat, optional) – Format to save data.

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

abstract split_regions(base_map: numpy.ndarray)

Split mask into anatomical regions.

Parameters

base_map (np.ndarray) – 3D numpy array typically corresponding to volume to split.

Returns

4D numpy array (region, height, width, depth).

Saved in variable self.regions.

Return type

np.ndarray

Module contents

class dosma.tissues.FemoralCartilage(weights_dir=None, medial_to_lateral=None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for femoral cartilage.

This class extends functionality from Tissue.

For visualization, the femoral cartilage is unrolled onto a 2D plane using angular binning [1].

References

[1] Monu UD, Jordan CD, Samuelson BL, Hargreaves BA, Gold GE, McWalter EJ. Cluster analysis of quantitative MRI T2 and \(T1\rho\) relaxation times of cartilage identifies differences between healthy and ACL-injured individuals at 3T.” Osteoarthritis and cartilage 2017;25(4):513-520.

ACP_BOUNDARY = None

FULL_NAME = 'femoral cartilage'

ID = 1

ML_BOUNDARY = None

STR_ID = 'fc'

T1_EXPECTED = 1200

save_data(save_dirpath, data_format: dosma.data_io.format_io.ImageDataFormat = <ImageDataFormat.nifti: 1>)

Save data for tissue.

Saves mask and quantitative values associated with this tissue.

Override in subclasses to save additional data. When overriding in subclasses, call super().save_data(save_dirpath) first to save mask and quantitative values by default. See dosma.tissues.femoral_cartilage for details.

Parameters

• save_dirpath (str) – Directory path where all data is stored.

• data_format (ImageDataFormat, optional) – Format to save data.

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Mask is cleaned by selecting the largest connected component from the mask.

Femoral cartilage is expected to be single connected tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map: numpy.ndarray, thickness_divisor=0.5, num_bins=72, theta=(- 270, 90))

Split volume into anatomical regions.

Pixels corresponding to femoral cartilage are divided across 3 planes:

• Coronal: Posterior, Central, or Anterior

• Sagittal: Medial, Lateral

• Axial: Deep, Superficial

For example, a pixel could correspond to the Posterior Lateral Deep region of

femoral cartilage.

Parameters

base_map (np.ndarray) – 3D numpy array typically corresponding to volume to split.

Returns

4D numpy array (region, height, width, depth).

Saved in variable self.regions.

Return type

np.ndarray

unroll(qv_map: numpy.ndarray, regions_mask: numpy.ndarray, theta_bins)

Unroll femoral cartilage 3D quantitative value (qv) maps to 2D for visualization.

The function multiplies a 3D segmentation mask to a 3D qv map to produce a 3D femoral cartilage qv (fc_qv) map. It then fits a circle to the collapsed sagittal projection of the fc_qv map. Each slice is binned into bins of 5 degree sizes

The unrolled map is then divided into deep and superficial cartilage.

Parameters

qv_map (np.ndarray) – 3D array (slices last) of sagittal knee describing quantitative parameter values regions_mask (np.ndarray): regions_mask

Returns

(row, column) format

1. 2D Total unrolled cartilage (slices, degrees) - average of superficial

   and deep layers

2. Superficial unrolled cartilage (slices, degrees) - superficial layer

3. Deep unrolled cartilage (slices, degrees) - deep layer

Return type

tuple

class dosma.tissues.Meniscus(weights_dir: Optional[str] = None, medial_to_lateral: Optional[bool] = None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for meniscus.

This class extends functionality from Tissue.

For visualization, the meniscus is unrolled across the axial plane.

FULL_NAME = 'meniscus'

ID = 2

STR_ID = 'men'

T1_EXPECTED = 1000

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Split mask into anatomical regions.

Parameters

base_map (np.ndarray) – 3D numpy array typically corresponding to volume to split.

Returns

4D numpy array (region, height, width, depth).

Saved in variable self.regions.

Return type

np.ndarray

unroll_axial(quant_map: numpy.ndarray)

Unroll meniscus in axial direction.

Parameters

quant_map (np.ndarray) – Map to roll out.

class dosma.tissues.PatellarCartilage(weights_dir: Optional[str] = None, medial_to_lateral: Optional[bool] = None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for patellar cartilage.

FULL_NAME = 'patellar cartilage'

ID = 3

STR_ID = 'pc'

T1_EXPECTED = 1000

set_mask(mask)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Split patellar cartilage into deep/superficial regions.

For patellar cartilage, the superficial/deep transition occurs in the anterior/posterior (A/P) direction. The boundary is determined for each non-zero 1D column spanning independently by the local center-of-mass (COM). The medial/lateral (M/L) plane is computed using the global COM.

Parameters

base_map (ndarray) – Binary 3D mask with orientation (SI, AP, ML/LM). If self.medial_to_lateral, last dimension should be ML.

unroll_coronal(quant_map: numpy.ndarray)

Unroll patellar cartilage in the coronal direction.

Because patellar cartilage is flat, “unrolling” is projecting the patellar cartilage onto the coronal axis.

Parameters

quant_map (np.ndarray) –

class dosma.tissues.TibialCartilage(weights_dir=None, medial_to_lateral=None)

Bases: dosma.tissues.tissue.Tissue

Handles analysis and visualization for tibial cartilage.

FULL_NAME = 'tibial cartilage'

ID = 4

STR_ID = 'tc'

T1_EXPECTED = 1000

set_mask(mask: dosma.data_io.med_volume.MedicalVolume)

Set mask for tissue.

Parameters

mask (MedicalVolume) – Binary mask of segmented tissue.

split_regions(base_map)

Generate subregions for tibial cartilage.

Tibial cartilage is split into subregions along the 3 major axes: superior/inferior (S/I), anterior/posterior (A/P), medial/lateral (M/L). M/L plateaus are computed with respect to the center of mass (COM) in the sagittal direction. A/C/P divisions are computed independently for each plateau using thirds of the distance between the minimum/maximum pixel in the A/P direction. S/I divisions are computed based on local COM for each 1D column with tissues in the S/I direction.

The output is stored in self.regions_mask.

Note

Previously, COM was used to split A/P subregions. However, COM is not as robust to split the data into 3 subregions. We use the method described in the reference below: A/C/P are split by thirds of the distance between the minimum/maximum pixel in the A/P direction. Note the minimum/maximum pixel method may not be a robust if there are a sufficient number of erroneous pixels. We do not sufficiently correct for erroneous pixels.

Parameters

base_map (ndarray) – Binary 3D mask with orientation (SI, AP, ML/LM). If self.medial_to_lateral, last dimension should be ML.

References

Black, MS et al. Detecting Early Changes in ACL-Reconstructed Knees: Cluster Analysis of T2 Relaxation Times from 3 Months to 18 Months Post-Surgery. 28th Annual Meeting of ISMRM, Sydney, Australia 2020.

unroll_axial(quant_map)