API¶

Reference page for individual observer functions, observer classes, helper functions and and scripts.

observer functions¶

Functional versions of model observers.

LCD.functions.lg_cho_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, ch_width, nch)¶

[auc,snr, chimg,tplimg,meanSP,meanSA,meanSig, k_ch, t_sp, t_sa,]=LG_CHO_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, ch_width, nch) Calculating lesion detectability using Laguerre-Gauss channelized model observer.

Parameters:

trimg_sa:: the training set of signal-absent (SA) images;
trimg_sp:: the training set of signal-present (SP) images;
testimg_sa:: the test set of signal-absent images;
testimg_sp:: the test set of signal-present iamges;
ch_width:: channel width parameter; (suggest setting this parameter to be about 2/3 of the disk radius (in pixel)).
nch:: number of channels to be used; default is 5.

Returns:

auc:: the AUC values
snr:: the detectibility SNR
t_sa:: t-scores of SA cases
t_sp:: t-scores of SP cases
meanSA:: mean of training SP ROIs
meanSP:: mean of traning SA ROIs
meanSig:: mean singal images (= meanSP-meanSA)
tplimg:: the template of the model observer
chimg:: channel images
k_ch:: the channelized data covariance matrix estimated from the training data

R Zeng, 6/2016, FDA/CDRH/OSEL/DIDSR

LCD.functions.conv_LG_CHO_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, ch_width, nch, b_conv, ch2)¶

Filtered/convolutional Channels CHO

Based on the paper: Diaz et al, IEEE-tmi-34(7), 2015, “Derivation of an observer model adapted to irregular signals based on covolution channels” <https://pubmed.ncbi.nlm.nih.gov/25622313/>

Paremeters:

testimg_sa:: the test set of signal-absent, a stack of 2D array
testimg_sp:: the test set of signal-present
trimg_sa:: the training set of signal-absent
trimg_sp:: the training set of signal-present
ch_width:: channel width parameter;
nch:: number of channels to be used;
b_conv:: 1 or 0 to indicate whether to apply a convolution of the signal to the LG channels. Default is 1.
ch2:: an optional additional LG channel, 2-element vector form [ch_width nch] eg. for the spiculated mass, one may use a main channel of width matching the signal size and use an additional channel with small width for detecting the edge feature.

Returns:

auc:: the AUC values
snr:: the detectibility SNR
t_sp:: t-scores of SP cases
t_sa:: t-scores of SA cases

R Zeng, 6/2016, FDA/CDRH/OSEL/DIDSR

LCD.functions.gabor_cho_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, nband, ntheta, phase)¶

[auc,snr, chimg,tplimg,meanSP,meanSA,meanSig, k_ch, t_sp, t_sa,]=gabor_cho_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, nband, ntheta, phase) Calculating lesion detectability using Gabor channelized Hoteling model observer.

Parameters:

testimg_sa:: the test set of signal-absent, a stack of 2D array;
testimg_sp:: the test set of signal-present;
trimg_sa:: the training set of signal-absent;
trimg_sp:: the training set of signal-present;
nband:: number of octave bands; (default is 4)
ntheta:: number of angles; (default is 4)
phase:: a vector containing the phase values in radian such as 0,pi/3,pi/2 etc.(default is 0)

Returns:

auc:: the AUC values
snr:: the detectibility SNR
t_sa:: t-scores of SA cases
t_sp:: t-scores of SP cases
meanSA:: mean of training SP ROIs
meanSP:: mean of traning SA ROIs
meanSig:: mean singal images (= meanSP-meanSA)
tplimg:: the template of the model observer
chimg:: channel images
k_ch:: the channelized data covariance matrix estimated from the training data

R Zeng, 11/2022, FDA/CDRH/OSEL/DIDSR

LCD.functions.dog_cho_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, DOGtype)¶

[auc,snr, chimg,tplimg,meanSP,meanSA,meanSig, k_ch, t_sp, t_sa,]=dog_cho_2d(trimg_sa, trimg_sp, testimg_sa, testimg_sp, DOGtype) Calculating lesion detectability using difference-of-Gaussian channelized Hoteling model observer.

Parameters:

trimg_sa:: the training set of signal-absent (SA) images;
trimg_sp:: the training set of signal-present (SP) images;
testimg_sa:: the test set of signal-absent images;
testimg_sp:: the test set of signal-present iamges;
DOGtype:: ‘dense’ or ‘sparse’ (default is ‘dense’), based on the parameter settings in Abbey&Barrett2001-josa-v18n3.

Returns:

