cerr package

Subpackages

Submodules

cerr.dvh module

cerr.dvh.getDVH(structNum, doseNum, planC)[source]

Routine to calculate Dose and Volume vectors to be used for Histogram calculation

Parameters:

  • structNum (int) – Binary mask where 1s represent the segmentation

  • doseNum (int) – x-values i.e. coordinates of columns of input mask

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object

Returns:

vector of dose values for voxels in structNum List (volsV): vector of volumes corresponding to voxels in dosesV int (isError): error flag. 0: No error, 1: error in calculation

Return type:

List (dosesV)

cerr.dvh.accumulate(V1, V2, indV)[source]

Accumulate values from V2 into V1 at positions specified by indV.

For each element in V2, adds its value to V1 at the corresponding index given by indV. Operates in-place and also returns the modified V1.

Parameters:

  • V1 (np.ndarray) – Target array that will be updated in-place.

  • V2 (np.ndarray) – Source values to add into V1.

  • indV (np.ndarray) – Integer index array; indV[i] is the position in V1 where V2[i] should be accumulated.

Returns:

The updated V1 array.

Return type:

np.ndarray

cerr.dvh.doseHist(doseV, volsV, binWidth)[source]

Routine to calculate Dose Volume Histogram from input dose and volume vectors

Parameters:

  • doseV (List) – vector of dose values for voxels in structNum

  • volsV (List) – vector of volumes corresponding to voxels in dosesV

  • binWidth (float) – Bin-width of dose bins.

Returns:

vector of dose bin centers. List (volsHistV): vector of volumes accumulated in corresponding dose bins.

Return type:

List (doseBinsV)

cerr.dvh.MOHx(doseBinsV, volsHistV, percent)[source]

This routine computes the mean of hottest x% dose.

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

  • percent (float) – cutoff in terms of percentage. (e.g. 90)

Returns:

mean of the hottest x% dose

Return type:

Float

cerr.dvh.MOCx(doseBinsV, volsHistV, percent)[source]

This routine computes the mean of coldest x% dose.

doseBinsV: (List): vector of dose bin centers. volsHistV (List): vector of volumes accumulated in corresponding dose bins. percent (float): cutoff in terms of percentage. (e.g. 10)

Returns:

mean of the coldest x% dose

Return type:

Float

cerr.dvh.Vx(doseBinsV, volsHistV, doseCutoff, volumeType=None)[source]

This routine computes the volume receiving at least x dose.

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

  • doseCutoff – dose cutoff in Gy.

  • volumeType (int) – 0: Return output volume as absolute cc. 1: Return output volume as percentage.

Returns:

Volume (absolute ot percentage)

Return type:

Float

cerr.dvh.Dx(doseBinsV, volsHistV, volCutoff, volumeType=None)[source]

” This routine computes the minimum dose to the hottest x% volume.

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

  • volCutoff – volume cutoff in cc or percentage.

  • volumeType (int) – 0: volume is input in absolute cc. 1: volume is input in percentage.

Returns:

Volume (absolute ot percentage)

Return type:

Float

cerr.dvh.meanDose(doseBinsV, volsHistV)[source]

This routine computes the mean dose

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

Returns:

Mean dose

Return type:

Float

cerr.dvh.minDose(doseBinsV, volsHistV)[source]

This routine computes the minimum dose

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

Returns:

Minimum dose

Return type:

Float

cerr.dvh.maxDose(doseBinsV, volsHistV)[source]

This routine computes the maximum dose

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

Returns:

Maximum dose

Return type:

Float

cerr.dvh.medianDose(doseBinsV, volsHistV)[source]

This routine computes the median dose

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

Returns:

Median dose

Return type:

Float

cerr.dvh.eud(doseBinsV, volsHistV, exponent)[source]

This routine computes the equivalent uniform dose given DVH and exponent.

Parameters:

  • doseBinsV – (List): vector of dose bin centers.

  • volsHistV (List) – vector of volumes accumulated in corresponding dose bins.

  • exponent (int) – exponent.

Returns:

EUD

Return type:

Float

cerr.multiViewHelper module

Multiple viewer widget

This is an example on how to have more than one viewer in the same napari window. Additional viewers state will be synchronized with the main viewer. Switching to 3D display will only impact the main viewer.

This example also contain option to enable cross that will be moved to the current dims point (viewer.dims.point).

