Victre Class

Documentation for the Victre project.

class Victre.Pipeline(ips={'cpu': 'localhost', 'gpu': 'localhost'}, seed=None, results_folder='./results', phantom_file=None, spectrum_file='./Victre/projection/spectrum/W28kVp_Rh50um_Be1mm.spc', lesion_file=None, materials=None, roi_sizes={1: [65, 65, 5], 2: [109, 109, 9]}, arguments_generation={}, arguments_spiculated={}, arguments_mcgpu={}, arguments_recon={}, arguments_cluster={}, flatfield_DBT=None, flatfield_DM=None, density=None, verbosity=True)

Object constructor for the Victre pipeline class

Parameters:

ips – Dictionary with two IP addresses to run the pipeline: “gpu” for the projection process. “cpu” for the reconstruction.
seed – Random seed used to generate or read the phantom
results_folder – Path to folder to be used when saving the results
phantom_file – Path to file containing the phantom to be loaded
spectrum_file – Path to file containing the spectrum used to project in MCGPU
lesion_file – Path to file containing the lesion to be inserted (in HDF5 format)
materials – Dictionary including the materials to be used during projection
roi_sizes – Dictionary with the ROI sizes for the extraction
arguments_generation – Arguments to be overriden for the breast phantom generation
arguments_spiculated – Arguments to be overriden for the spiculated mass generation
arguments_mcgpu – Arguments to be overridden for the projection in MCGPU
arguments_recon – Arguments to be overridden for the reconstruction algorithm
arguments_cluster – Arguments to be overridden for the calcification cluster generation
flatfield_DBT – Path to the flatfield file for the DBT reconstruction
flatfield_DM – Path to the flatfield file for the digital mammography
density – [EXPERIMENTAL] Percentage of dense tissue of the phantom to be generated, this will adjust the compression thickness too
verbosity – True will output the progress of each process and steps

Returns:

None

add_absent_ROIs(lesion_type, n=1, locations=None, roi_sizes=None, save_locations=True)

Adds the specified number of lesion-absent regions of interest.

Parameters:

lesion_type – Constant with the desired lesion type. Check available lesion types and materials in the Constants file.
n – Number of lesions to be added
locations – List of coordinates in the voxel/phantom space where the lesions will be inserted. If not specified, random locations will be generated.
roi_sizes – Size of the region of interest to be calculated to avoid overlapping with other tissues and check out of bounds locations

Returns:

None. A location file will be saved inside the phantom folder with the corresponding seed. Negative lesion type means absent ROI.

compress_phantom(thickness=None)

Runs the FEBio compression.

Parameters:: thickness – Specifies the objective thickness for the phantom to be compressed (in cm)
Returns:: None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: pc_SEED.raw.gz with the raw data, and pc_SEED.mhd with the information about the raw data.

crop(size=None)

Runs breast phantom cropping.

Returns:: None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: pc_SEED_crop.raw.gz with the raw data, and pc_SEED_crop.mhd with the information about the raw data.

generate_cluster(seed=None, size=None, nmin=None, nmax=None, smin=None, smax=None)

Generates a random calcification cluster

Parameters:

seed – Seed to be used when generating the cluster
size – Side of the 3D array (ROI cube) in which to generate the cluster (in mm)
nmin – Minimum number of calcifications to generate
nmax – Maximum number of calcifications to generate
smin – Minimum size of the generated calcifications (in mm)
smax – Maximum size of the generated calcifications (in mm)

Returns:

None. The result is saved in the lesions subfolder

generate_phantom()

Runs breast phantom generation.

Returns:: None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: p_SEED.raw.gz with the raw data, and p_SEED.mhd with the information about the raw data.

generate_spiculated(seed=None, size=None)

Generates a spiculated mass using the breastMass software

Parameters:

seed – Seed to be used when generating the mass
size – Size of the mass to be used in the breastMass config file

Returns:

None. The result is saved in the lesions subfolder

get_DBT_segmentation()

Calculates the true segmentation of the DBT volume using the phantom model.

Returns:: 3-dimensional array of integer values of the tissue ID corresponding to each

voxel of the DBT reconstruction.

get_coordinates_dbt(vx_location)

Method to get the corresponding coordinates in the DBT volume from the voxelized coordinates

Parameters:: vx_location – Coordinates in the voxel/phantom space
Returns:: Coordinates in the DBT space

get_coordinates_dm(vx_location)

Method to get the corresponding coordinates in the DM volume from the voxelized coordinates

Parameters:: vx_location – Coordinates in the voxel/phantom space
Returns:: Coordinates in the DM space

static get_folder_contents(folder)

Gets a list of files in the given folder

Parameters:: folder – Path to the folder to be processed
Returns:: List with files inside the given folder

insert_lesions(lesion_type=None, n=-1, lesion_file=None, lesion_size=None, locations=None, roi_sizes=None, save_phantom=True, seed=None)