auc:: the AUC values
snr:: the detectibility SNR
t_sa:: t-scores of SA cases
t_sp:: t-scores of SP cases
meanSA:: mean of training SP ROIs
meanSP:: mean of traning SA ROIs
meanSig:: mean singal images (= meanSP-meanSA)
tplimg:: the template of the model observer
chimg:: channel images
k_ch:: the channelized data covariance matrix estimated from the training data

R Zeng, 11/2022, FDA/CDRH/OSEL/DIDSR

observer classes¶

Observer functions wrapped in classes for more consistent and convenient use.

class LCD.classes.BaseObserver¶

BASEOBSERVER Summary of this class goes here Detailed explanation goes here

Method Summary

perform_study(signal_absent_train, signal_present_train, signal_absent_test, signal_present_test)¶: METHOD1 Summary of this method goes here Detailed explanation goes here

class LCD.classes.LG_CHO_2D¶

LG_CHO_2D Summary of this class goes here Detailed explanation goes here

Constructor Summary

LG_CHO_2D(channel_width, n_channels)¶: LG_CHO_2D Construct an instance of this class Detailed explanation goes here

Method Summary

perform_study(signal_absent_train, signal_present_train, signal_absent_test, signal_present_test)¶: [results] = perform_study(obj,signal_absent_train, signal_present_train,signal_absent_test, signal_present_test) Detailed explanation goes here

class LCD.classes.GABOR_CHO_2D¶

GABOR_CHO_2D Summary of this class goes here Detailed explanation goes here nband: number of octave bands; (default is 4) ntheta: number of angles; (default is 4) phase: a vector containing the phase values in radian such as 0,pi/3,pi/2 etc.(default is 0)

Constructor Summary

GABOR_CHO_2D(nband, ntheta, phase)¶: DOG_CHO_2D Construct an instance of this class Detailed explanation goes here

Method Summary

perform_study(signal_absent_train, signal_present_train, signal_absent_test, signal_present_test)¶: METHOD1 Summary of this method goes here Detailed explanation goes here

class LCD.classes.DOG_CHO_2D¶

DOG_CHO_2D Summary of this class goes here Detailed explanation goes here

Constructor Summary

DOG_CHO_2D(DOGtype)¶: DOG_CHO_2D Construct an instance of this class Detailed explanation goes here

Method Summary

perform_study(signal_absent_train, signal_present_train, signal_absent_test, signal_present_test)¶: METHOD1 Summary of this method goes here Detailed explanation goes here

helper functions¶

LCD.measure_LCD(base_dir, observers, ground_truth, offset, n_reader, pct_split, seed_split)¶

given a dataset calculate low contrast detectability as auc curves and return as a table ready for saving or plotting

Parameters:

base_dir – directory containing dataset
observers – list of observer objects or strings of name of observers. Options: LG_CHO_2D, DOG_CHO_2D, GABOR_CHO_2D
ground_truth – image or filename of image with no noise of MITA LCD phantom, see approximate_groundtruth for details on how to turn repeat scans into a ground truth image
offset – an optional offset subtracted from each image (default 0)
n_reader – number of readers (default is 10)
pct_split – percent of images to be used for training, remainder (1 - split_pct) to be used for testing (default is 0.5)
seed_split – 1d vector containing ‘nreader’ of random seed values. (defaults to randomly selected seed)

Return res_table:

table ready for saving or plotting

LCD.imread_raw(fname, imsize, offset, dtype)¶: im = imread_raw(fname, imsize, offset, dtype) see help fread for more

LCD.mhd_write_volume(filename, image, varargin)¶: Write mhd arguments: write_mhd(filename,image) write_mhd(filename,image, param, value,…) params and default value:

‘NDims’ = 3 ‘BinaryData’ = true ‘BinaryDataByteOrderMSB’ = false ‘CompressedData’ = false ‘TransformMatrix’ = 1 0 0 0 1 0 0 0 1 (coherent with NDims) ‘CenterOfRotation’ = 0 0 0 (coherent with NDims) ‘AnatomicalOrientation’ = RAI ‘ElementNumberOfChannels’ = 1 ‘ElementType’ = MET_FLOAT

LCD.download_largedataset(large_dataset_directory)¶: DOWNLOAD_LARGEDATASET Summary of this function goes here Detailed explanation goes here

LCD.get_ROI_from_truth_mask(bw_truth_mask, img, nx)¶: return bounding box region of interest around a known signal === inputs: bw_truth_mask - a binary image with a one signal, will error if multiple signals are provided img: image to crop around the truth signal and return nx: matrix size (area around the signal to crop) optional, if left unspecified, will grab bounding box width === outputs: cropped_img

LCD.laguerre(x, J)¶: function L=laguerre(x,J) Calculate the laguerre polynomials

LCD.laguerre_gaussian_2d(x, J, h)¶

function u=laguerre_gaussian_2d(x,J,h) Calculate the Laguerre-gaussian function Inputs