cerr.multiViewHelper.copy_layer_le_4_16(layer: napari.layers.Layer, name: str = '')[source]
cerr.multiViewHelper.copy_layer(layer: napari.layers.Layer, name: str = '')[source]
cerr.multiViewHelper.get_property_names(layer: napari.layers.Layer)[source]
cerr.multiViewHelper.center_cross_on_mouse(viewer_model: napari.components.viewer_model.ViewerModel)[source]

move the cross to the mouse position

class cerr.multiViewHelper.own_partial(func, *args, **kwargs)[source]

Bases: object

Workaround for deepcopy not copying partial functions (Qt widgets are not serializable)

class cerr.multiViewHelper.QtViewerWrap(*args: Any, **kwargs: Any)[source]

Bases: QtViewer

class cerr.multiViewHelper.CrossWidget(*args: Any, **kwargs: Any)[source]

Bases: QCheckBox

Widget to control the cross layer. because of the performance reason the cross update is throttled

update_cross()[source]
class cerr.multiViewHelper.ExampleWidget(*args: Any, **kwargs: Any)[source]

Bases: QWidget

Dummy widget showcasing how to place additional widgets to the right of the additional viewers.

class cerr.multiViewHelper.MultipleViewerWidget(*args: Any, **kwargs: Any)[source]

Bases: QSplitter

The main widget of the example.

cerr.plan_container module

This module defines the container class PlanC and methods to import metadata from DICOM and NifTI formats.

cerr.plan_container.get_empty_list()[source]

Return an empty list, used as a default factory for dataclass fields.

Returns:

An empty list.

Return type:

list

class cerr.plan_container.PlanC(header: Header = None, scan: List[Scan] = <factory>, structure: List[Structure] = <factory>, dose: List[Dose] = <factory>, beams: List[Beams] = <factory>, deform: List[Deform] = <factory>)[source]

Bases: object

Plan Container for imaging metadata. Each Attribute of this class holds metadata for a particular type of imaging object. Additional attributes can be added to this class without breaking the functionality from other attributes.

header

Header storing information about date of creation, version etc.

Type:

cerr.dataclasses.header.Header

scan

List of pyCERR’s scan objects for modalities such as CT, MR, PT or derived types.

Type:

List[cerr.dataclasses.scan.Scan]

structure

List of pyCERR’s structure objects for modalities such as RTSTRUCT, SEG or user defined segmentation masks.

Type:

List[cerr.dataclasses.structure.Structure]

dose

List of pyCERR’s dose objects for RTDOSE modality.

Type:

List[cerr.dataclasses.dose.Dose]

beams

List of pyCERR’s beams objects for RTPLAN modality.

Type:

List[cerr.dataclasses.beams.Beams]

deform

(List[cerr.dataclasses.deform.Deform]): List of pyCERR’s deformable image registration objects.

Type:

List[cerr.dataclasses.deform.Deform]

header: Header = None
scan: List[Scan]
structure: List[Structure]
dose: List[Dose]
beams: List[Beams]
deform: List[Deform]
addScan(new_scan) -> Field(name='scan',type=typing.List[cerr.dataclasses.scan.Scan],default=<dataclasses._MISSING_TYPE object at 0x7d1cf0128380>,default_factory=<function get_empty_list at 0x7d1ce7155f80>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)[source]

Append a new scan object to the plan container’s scan list.

Parameters:

new_scan (cerr.dataclasses.scan.Scan) – The scan object to add.

