Analysis module#

Overview#

OMG Dosimetry analysis module.

The dose analysis module performs in-depth comparison from film dose to reference dose image from treatment planning system.

Features:

  • Perform registration by identifying fiducial markers on the film,

  • Interactive display of analysis results (gamma map, relative error, dose profiles)

  • Gamma analysis: display gamma map, pass rate, histogram, pass rate vs dose bar graph, pass rate vs distance to agreement (fixed dose to agreement), pass rate vs dose to agreement (fixed distance to agreement)

  • Publish PDF report

Written by Jean-Francois Cabana, copyright 2018 Modified by Peter Truong (CISSSO) Version: 2023-12-15

API Documentation#

Main classes#

These are the classes a typical user may interface with.

class omg_dosimetry.analysis.DoseAnalysis(film_dose=None, ref_dose=None, norm_film_dose=None, film_dose_factor=1, ref_dose_factor=1, flipLR=False, flipUD=False, rot90=0, ref_dose_sum=False)[source]#

Base class for analysis film dose vs reference dose.

Usage : film = analysis.DoseAnalysis(film_dose=file_doseFilm, ref_dose=ref_dose)

path#

File path of scanned tif images of film to convert to dose. Multiple scans of the same films should be named (someName)_00x.tif These files will be averaged together to increase SNR.

Type:

str

film_dose#

File path of planar dose image of the scanned film converted to dose (using tiff2dose module).

Type:

str

ref_dose#

File path of the reference dose (from TPS).

Type:

str

norm_film_dose#

File path of the normalization film dose if scanned separately. Principle being that the same normalization film scan can be used for other tif images of film (path) scanned at the same time. Optional, default value is None.

Type:

str

film_dose_factor#

Scaling factor to apply to the film dose. Default is 1.

Type:

float, optional

ref_dose_factor#

Scaling factor to apply to the reference dose. Default is 1.

Type:

float, optional

flipLR#

Whether or not to flip the film dose horizontally (to match reference dose orientation). Default is False.

Type:

bool, optional

flipUD#

Whether or not to flip the film dose vertically (to match reference dose orientation). Default is False.

Type:

bool, optional

rot90#

If not 0, number of 90 degrees rotation to apply to the film (to match reference dose orientation).

Type:

int, optional

ref_dose_sum#

If True, all all planar dose files found in the ref_dose folder will be summed together.

Type:

bool, optional

apply_factor_from_isodose(norm_isodose=0)[source]#

Apply film normalisation factor from a reference dose isodose [cGy]. Mean dose inside regions where ref_dose > norm_isodose will be compared between film and ref_dose. A factor is computed and applied to film dose so that average dose in this region is the same for both.

apply_factor_from_norm_film(norm_dose=None, norm_roi_size=10)[source]#

Define an ROI of norm_roi_size mm x norm_roi_size mm to compute dose factor from a normalisation film.

apply_factor_from_roi(norm_dose=None)[source]#

Apply film normalisation factor from a rectangle ROI. Brings up an interactive plot, where the user must define a rectangle ROI that will be used to compute a film normalisation factor. Median dose inside this rectangle will be used to scale the film dose to match that of the reference.

apply_factor_from_roi_press_enter(event)[source]#

Function called from apply_factor_from_roi() when ‘’enter’’ is pressed.

apply_film_factor(film_dose_factor=None)[source]#

Apply a normalisation factor to film dose.

apply_ref_factor(ref_dose_factor=None)[source]#

Apply a normalisation factor to reference dose.

apply_shifts_ref()[source]#

Apply shifts given in self.shifts by padding the reference image.

computeDiff()[source]#

Compute the difference map with the reference image. Returns self.DiffMap = film_dose - ref_dose

computeGamma(doseTA=2, distTA=2, threshold=0.1, norm_val=None, local_gamma=False, max_gamma=None, random_subset=None)[source]#

Compute Gamma (using pymedphys.gamma)

computeHDmedianDiff(threshold=0.8, ref='max')[source]#

Compute median difference between film and reference doses in high dose region.

Parameters:

  • threshold (float, optional (>=0, <=1.0)) – The relative threshold (with respect to ‘ref’) used to determine the high dose region.

  • ref ('max' or float) – If given a number, the dose [cGy] used as a reference for threshold. If ‘max’, the maximum dose in ref_dose will be used.

crop_film()[source]#

Brings up an interactive plot, where the user must define a rectangle ROI that will be used to crop the film.

crop_film_press_enter(event)[source]#

Function called from crop_film() when ‘’enter’’ is pressed.

gamma_analysis(film_filt=0, doseTA=3.0, distTA=3.0, threshold=0.1, norm_val='max', local_gamma=False, max_gamma=None, random_subset=None)[source]#

Perform Gamma analysis between registered film_dose and ref_dose. Gamma computation is performed using pymedphys.gamma.