x: 1d vector of pixel locations J: # of channels h: the Guassian width

2009, R Zeng, FDA/CDRH/OSEL

LCD.write_lcd_results(res_table, fname)¶

write low contrast detectability measures to csv file

Parameters:

res_table – Matlab or Octave table containing LCD results
fname – file name of csv file to be saved

LCD.roc(varargin)¶

ROC - Receiver Operating Characteristics. The ROC graphs are a useful tecnique for organizing classifiers and visualizing their performance. ROC graphs are commonly used in medical decision making. If you have downloaded partest http://www.mathworks.com/matlabcentral/fileexchange/12705 the routine will compute several data on test performance.

Syntax: roc(x,alpha)

Input: x - This is the data matrix. The first column is the column of the data value;: The second column is the column of the tag: unhealthy (1) and healthy (0).

alpha - significance level (default 0.05)

Output: The ROC plot;

The Area under the curve with Standard error and Confidence interval and comment. Cut-off point for best sensitivity and specificity. (Optional) the test performances at cut-off point.

Example:

load rocdata roc(x)

Created by Giuseppe Cardillo giuseppe.cardillo-edta@poste.it

To cite this file, this would be an appropriate format: Cardillo G. (2008) ROC curve: compute a Receiver Operating Characteristics curve. http://www.mathworks.com/matlabcentral/fileexchange/19950

LCD.approximate_groundtruth(base_directory, ground_truth_filename, offset)¶

given a base_directory with many repeat scans of signal-present and signal-absent images estimate a ground truth image by avaging the repeat images and subtracting background images to get signal only images. Filtering and segmentation are applied to approximate ground truth masks with no noise.

Parameters:: base_directory – directory containing dose_100 directory and two subdirectories signal_present and signal_absent each with repeat images like so:

Parameters:

ground_truth_filename – [optional] full pathname to the file where the estimagte ground truth image will be saved to. Defaults to ground_truth.mhd
offset – [optional] subtract a constant HU value from all pixels. Can be useful if loading from int16 images where only positive values ares kept, thus subtracting an offset would yield the correct HU alues, say negative values in air.

Return ground_truth:

ground truth image used as input for themake_auc

LCD.mhd_read_image(mhd_header)¶: MHD_READ_IMAGE Summary of this function goes here Detailed explanation goes here

LCD.mha_read_volume(info)¶

Function for reading the volume of a Insight Meta-Image (.mha, .mhd) file

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions %are met:

Redistributions of source code must retain the above copyright %notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright %notice, this list of conditions and the following disclaimer in the %documentation and/or other materials provided with the distribution examples:

1: info = mha_read_header()
V = mha_read_volume(info); imshow(squeeze(V(:,:,round(end/2))),[]);

2: V = mha_read_volume(‘test.mha’);

LCD.find_insert_centers(signal_present_image, smoothing_window_size, search_range)¶: given a signal-present MITA-LCD image with 14, 7, 5, and 3 HU inserts, segment the inserts and yield a noise-free ground truth mask :param signal_present_image: high dose/low noise MITA-LCD signal-present image used to find centers :param smoothing_window_size: [optional] defaults to 11 pixels wide. Larger values can be used to increase smoothing of image to help find circlular inserts in highly noisy images :param search_range: [optional] circle radius serch range in pixels to detect circlar inserts. Try help imfindcircles to learn more

LCD.plot_results(results, set_ylim)¶: results can be a csv filename, Matlab Table, or 2D array :param results: Table or csv filename of LCD results from measure_LCD :param set_ylim: y limits for plotting AUC :param comparison: (default is none []) method for comparing different recons plotting examples

LCD.train_test_split(sa_imgs, sp_imgs, split_pct, seed_val)¶

split signal absent and signal present images into training and testing sets

param sa_imgs:

3D array of signal absent images

param sp_imgs:

3D array of signal present images

param split_pct:

percent of images to be used for training, remainder (1 - split_pct) to be used for testing

param seed_val:

seed value to control the random generator

Return sa_train:

training set of sample absent images

Return sa_test:

testing set of sample absent images

Return sp_train:

training set of sample present images

Return sp_train:

testing set of sample present images

Example:: train_test_split(rand(64, 64, 10), rand(64, 64, 10), 0.3)

LCD.mha_read_header(filename)¶

Function for reading the header of a Insight Meta-Image (.mha,.mhd) file

info = mha_read_header(filename);

examples: 1, info=mha_read_header() 2, info=mha_read_header(‘volume.mha’);

LCD.get_demo_truth_masks(xtrue, tol)¶

Parameters:: tol – relative tolerance

API¶

observer functions¶

observer classes¶

helper functions¶

LCD for CT Toolbox

Navigation

Related Topics