Inserts the specified number of lesions in the phantom.

Parameters:

lesion_type – Constant with the desired lesion type. Check available lesion types and materials in the Constants file.
n – Number of lesions to be added
lesion_file – Path to file including the lesion to be inserted (in HDF5 format). If specified, it will overrite the lesion file specified in the constructor.
lesion_size – If lesion_file is a raw file, lesion_size indicates the size of this file
locations – List of coordinates in the voxel/phantom space where the lesions will be inserted. If not specified, random locations will be generated.
roi_sizes – Size of the region of interest to be calculated to avoid overlapping with other tissues and check out of bounds locations
seed – Specific seed for randomized insertion, defaults to phantom seed, set to -1 to randomize every insertion

Returns:

None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Three files will be generated: pcl_SEED.raw.gz with the raw data, pcl_SEED.mhd with the information about the raw data, and pcl_SEED.loc with the voxel coordinates of the lesion centers.

project(flatfield_correction=True, clean=True, do_flatfield=0, for_presentation=False)

Method that runs MCGPU to project the phantom.

Parameters:

flatfield_correction – If True, the projections will be corrected using a given flatfield. It will be generated if not found and not given.
clean – If True, it will delete the contents of the output folder before projecting.
do_flatfield – If > 0, it will generate an empty flat field projection.

reconstruct(): Method that runs the reconstruction code for the DBT volume

reverse_dbt_coordinates(dbt_location)

Returns the 3D coordinate in the model (phantom) space from the input 3D digital breast tomosynthesis coordinates

Parameters:: dbt_location – 3-dimensional tuple or array with the coordinates in the digital breast tomosynthesis space
Returns:: 3-dimensional array of coordinates in the model (phantom) space

reverse_dm_coordinates(dm_location)

Returns the list of 3D coordinates in the model (phantom) space from the input 2D digital mammography coordinates. Note: This will take a long time to compute

Parameters:: dm_location – 2-dimensional tuple or array with the coordinates in the digital mammography space
Returns:: List of 3D coordinates in the model (phantom) space

save_DICOM(modality='dbt')

Saves the DM or DBT images in DICOM format. If present, lesion location will be stored in a custom tag 0x009900XX where XX is the lesion number.

Parameters:: modality – Modality to save: dbt or dm

save_ROIs(roi_sizes=None, clean=True, save_folder=None)

Saves the generated ROIs (absent and present) in RAW and HDF5 formats

Parameters:

roi_sizes – Size of the ROIs for the defined lesion types
clean – If True, the existing ROI folder will be deleted

Model Observer Class

Documentation for the Model Observer component of the VICTRE project.

class Victre.ModelObserver.CHO(channel_type=None, channels=None, signal=None, nps=None, signal_present_samples=None, signal_absent_samples=None, results_folder=None, modality='dm', training_ratio=1, channel_filter=None, channel_params=None, subtract_mean_background=False)

This method initializes a Channelized Hotelling Observer (CHO) given a specific channel type. It can receive the signal or a set of training present and absent images.

Parameters:

channel_type – Type of the channels to be created for the CHO: Gabor, LGauss or DoG.
channels: – Alternatively, you can provide your own channels.
signal – Provide your own signal profile, otherwise, samples will be used to calculate the signal profile.
nps – Noise power spectrum used to filter the channels.
signal_present_samples – List of images (2D or 3D) for signal-present trials.
signal_absent_samples – List of images (2D or 3D) for signal-absent trials.
results_folder – Path to the VICTRE results folder if trials are to be extracted from there.
modality – Modality to use when path to VICTRE results folder is given.
training_ratio – ratio of samples used to retrain.
channel_filter – Use of filtered channels.
channel_params – Dictionary with the parameters for the channel generation.

Returns:

None

build_template()

This method builds the Channelized Hotelling template with the given channels and signal.

Returns:: None

class Victre.ModelObserver.ModelObserver(signal_present_samples=None, signal_absent_samples=None, signal=None, results_folder=None, modality='dm', training_ratio=1, subtract_mean_background=False)

Initializes the ModelObserver generic class. This should be done on the children classes, not here.

Parameters:

signal_present_samples – List of images (2D or 3D) for signal-present trials.
signal_absent_samples – List of images (2D or 3D) for signal-absent trials.
signal – Provide your own signal profile, otherwise, samples will be used to calculate the signal profile.
results_folder – Path to the VICTRE results folder if trials are to be extracted from there.
modality – Modality to use when path to VICTRE results folder is given.
training_ratio – ratio of samples used to retrain.

Returns:

None

estimate_NPS(samples)

This method estimates the noise power spectrum from samples in any dimension. :param samples: List of samples.

Returns:: Noise power spectrum matrix.

extract_from_samples(signal_present_samples, signal_absent_samples)

Extracts the signal only from present and absent samples and saves it as class variables.

Parameters:

signal_present_samples – List of signal-present images.
signal_absent_samples – List of signal-absent images.

Returns:

None.

get_performance(LKE=True, function='sum')

Calculates model observer’s performance for the loaded samples.

Parameters:

LKE – Indicate a Location-Known Exactly (LKE) task or a search task.
function – For search tasks (LKE = false), specify the function used to

combine the results of the convolution. Valid options are sum or max.

read_from_VICTRE(results_folder, modality, subtract_mean_background=True)

Reads the samples from a VICTRE results folder structure and extracts the signal.

Parameters:

results_folder – Path to the results folder from the VICTRE pipeline.
modality – Modality to load (dm or dbt)

Returns:

None.

retrain(training_ratio=None)

Retrains the model from a different set of samples.

Parameters:: training_ratio – ratio of samples used to retrain.
Returns:: None.

run(images=None, LKE=True, function='sum')

Computes the result for the model observer template in a LKE or Search task on a set of images.

Parameters:

images – List of images to be processed by the model observer.
LKE – Indicate a Location-Known Exactly (LKE) task or a search task.
function – For search tasks (LKE = false), specify the function used to combine the results of the convolution. Valid options are sum or max.

Returns:

List with the resulting statistic of the model observer computation for each image.

run_readers(num_readers, LKE=True, function='sum')

Run a specified number of readers, retraining them every iteration.

Parameters:

num_readers – Number of readers to run.
LKE – Indicate a Location-Known Exactly (LKE) task or a search task.
function – For search tasks (LKE = false), specify the function used to combine the results of the convolution. Valid options are sum or max.

Returns:

2-tuple with the statistics of each reader and their corresponding responses to each processed trial.

save_iMRMC(filename, scores=None)

Save the results of the model observer as an iMRMC format file.

Parameters:

filename – Output file name to save the result.
scores – Alternatively, specify the scores of various modalities to be saved in the file instead of the current model observer’s results.

Returns:

None.

class Victre.ModelObserver.NPW(signal=None, signal_present_samples=None, signal_absent_samples=None, results_folder=None, modality='dm', training_ratio=1, subtract_mean_background=False)

This method initializes a Non PreWhitening (NPW) model observer. It can receive the signal or a set of training present and absent images.

Parameters:

signal – Provide your own signal profile, otherwise, samples will be used to calculate the signal profile.
signal_present_samples – List of images (2D or 3D) for signal-present trials.
signal_absent_samples – List of images (2D or 3D) for signal-absent trials.
results_folder – Path to the VICTRE results folder if trials are to be extracted from there.
modality – Modality to use when path to VICTRE results folder is given.
training_ratio – ratio of samples used to retrain.

Returns:

None

build_template()

This method builds the NPW template.

Returns:: None

class Victre.ModelObserver.NPWE(signal=None, signal_present_samples=None, signal_absent_samples=None, results_folder=None, modality='dm', training_ratio=1, pixels_per_degree=50, alpha=1.9, beta=2, gamma=0.5)

This method initializes a Non PreWhitening with Eye filter (NPWE) model observer. It can receive the signal or a set of training present and absent images.

Parameters:

signal – Provide your own signal profile, otherwise, samples will be used to calculate the signal profile.
signal_present_samples – List of images (2D or 3D) for signal-present trials.
signal_absent_samples – List of images (2D or 3D) for signal-absent trials.
results_folder – Path to the VICTRE results folder if trials are to be extracted from there.
modality – Modality to use when path to VICTRE results folder is given.
training_ratio – ratio of samples used to retrain.
pixels_per_degree – Pixels per degree of visual angle to generate the eye filter.
alpha – Parameter alpha for the eye filter.
beta – Parameter beta for the eye filter.
gamma – Parameter gamma for the eye filter.

Returns:

None

build_template()

This method builds the NPWE template.

Returns:: None

eye_filter(r)

Generates the corresponding eye filter at distance r.

Parameters:: r – Radial distance to generate the eye filter.
Returns:: Eye filter response at distance r.

class Victre.ModelObserver.PWMF(signal=None, nps=None, signal_present_samples=None, signal_absent_samples=None, results_folder=None, modality='dm', training_ratio=1, subtract_mean_background=False)

This method initializes a PreWhitening Matched Filter (PWMF) model observer. It can receive the signal or a set of training present and absent images.

Parameters:

signal – Provide your own signal profile, otherwise, samples will be used to calculate the signal profile.
nps – Noise power spectrum used to filter the channels. If not provided it will be estimated from trials.
signal_present_samples – List of images (2D or 3D) for signal-present trials.
signal_absent_samples – List of images (2D or 3D) for signal-absent trials.
results_folder – Path to the VICTRE results folder if trials are to be extracted from there.
modality – Modality to use when path to VICTRE results folder is given.
training_ratio – ratio of samples used to retrain.

Returns:

None

build_template()

This method builds the PWMF template.

Returns:: None