Parameters:

  • film_filt (int, optional) – Kernel size of median filter to apply to film dose before performing gamma analysis (for noise reduction). Default is 0.

  • doseTA (float, optional) – Dose to agreement threshold [%]. Default is 3.0.

  • distTA (float, optional) – Distance to agreement threshold [mm]¸. Default is 3.0.

  • threshold (float, optional (>=0, <=1.0)) – The percent lower dose cutoff below which gamma will not be calculated. Default is 0.1.

  • norm_val (float or 'max', optional) – Normalisation value [cGy] of reference dose, used to calculate the dose to agreement threshold and lower dose threshold. If ‘max’, the maximum dose from the reference distribution will be used. Default is ‘max’.

  • local_gamma (bool, optional) – Whether or not local gamma should be used instead of global. Default is False.

  • max_gamma (float, optional) – The maximum gamma searched for. This can be used to speed up calculation, once a search distance is reached that would give gamma values larger than this parameter, the search stops. Default is None.

  • random_subset (float (>=0, <=1), optional) – Used to only calculate a random subset fraction of the reference grid, to speed up calculation. Default is None

get_profile_offset(direction='x', side='left')[source]#
Opens an interactive plot where the user can move

the measured profile with respect to the reference profile in order to compute the spatial offset between the two.

Parameters:

  • direction (str, optional) – The direction of the profile. Either ‘x’ (horizontal) or ‘y’ (vertical). Default is ‘x’.

  • side (str, optional) – The side on the profile that will be matched. Either ‘left’ or ‘right’. Default is left.

get_profile_offsets()[source]#

Starts an interactive process where the user can move the measured profile with respect to the reference profile in order to compute the spatial offset between the two. The process is repeated four times to get offsets on both sides in the x and y directions.

move_iso_center()[source]#

Register the film dose and reference dose by moving the reference point to the center of the image (by padding). The reference point is given by the intersection of the two lines connecting the two markers on opposite side of the film, and by absolute coordinates in the stored in self.markers_center for the reference dose.

move_profile_ontype(event)[source]#

This function is called by self.get_profile_offset() to either move the profile when left/right keys are pressed, or to close the figure when Enter is pressed.

onclick(event)[source]#

This function is called by self.select_markers() to set the markers coordinates when the mouse is double-cliked.

ontype(event)[source]#

This function is called by self.select_markers() to continue the registration process when “enter” is pressed on the keyboard.

plot_gamma_hist(ax=None, bins='auto', range=[0, 3])[source]#

Plot a histogram of gamma map values.

Parameters:

  • ax (matplotlib.pyplot axe object, optional) – Axis in which to plot the graph. If None, a new plot is made. Default is None

  • bins (Determines the number of bins in the histogram.) – The argument passed to matplotlib.pyplot.hist. Default is ‘auto’

  • range (Determines the range of values showed in the histogram.) – The argument passed to matplotlib.pyplot.hist. Default is [0,3]

plot_gamma_pass_hist(ax=None, bin_size=50)[source]#

Plot a histogram of gamma map pass rate vs dose.

Parameters:

  • ax (matplotlib.pyplot axe object, optional) – Axis in which to plot the graph. If None, a new plot is made. Default is None

  • bin_size (float, optional) – Determines the size of bins in the histogram [cGy]. The number of bins is determined from the maximum dose in reference dose, and the bin_size. Default is 50 cGy

plot_gamma_stats(figsize=(10, 10), show_hist=True, show_pass_hist=True, show_varDistTA=True, show_varDoseTA=True)[source]#

Displays a figure with 4 subplots showing gamma analysis statistics: 1- Gamma map histogram, 2- Gamma pass rate vs dose histogram 3- Gamma pass rate vs variable distance to agreement threshold 4- Gamma pass rate vs variable dose to agreement threshold

plot_gamma_varDistTA(ax=None, start=0.5, stop=4, step=0.5)[source]#

Plot graph of Gamma pass rate vs variable distTA Note: values of doseTA, threshold and norm_val will be taken as those from the previous “standard” gamma analysis.

Parameters:

  • start (float, optional) – Minimum value of dist to agreement threshold [mm] Default is 0.5 mm

  • stop (float, optional) – Maximum value of dist to agreement threshold [mm] Default is 4.0 mm

  • step (float, optional) – Increment of dist to agreement value between start and stop values [mm] Default is 0.5 mm

plot_gamma_varDoseTA(ax=None, start=0.5, stop=4, step=0.5)[source]#

Plot graph of Gamma pass rate vs variable doseTA. Note: values of distTA, threshold and norm_val will be taken as those from the previous “standard” gamma analysis.

Parameters:

  • start (float, optional) – Minimum value of dose to agreement threshold [%] Default is 0.5 %

  • stop (float, optional) – Maximum value of dose to agreement threshold [%] Default is 4.0 %

  • step (float, optional) – Increment of dose to agreement value between start and stop values [%] Default is 0.5 %

plot_markers()[source]#

This function is called by self.onclick() and self.ontype() when self.markers need to be plotted onto figure

plot_profile(ax=None, profile='x', position=None, title=None, diff=False, offset=0)[source]#

Plot a line profile of reference dose and film dose at a given position.

