The Group class#

class rockverse.dualenergyct.DualEnergyCTGroup(store, overwrite=False, **kwargs)[source]#

Parallel CPU GPU

Manages Dual Energy Computed Tomography (DECT) processing. The workflow is described in the original research paper. This class builds upon Zarr groups and is adapted for MPI (Message Passing Interface) processing, allowing for parallel computation across multiple CPUs or GPUs.

Parameters:

store (str) – Zarr store where the underlying Zarr group will be created.
overwrite (bool) – If True, deletes all data under store and creates a new group.
**kwargs – Additional keyword arguments for Zarr group creation.

Attribute summary#

Voxel image

`lowECT`	The low energy computed tomography voxel image.
`highECT`	The high energy computed tomography voxel image.
`mask`	The mask voxel image.
`segmentation`	The segmentation voxel image.
`rho_min`	Voxel image with the minimum electron density per voxel.
`rho_p25`	Voxel image with the the first quartile for the electron density values per voxel (Q1 or 25th percentile) from the Monte Carlo inversion.
`rho_p50`	Voxel image with the the median values for the electron density per voxel (Q2 or 50th percentile) from the Monte Carlo inversion.
`rho_p75`	Voxel image with the the third quartile for the electron density values per voxel (Q3 or 75th percentile) from the Monte Carlo inversion.
`rho_max`	Voxel image with the maximum electron density per voxel.
`Z_min`	Voxel image with the minimum effective atomic number per voxel.
`Z_p25`	Voxel image with the the first quartile for the effective atomic number values per voxel (Q1 or 25th percentile) from the Monte Carlo inversion.
`Z_p50`	Voxel image with the the median values for the effective atomic number per voxel (Q2 or 50th percentile) from the Monte Carlo inversion.
`Z_p75`	Voxel image with the the third quartile for the effective atomic number values per voxel (Q3 or 75th percentile) from the Monte Carlo inversion.
`Z_max`	Voxel image with the maximum effective atomic number per voxel.
`valid`	Voxel image with the number of valid Monte Carlo results for each voxel.

Histograms

`histogram_bins`	Number of equal-width histogram bins for the CT images.
`lowEhistogram`	Histogram count for the low energy image as a Pandas DataFrame.
`highEhistogram`	Histogram count for the high energy image as a Pandas DataFrame.

Calibration parameters

`calibration_material0`	Dictionary-like object with the properties for calibration_material0 (empty region).
`calibration_material1`	Dictionary-like object with the properties for calibration_material1.
`calibration_material2`	Dictionary-like object with the properties for calibration_material2.
`calibration_material3`	Dictionary-like object with the properties for calibration_material3.
`calibration_gaussian_coefficients`	A Pandas DataFrame with the fitting coefficients `[A, mu, sigma]` for the calibration materials in the low and high energy CT images, according to the model
`periodic_table`	Class with atomic number and atomic mass values to be used in the Monte Carlo inversion.
`maxA`	Maximum value for coefficient A in broad search.
`maxB`	Maximum value for coefficient B in broad search.
`maxn`	Maximum value for coefficient n in broad search.
`lowE_inversion_coefficients`	Pandas DataFrame with the realization sets for low energy inversion coefficients.
`highE_inversion_coefficients`	Pandas DataFrame with the realization sets for high energy inversion coefficients.

Inversion parameters

`tol`	Tolerance value for terminating the Newton-Raphson optimizations.
`whis`	The boxplot whisker length for determining Monte Carlo outlier results.
`required_iterations`	The required number of valid Monte Carlo iterations for each voxel.
`maximum_iterations`	The maximum number of trials to get valid Monte Carlo iterations per voxel.
`threads_per_block`	Number of threads per block when processing using GPUs.
`hash_buffer_size`	(Integer) Number of array slices processed at once when calculating hashes.

Attributes#

DualEnergyCTGroup.calibration_gaussian_coefficients#: A Pandas DataFrame with the fitting coefficients [A, mu, sigma] for the calibration materials in the low and high energy CT images, according to the model

(1)#\[y = Ae^{-\frac{1}{2}\bigg(\frac{x-\mu}{\sigma}\bigg)^2}.\]

DualEnergyCTGroup.calibration_material0#

Dictionary-like object with the properties for calibration_material0 (empty region). The following keys must be set:

'description' - string describing calibration_material0. Will be used in the default plots.
'segmentation_phase' - segmentation phase in segmentation array defining the voxels belonging to calibration_material0.
'lowE_gaussian_center_bounds' - two-element list with lower and upper bounds for the gaussian center in the lowECT image histogram.
'highE_gaussian_center_bounds' - two-element list with lower and upper bounds for the gaussian center in the highECT image histogram.

DualEnergyCTGroup.calibration_material1#

Dictionary-like object with the properties for calibration_material1. The keys are the same as in calibration_material0, plus these additional ones:

'bulk_density' - bulk density for the calibration material, in g/cc.
'composition' - dictionary defining the chemical composition. Must be set as key: value pairs where key is the element symbol and value is the proportionate number of atoms of each element.

Examples:

Water H₂O:

path = r'/path/to/my/working/dir/dect'
dectgroup = rockverse.dualenergyct.create_group(path)
dectgroup.calibration_material1['description'] = 'Water'
dectgroup.calibration_material1['bulk_density'] = 1
dectgroup.calibration_material1['composition'] = {'H': 2, 'O': 1}

Silica SiO₂:

path = r'/path/to/my/working/dir/dect.zarr'
dectgroup = rockverse.dualenergyct.create_group(path)
dectgroup.calibration_material1['description'] = 'Silica'
dectgroup.calibration_material1['bulk_density'] = 2.2
dectgroup.calibration_material1['composition'] = {'Si': 1, 'O': 2}

Dolomite CaMg(CO₃)₂:

path = r'/path/to/my/working/dir/dect.zarr'
dectgroup = rockverse.dualenergyct.create_group(path)
dectgroup.calibration_material1['description'] = 'Dolomite'
dectgroup.calibration_material1['bulk_density'] = 2.84
dectgroup.calibration_material1['composition'] = {'Ca': 1, 'Mg': 1, 'C': 2, 'O': 6}

Teflon (C₂F₄)_n:

path = r'/path/to/my/working/dir/dect.zarr'
dectgroup = rockverse.dualenergyct.create_group(path)
dectgroup.calibration_material1['description'] = 'Teflon'
dectgroup.calibration_material1['composition'] = {'C': 2, 'F': 4}
dectgroup.calibration_material1['bulk_density'] = 2.2

DualEnergyCTGroup.calibration_material2#: Dictionary-like object with the properties for calibration_material2. See calibration_material1 for details.

DualEnergyCTGroup.calibration_material3#: Dictionary-like object with the properties for calibration_material3. See calibration_material1 for details.

DualEnergyCTGroup.hash_buffer_size#

(Integer) Number of array slices processed at once when calculating hashes.

The array hashes are not calculated all at once, but updated using a number of slices at a time, given by the hash_buffer_size parameter. Higher values for hash_buffer_size will speed up the hashing operation but require more RAM, while lower values require less memory but slow down the hashing operation due to the need to access the file system more times. Default value of 100 should be a good compromise in most cases.

DualEnergyCTGroup.highECT#: The high energy computed tomography voxel image. Returns None if not set. Can only be changed through the array creation methods.

DualEnergyCTGroup.highE_inversion_coefficients#: Pandas DataFrame with the realization sets for high energy inversion coefficients. Returns None if not calculated.

DualEnergyCTGroup.highEhistogram#: Histogram count for the high energy image as a Pandas DataFrame. Return None if highECT is not set.

DualEnergyCTGroup.histogram_bins#: Number of equal-width histogram bins for the CT images. Must be a positive integer.

DualEnergyCTGroup.lowECT#: The low energy computed tomography voxel image. Returns None if not set. Can only be changed through the array creation methods.

DualEnergyCTGroup.lowEhistogram#: Histogram count for the low energy image as a Pandas DataFrame. Return None if lowECT is not set.

DualEnergyCTGroup.lowE_inversion_coefficients#: Pandas DataFrame with the realization sets for low energy inversion coefficients. Returns None if not calculated.

DualEnergyCTGroup.mask#: The mask voxel image. Returns None if not set. Masked voxels will be ignored during the Monte Carlo inversion and histogram calculations. Can only be changed through the array creation methods.

DualEnergyCTGroup.maxA#: Maximum value for coefficient A in broad search.

DualEnergyCTGroup.maxB#: Maximum value for coefficient B in broad search.

DualEnergyCTGroup.maximum_iterations#: The maximum number of trials to get valid Monte Carlo iterations per voxel. Default value is 50000. Recommended 10 times the required number of valid Monte Carlo iterations.

DualEnergyCTGroup.maxn#: Maximum value for coefficient n in broad search.

DualEnergyCTGroup.periodic_table#: Class with atomic number and atomic mass values to be used in the Monte Carlo inversion. See the details in PeriodicTable documentation.

DualEnergyCTGroup.required_iterations#: The required number of valid Monte Carlo iterations for each voxel. Default value is 5000.

DualEnergyCTGroup.rho_max#: Voxel image with the maximum electron density per voxel. Maximum value is taken as the upper boxplot whisker boundary from the Monte Carlo inversion.

DualEnergyCTGroup.rho_min#: Voxel image with the minimum electron density per voxel. Minimum value is taken as the lower boxplot whisker boundary from the Monte Carlo inversion.

DualEnergyCTGroup.rho_p25#: Voxel image with the the first quartile for the electron density values per voxel (Q1 or 25th percentile) from the Monte Carlo inversion.

DualEnergyCTGroup.rho_p50#: Voxel image with the the median values for the electron density per voxel (Q2 or 50th percentile) from the Monte Carlo inversion.