class json_serialize(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: JSONEncoder

default(obj)[source]

Serialize pyCERR dataclass objects to JSON-compatible representations.

Parameters:

obj – The object to serialize. Handled types are cerr.dataclasses.scan.Scan, cerr.dataclasses.dose.Dose, and cerr.dataclasses.structure.Structure.

Returns:

A dictionary containing the object’s UID, or an empty

string for unrecognized types.

Return type:

dict

cerr.plan_container.getSortedItems(itemList)[source]

Sort a list of H5 group-item names of the form Item_N by their numeric suffix.

Parameters:

itemList (list) – List of strings such as ['Item_2', 'Item_0', 'Item_1'].

Returns:

The same items sorted in ascending numeric order, or the original

list unchanged if it is empty.

Return type:

list

cerr.plan_container.addToH5Grp(h5Grp, structDict, key)[source]

Write a single key from a dictionary into an HDF5 group as an attribute or dataset.

Scalar strings and numbers are stored as HDF5 attributes; lists and arrays are stored as compressed HDF5 datasets.

Parameters:

  • h5Grp (h5py.Group) – The HDF5 group to write into.

  • structDict (dict) – Dictionary containing the data to write.

  • key (str) – The key in structDict whose value should be written.

Returns:

The updated HDF5 group.

Return type:

h5py.Group

cerr.plan_container.saveToH5(planC, h5File, scanNumV=[], structNumV=[], doseNumV=[], deformNumV=[])[source]

Routine to serialize planC to H5 file

Parameters:

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object

  • h5File (str) – File path/name to save planC

  • scanNumV – Indices for scan objects from planC.scan to export to h5 file

  • structNumV – Indices for structure objects from planC.structure to export to h5 file

  • doseNumV – Indices for dose objects from planC.dose to export to h5 file

  • deformNumV – Indices for deformation objects from planC.deform to export to h5 file

Returns:

cerr.plan_container.saveNiiStructure(niiFileName, labelDict, planC, strNumV=None, dim=3)[source]

Function to export a pyCERR’s structure objects to NIfTi format mask/label map.

Parameters:

  • niiFileName – string specifying path to output NIfTI file.

  • labelDict – dictionary mapping indices with structure names

  • planC – pyCERR plan_container object.

  • strNumV – [optional, default=None] list of structure indices to be exported.

  • dim – [optional, default=3]: writes a 3D array to nii, 4: writes 4D array to nii.

Returns:

0 on successful export.

cerr.plan_container.loadFromH5(h5File, initplanC='')[source]

Routine to load contents of H5 file into planC

Parameters:

  • h5File (str) – File path/name of .h5 file containing matadata from planC

  • initplanC (cerr.plan_container.PlanC) – pyCERR’s plan container object

Returns:

pyCERR’s plan container object with metadata imported from input H5 file.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.saveH5Header(headerGrp, planC)[source]

Write planC header attributes into an HDF5 group.

Parameters:

  • headerGrp (h5py.Group) – The HDF5 group that will receive the header data.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object.

Returns:

The updated HDF5 header group.

Return type:

h5py.Group

cerr.plan_container.saveH5Scan(scanGrp, scanNumV, planC)[source]

Write selected scan objects from planC into an HDF5 group.

Parameters:

  • scanGrp (h5py.Group) – The HDF5 group that will receive the scan data.

  • scanNumV (list[int]) – Indices into planC.scan identifying which scans to export.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object.

Returns:

The updated HDF5 scan group.

Return type:

h5py.Group

cerr.plan_container.saveH5Dose(structGrp, structNumV, planC)[source]

Write selected dose objects from planC into an HDF5 group.

Parameters:

  • structGrp (h5py.Group) – The HDF5 group that will receive the dose data.

  • structNumV (list[int]) – Indices into planC.dose identifying which dose objects to export.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object.

Returns:

The updated HDF5 dose group.

Return type:

h5py.Group

cerr.plan_container.saveH5Deform(deformGrp, deformNumV, planC)[source]

Write selected deformation objects from planC into an HDF5 group.

Parameters:

  • deformGrp (h5py.Group) – The HDF5 group that will receive the deformation data.

  • deformNumV (list[int]) – Indices into planC.deform identifying which deformation objects to export.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object.

Returns:

The updated HDF5 deformation group.

Return type:

h5py.Group

cerr.plan_container.saveH5Structure(structGrp, structNumV, planC)[source]

Write selected structure objects from planC into an HDF5 group.

Each structure’s contour segments are serialised recursively into nested HDF5 sub-groups.

Parameters:

  • structGrp (h5py.Group) – The HDF5 group that will receive the structure data.

  • structNumV (list[int]) – Indices into planC.structure identifying which structures to export.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object.

Returns:

The updated HDF5 structure group.

Return type:

h5py.Group

cerr.plan_container.readAttribsAndDsets(obj, h5Grp, excludeKeys=[])[source]

Populate a Python object’s fields from matching HDF5 attributes and datasets.

Scalar fields stored as HDF5 attributes are decoded from bytes when necessary. Array fields stored as HDF5 datasets are loaded via slice notation. Fields listed in excludeKeys are skipped.

Parameters:

  • obj – Any object whose __dict__ fields should be populated.

  • h5Grp (h5py.Group) – The HDF5 group containing attributes and datasets that correspond to obj’s fields.

  • excludeKeys (list[str]) – Optional list of field names to skip.

Returns:

The same object with fields populated from the HDF5 group.

Return type:

obj

cerr.plan_container.loadH5Header(headerGrp, planC)[source]

Load header metadata from an HDF5 group into planC.

Parameters:

  • headerGrp (h5py.Group) – The HDF5 group containing header attributes.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to update.

Returns:

The updated plan container with header populated.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadH5Scan(scanGrp, planC)[source]

Load scan objects from an HDF5 group into planC, skipping duplicates.

Each Item_N sub-group in scanGrp is deserialised into a cerr.dataclasses.scan.Scan object together with its associated scanInfo entries. Scans whose scanUID already exists in planC.scan are skipped with a warning.

Parameters:

  • scanGrp (h5py.Group) – The HDF5 group containing serialised scan items.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to update.

Returns:

The updated plan container with scans appended.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadH5Deform(deformGrp, planC)[source]

Load deformation objects from an HDF5 group into planC, skipping duplicates.

Each Item_N sub-group in deformGrp is deserialised into a cerr.dataclasses.deform.Deform object. Deformations whose deformUID already exists in planC.deform are skipped with a warning.

Parameters:

  • deformGrp (h5py.Group) – The HDF5 group containing serialised deformation items.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to update.

Returns:

The updated plan container with deformations appended.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadH5Dose(doseGrp, planC)[source]

Load dose objects from an HDF5 group into planC, skipping duplicates.

Each Item_N sub-group in doseGrp is deserialised into a cerr.dataclasses.dose.Dose object. Dose objects whose doseUID already exists in planC.dose are skipped with a warning.

Parameters:

  • doseGrp (h5py.Group) – The HDF5 group containing serialised dose items.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to update.

Returns:

The updated plan container with doses appended.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadH5Strucutre(structGrp, planC)[source]

Load structure objects from an HDF5 group into planC, skipping duplicates.

Each Item_N sub-group in structGrp is deserialised into a cerr.dataclasses.structure.Structure object together with its contour and segment data. Structures whose strUID already exists in planC.structure are skipped with a warning.

Parameters:

  • structGrp (h5py.Group) – The HDF5 group containing serialised structure items.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to update.

Returns:

The updated plan container with structures appended.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadDcmDir(dcmDir, opts={}, initplanC='')[source]

This routine imports metadata from DICOM directory and sub-directories into an instance of PlanC.

Parameters:

  • dcmDir (str) – absolute path to directory containing dicom files

  • opts (dict) –

    dictionary of import options. Currently supported options are:

    • ’suvType’: Choose from ‘BW’, ‘BSA’, ‘LBM’, ‘LBMJANMA’

    • ’groupByAcquisitionNumber’: Choose from True, False (default)

    e.g. opts = {'suvType': 'LBM', 'groupByAcquisitionNumber': True}

  • initplanC (PlanC) – An instance of PlanC to add the metadata. If not specified, metadata is added to an empty PlanC instance

Returns:

An instance of PlanC with metadata populated from DICOM files in dcm_dir

Return type:

PlanC

cerr.plan_container.populatePlanCField(field_name, file_list, opts={})[source]

Load imaging metadata from a list of DICOM files into the appropriate pyCERR dataclass.

Parameters:

  • field_name (str) – The planC field to populate. Accepted values are 'scan', 'structure', 'dose', and 'beams'.

  • file_list (pandas.Series or list) – Collection of DICOM file paths belonging to a single series/modality group.

  • opts (dict) – Optional import options forwarded to the underlying loader. Recognised keys include 'suvType'.

Returns:

A list of dataclass objects corresponding to field_name

(e.g. a list of cerr.dataclasses.scan.Scan for field_name='scan').

Return type:

list

cerr.plan_container.loadScanFromDB(sacnInfoList, niiFile, initplanC='')[source]

This routine imports scan from a list of scanInfo dicts and scanArray into planC

Parameters:

  • sacnInfoList (list) – List of dictionaries whose fields corresponsd to scanInfo fields

  • niiFile (np.ndarray) – 3D array of size numRows x numCols x numSlices, where the slice-dimension corresponds to entries in sacnInfoList

  • initplanC (cerr.plan_container.PlanC) – optional, pyCERR’s plan container object to append the scan

Returns:

pyCERR’s plan container object with scan imported to planC.scan[-1]

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadPlanCFromPkl(file_name='')[source]

Load a planC object previously serialised with Python’s pickle module.

Parameters:

file_name (str) – Path to the pickle file to load.

Returns:

The deserialised plan container object.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadNiiScan(nii_file_name, imageType='CT SCAN', direction='', initplanC='')[source]

This routine imports scan from NifTi file into planC

Parameters:

  • nii_file_name (str) – path of NifTi file containing the scan

  • imageType (str) – typte of scan. e.g. ‘CT SCAN’, ‘MR SCAN’, ‘PT SCAN’

  • direction (str) – optional, the desired orientation of scan. e.g. HFS

  • initplanC (cerr.plan_container.PlanC) – optional, pyCERR’s plan container object to append the scan

Returns:

pyCERR’s plan container object with scan imported to planC.scan[-1]

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadNiiDose(nii_file_name, assocScanNum, planC, fractionGroupID='RT-dose')[source]

Load a dose distribution from a NIfTI file into planC.

Parameters:

  • nii_file_name (str) – Path to the NIfTI file containing the dose array.

  • assocScanNum (int) – Index into planC.scan of the scan associated with this dose distribution.

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to which the dose will be appended.

  • fractionGroupID (str) – Optional label for the fraction group. Defaults to 'RT-dose'.

Returns:

The updated plan container with the dose

appended to planC.dose.

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadNiiStructure(nii_file_name, assocScanNum, planC, labels_dict={})[source]

This routine imports segmentation from NifTi file into planC

Parameters:

  • nii_file_name (str) – path of NifTi file containing the structure/s

  • assocScanNum (int) – index of scan from planC.scan associated with segmentation

  • planC (cerr.plan_container.PlanC) – optional, pyCERR’s plan container object to append structure/s

  • labels_dict (dict) – optional, dictionary mapping structure names to labels. e.g. {‘GTV’:1, ‘Lung_total’:2}

Returns:

pyCERR’s plan container object with structure/s imported to planC.structure

Return type:

cerr.plan_container.PlanC

cerr.plan_container.loadNiiVf(dvf_file, baseScanNum, planC)[source]

This routine loads deformation vector field from file into planC

Parameters:

  • dvf_file (str) – path to file containing the DFV

  • baseScanNum (int) – index of scan from planC.scan

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object to append vector field

Returns:

pyCERR’s plan container object with vector field imported to planC.deform

Return type:

cerr.plan_container.PlanC

cerr.plan_container.importScanArray(scan3M, xV, yV, zV, modality, assocScanNum, planC)[source]

This routine imports a scan from numpy array into planC

Parameters:

  • scan3M (numpy.ndarray)

  • xV (numpy.ndarray)

  • yV (numpy.ndarray)

  • zV (numpy.ndarray)

  • modality (str)

  • assocScanNum (int)

  • planC (cerr.plan_container.PlanC)

Returns:

pyCERR’s plan container object with scan imported to planC.scan

Return type:

cerr.plan_container.PlanC

cerr.plan_container.importDoseArray(dose3M, xV, yV, zV, planC, assocScanNum, doseInfo=None)[source]

This routine imports rt dose from numpy array into planC

Parameters:

  • dose3M (numpy.ndarray) – 3D dose array

  • xV (numpy.ndarray) – x-coordinates of dose grid

  • yV (numpy.ndarray) – y-coordinates of dose grid

  • zV (numpy.ndarray) – z-coordinates of dose grid

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object

  • assocScanNum (int) – Index of scan associated with dose

  • [Optional (doseInfo) – None]: Dictionary specifying ‘fractionGroupID’, and ‘units’.

Returns:

pyCERR’s plan container object with scan imported to planC.scan

Return type:

cerr.plan_container.PlanC

cerr.plan_container.importStructureMask(mask3M, assocScanNum, structName, planC, structNum=None)[source]
Parameters:

  • mask3M (numpy.ndarray) – binary mask containing segmentation

  • assocScanNum (int) – index of scan from planC.scan associated with segmentation

  • structName (str) – name of structure

  • planC (cerr.plan_container.PlanC) – pyCERR’s plan container object

  • structNum (int or None) – optional, index of structure object within planC.structure to replace

Returns:

pyCERR’s plan container object with structure imported to planC.structure

Return type:

cerr.plan_container.PlanC

cerr.plan_container.parseDcmHeader(fileList)[source]

This routine parses header from DICOM files in the input directory

Parameters:

fileList (list) – list of DICOM files

Returns:

Data frame containing header values of DICOM files. The header attributes consist of “PatientName”,”PatientID”,”StudyInstanceUID”,”SeriesInstanceUID”,”Modality”, “bValue”,”TemporalPosition”,”TriggerTime”,”NumSlices”,”FilePath”

Return type:

pandas.DataFrame

Module contents