Parameters:

  • ax (matplotlib.pyplot axe object, optional) – Axis in which to plot the graph. If None, a new plot is made. Default is None

  • profile ('x' or 'y') – The orientation of the profile to plot (x: horizontal, y: vertical) Default is ‘x’

  • position (int, optional) – The position of the profile to plot, in pixels, in the direction perpendicular to the profile. eg. if profile=’x’ and position=400, a profile in the x direction is showed, at position y=400. If None, position is set to the center of the reference dose. Default is None

  • title (str, optional) – The title to display on the graph. If None, the tile is set automatically to display profile direction and position Default is None

  • diff (bool, optional) – If True, the difference in profiles (film - reference) is displayed Default is False

  • offset (int, optional) – If a known offset exists between the film and the reference dose, the plotted profile can be shifted to account for this offset. For example, a film exposed at a fixed gantry angle coud have a known offset due to gantry sag, and you could want to correct for it on the profile. Default is 0 mm

publish_pdf(filename=None, author=None, unit=None, notes=None, open_file=False, x=None, y=None, **kwargs)[source]#

Publish a PDF report of the calibration. The report includes basic file information, the image and determined ROIs, and the calibration curves

Parameters:

  • filename (str) – The path and/or filename to save the PDF report as; must end in “.pdf”.

  • author (str, optional) – The person who analyzed the image.

  • unit (str, optional) – The machine unit name or other identifier (e.g. serial number).

  • notes (str, list of strings, optional) – If a string, adds it as a line of text in the PDf report. If a list of strings, each string item is printed on its own line. Useful for writing multiple sentences.

reg_ontype(event)[source]#

Thie function is called by self.tune_registration() to apply translations and rotations, and to end the registration process when Enter is pressed.

register(shift_x=0, shift_y=0, threshold=10, register_using_gradient=False, markers_center=None, rot=0)[source]#

Starts the registration procedure between film and reference dose.

Parameters:

  • shift_y (shift_x /) –

  • dose. (Apply a known rotation [degrees] between reference dose and film) –

  • image. (Used if there is a known shift between the registration point in the reference image and the film) –

  • 0 (Default is) –

  • threshold (int, optional) –

  • auto-cropping. (Threshold value [cGy] used in detecting film edges for) –

  • 10 (Default is) –

  • register_using_gradient (bool, optional) –

  • displayed (Determine if the registration results (overlay of film/ref dose) will be) –

  • gradients. (after applying a sobel filter to improve visibility of strong dose) –

  • False (Default is) –

  • markers_center (list of 3 floats, optional) –

  • (R-L (Coordinates [mm] in the reference dose corresponding to the marks intersection on the film) –

  • I-S –

  • P-A). –

  • lines (It will be used to align the reference point on the film (given by the intersection of the two) –

  • dose. –

  • None (Default is) –

  • dose. –

  • None –

  • rot (float, optional) –

  • dose. –

  • aligned (Used if the markers on the reference image are known to be not perfectly) –

  • line. (in an horizontal/vertical) –

  • 0 –

remove_rotation()[source]#

Rotates the film around the center so that left/right and top/bottom markers are horizontally and vertically aligned.

save_analyzed_gamma(filename, **kwargs)[source]#

Save the analyzed image to a file.

Parameters:

  • filename (str) – The location and filename to save to.

  • kwargs – Keyword arguments are passed to plt.savefig().

save_analyzed_image(filename, x=None, y=None, **kwargs)[source]#

Save the analyzed image to a file.

Parameters:

  • filename (str) – The location and filename to save to.

  • kwargs – Keyword arguments are passed to plt.savefig().

select_markers()[source]#

This function is called by self.register() to start the interactive plot where the 4 markes on the film must be identified.

set_profile(event, axes)[source]#

This function is called by show_results to draw dose profiles on mouse click (if cursor is not set to zoom or pan).

show_profiles(axes, x, y)[source]#

This function is called by show_results and set_profile to draw dose profiles at a given x/y coordinates, and draw lines on the dose distribution maps to show where the profile is taken.

show_registration(ax=None, cmap='bwr')[source]#

This function is used by self.tune_registration() for showing the superposition of the film and reference dose. If self.register_using_gradient is set to True, a sobel filter is applied to both reference and film dose in order to increase dose gradients visibility.

show_results(fig=None, x=None, y=None, show=True)[source]#

Display an interactive figure showing the results of a gamma analysis. The figure contains 6 axis, which are, from left to right and top to bottom: Film dose, reference dose, gamma map, relative error, x profile and y profile.

Parameters:

  • fig (matplotlib.pyplot figure object, optional) – Figure in which to plot the graph. If None, a new figure is made. Default is None

  • x (int, optional) – Initial x/y coordinates of the profiles. If None, profile will be at image center. Default is None

  • y (int, optional) – Initial x/y coordinates of the profiles. If None, profile will be at image center. Default is None

tune_registration()[source]#

Starts the registration fine tuning process. The registered film and reference image are displayed superposed. User can adjust the registration using keyboard shortcuts. Arrow keys will move the film dose in one pixel increments. Ctrl+left/right will rotate the film dose by 0.1 degrees counterclockwise/clockwise.