DualEnergyCTGroup.rho_p75#: Voxel image with the the third quartile for the electron density values per voxel (Q3 or 75th percentile) from the Monte Carlo inversion.

DualEnergyCTGroup.segmentation#: The segmentation voxel image. Returns None if not set. This array is used to locate the calibration materials in the image and calculate histograms. Can only be changed through the array creation methods.

DualEnergyCTGroup.threads_per_block#: Number of threads per block when processing using GPUs. Use it for fine-tuning GPU performance based on your specific GPU capabilities. Default value is 4.

DualEnergyCTGroup.tol#: Tolerance value for terminating the Newton-Raphson optimizations. Default value is 1e-12.

DualEnergyCTGroup.valid#: Voxel image with the number of valid Monte Carlo results for each voxel.

DualEnergyCTGroup.whis#: The boxplot whisker length for determining Monte Carlo outlier results. Minimum values will be at least \(Q_1-whis(Q_3-Q_2)\) and maximum values will be at most \(Q_3+whis(Q_3-Q_2)\), where \(Q_1\), \(Q_2\), and \(Q_3\) are the three quartiles for the Monte Carlo results. Default value is 1.5.

DualEnergyCTGroup.Z_max#: Voxel image with the maximum effective atomic number per voxel. Maximum value is taken as the upper boxplot whisker boundary from the Monte Carlo inversion.

DualEnergyCTGroup.Z_min#: Voxel image with the minimum effective atomic number per voxel. Minimum value is taken as the lower boxplot whisker boundary from the Monte Carlo inversion.

DualEnergyCTGroup.Z_p25#: Voxel image with the the first quartile for the effective atomic number values per voxel (Q1 or 25th percentile) from the Monte Carlo inversion.

DualEnergyCTGroup.Z_p50#: Voxel image with the the median values for the effective atomic number per voxel (Q2 or 50th percentile) from the Monte Carlo inversion.

DualEnergyCTGroup.Z_p75#: Voxel image with the the third quartile for the effective atomic number values per voxel (Q3 or 75th percentile) from the Monte Carlo inversion.

Methods summary#

Handling arrays

`copy_image`(image, path, **kwargs)	Copy an existing voxel image into the DECT group.
`create_mask`([fill_value, overwrite, ...])	Create a mask voxel image based on the lowECT one.
`delete_mask`()	Remove the mask array from the structure.
`create_segmentation`([fill_value, dtype, ...])	Create segmentation voxel image based on the lowECT array.

Monte Carlo Inversion

`check`(*[, verbose])	Check the group structure for consistency and dependencies among arrays and processing parameters.
`preprocess`([restart])	Perform preprocessing steps for Dual Energy Computed Tomography analysis:
`run`([restart])	Run the DECT analysis on the data in this group.

Methods#

DualEnergyCTGroup.copy_image(image, path, **kwargs)[source]#

Copy an existing voxel image into the DECT group.

Parameters:

image (VoxelImage) – The original voxel image to be copied.
path ({'lowECT', 'highECT', 'mask', 'segmentation'}) – The path within the DECT group where the array will be stored.

DualEnergyCTGroup.create_mask(fill_value=False, overwrite=False, field_name='mask', description='Mask voxel image', **kwargs)[source]#

Create a mask voxel image based on the lowECT one. This function enforces boolean dtype and the path ‘/mask’ within the group store. These parameters will be ignored if passed as keyword arguments.

Parameters:

fill_value (bool, optional) – The value to fill the mask with (default is False).
overwrite (bool, optional) – If True, overwrite existing mask (default is False).
**kwargs – Additional keyword arguments for the drp.full_like function used to create the mask array.

DualEnergyCTGroup.create_segmentation(fill_value=0, dtype='u1', overwrite=False, field_name='segmentation', description='Segmentation voxel image', **kwargs)[source]#

Create segmentation voxel image based on the lowECT array. This function enforces unsigned integer dtype and the path ‘/segmentation’ within the group store.

Parameters:

fill_value (bool, optional) – The value to fill the mask with.
dtype (Numpy datatype) – Array data type. Must be unsigned integer.
overwrite (bool, optional) – If True, overwrite existing segmentation.
**kwargs – Additional keyword arguments for the drp.full_like function used to create the segmentation array.

DualEnergyCTGroup.delete_mask()[source]#: Remove the mask array from the structure.

DualEnergyCTGroup.run(restart=False)[source]#

Run the DECT analysis on the data in this group.

This method performs the following steps: 1. Runs preprocessing steps (histograms, Gaussian fitting, coefficient matrices). 2. Checks if output arrays exist and are up-to-date. 3. Creates or updates output arrays as necessary. 4. Calculates the electron density (rho) and effective atomic number (Z) distributions using Monte Carlo simulations.

Parameters:: restart (bool, optional) – If True, force recalculation of all steps, ignoring existing results. Default is False.

The Group class#

Attribute summary#

Attributes#

Methods summary#

Methods#

This Page