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: 2025-06-27

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, apply_dose_factors=True)

Base class for analysis film dose vs reference dose.

Usage:

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

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 scanned at the same time.

Type:

str, optional, default=None

film_dose_factor

Scaling factor to apply to the film dose.

Type:

float, optional, default=1.0

ref_dose_factor

Scaling factor to apply to the reference dose.

Type:

float, optional, default=1.0

flipLR

Whether or not to flip the film dose horizontally to match reference dose orientation.

Type:

bool, optional, default=False

flipUD

Whether or not to flip the film dose vertically to match reference dose orientation.

Type:

bool, optional, default=False

rot90

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

Type:

int, optional, default=0

ref_dose_sum

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

Type:

bool, optional, default=False

apply_dose_factors

If True, apply parameters film_dose_factor and ref_dose_factor to film/reference dose maps.

Type:

bool, optional, default = True

analyse_clusters(clusters_threshold=0.6, xlim_margin_mm=10)

Analyze clusters in the reference dose and compute median dose differences.

Parameters:

• clusters_threshold (float, optional, default=0.6) – Threshold value to identify clusters within the reference dose. The value should be between 0 and 1.

• xlim_margin_mm (int, optional, default=10) – The margin [mm] to add to the x-axis limits around the clusters.

apply_factor_from_isodose(norm_isodose=0)

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 median dose in this region is the same for both.

apply_factor_from_norm_film(norm_dose=None, norm_roi_size=10)

Define an ROI of norm_roi_size mm x norm_roi_size mm to compute dose factor from a normalisation film (in the same scan).

apply_factor_from_roi(norm_dose=None, apply=True)

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)

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

apply_film_factor(film_dose_factor=None)

Apply a normalisation factor to film dose.

apply_ref_factor(ref_dose_factor=None)

Apply a normalisation factor to reference dose.

apply_shifts_ref()

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

computeDiff()

Compute the difference map with the reference image.

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

Compute Gamma (using pymedphys.gamma).

Parameters:

• doseTA (float, optional, default=2) – Dose to agreement threshold [%].

• distTA (float, optional, default=2) – Distance to agreement threshold [mm].

• threshold (float, optional, default=0.1) – The percent lower dose cutoff below which gamma will not be calculated. Must be between 0 and 1.

• norm_val (float or None, optional, default=None) – Normalization value [cGy] of the reference dose, used to calculate the dose to agreement threshold and lower dose threshold. If None, no normalization is applied.

• local_gamma (bool, optional, default=False) – Whether to use local gamma instead of global gamma.

• max_gamma (float or None, optional, default=None) – The maximum gamma value to search for. Can speed up calculation by stopping the search once gamma values exceed this parameter.

• random_subset (float or None, optional, default=None) – If set, calculates gamma for only a random subset fraction of the reference grid to speed up calculation. Must be between 0 and 1.

Returns:

The computed gamma map as an ArrayImage object.

Return type:

ArrayImage

computeHDmedianDiff(threshold=0.8, ref='max')

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

Parameters:

• threshold (float, optional, default=0.8) – The relative threshold (with respect to ‘ref’) used to determine the high dose region. Must be between 0 and 1.

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

crop_film()

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)

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)

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

Parameters:

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

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

• distTA (float, optional, default=3.0) – Distance to agreement threshold [mm].

• threshold (float, optional, default=0.1) – The percent lower dose cutoff below which gamma will not be calculated. Must be between 0 and 1.

• norm_val (float or 'max', optional, default='max') – 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.

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

• max_gamma (float, optional, default=None) – 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.

• random_subset (float, optional, default=None) – Used to only calculate a random subset fraction of the reference grid, to speed up calculation. Must be between 0 and 1.

get_factor_from_roi_press_enter(event)

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

get_profile_offset(x, y, direction, side='left', xlim=None)

Open an interactive plot where the user can move the measured profile with respect to the reference profile to compute the spatial offset between the two.

Parameters:

• x (int) – X position for the profile plot, in pixels (horizontal direction).

• y (int) – Y position for the profile plot, in pixels (vertical direction).

• direction (str) – Direction of the profile, either ‘x’ (horizontal) or ‘y’ (vertical).

• side (str, optional, default='left') – Side of the profile to match, either ‘left’ or ‘right’.

• xlim (tuple of (float, float), optional) – X-axis limits for profile plotting.

get_profile_offsets(x=None, y=None, x_xlim=None, y_xlim=None)

Start an interactive process where the user can move the measured profile with respect to the reference profile 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.

Parameters:

• x (int, optional) – The x position of the profile to plot, in pixels. Defaults to the center of the reference dose.

• y (int, optional) – The y position of the profile to plot, in pixels. Defaults to the center of the reference dose.

• x_xlim (tuple of (float, float), optional) – X-axis limits for X profile plotting.

• y_xlim (tuple of (float, float), optional) – X-axis limits for Y profile plotting.

move_iso_center()

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)

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)

Set the markers’ coordinates when the mouse is double-clicked.

onclose(event)

Handle the figure close event.

ontype(event)

Handle keyboard events for rotation, flipping, and marker movement.

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

Plot a histogram of gamma map values.

Parameters:

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

• bins (int, sequence, or str, optional, default='auto') – Determines the number of bins in the histogram.

• range (tuple or None, optional, default=[0, 3]) – Determines the range of values shown in the histogram.

plot_gamma_pass_hist(ax=None, bin_size=50)

Plot a histogram of gamma map pass rate vs dose.

Parameters:

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

• bin_size (float, optional, default=50) – 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.

plot_gamma_var(param, ax=None, start=0.5, stop=4, step=0.5, varTA=None)

Plot Gamma pass rate as a function of a varying parameter (either doseTA or distTA).

Parameters:

• param (str) – The parameter to vary, either ‘DoseTA’ (dose to agreement threshold) or ‘DistTA’ (distance to agreement threshold).

• ax (matplotlib.pyplot.Axes, optional, default=None) – Axis in which to plot the graph. If None, a new plot is created.

• start (float, optional, default=0.5) – Minimum value of the parameter to vary.

• stop (float, optional, default=4.0) – Maximum value of the parameter to vary.

• step (float, optional, default=0.5) – Increment of the parameter value between start and stop.

• varTA (float, optional) – Value for dose or distance used in the variable dose or distance gamma analysis (based on param) Default is None (which will take value used in previous gamma analysis)

plot_gamma_varDistTA(ax=None, start=0.5, stop=4, step=0.5, varTA=None)

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:

• ax (matplotlib.pyplot.Axes, optional, default=None) – Axis in which to plot the graph. If None, a new plot is made.

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

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

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

• varTA (float, optional) – Value for dose used in the variable distance gamma analysis Default is None (which will take value used in previous gamma analysis)

plot_gamma_varDoseTA(ax=None, start=0.5, stop=4, step=0.5, varTA=None)

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:

• ax (matplotlib.pyplot.Axes, optional, default=None) – Axis in which to plot the graph. If None, a new plot is made.

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

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

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

• varTA (float, optional) – Value for distance used in the variable dose gamma analysis Default is None (which will take value used in previous gamma analysis)

plot_markers()

Plot the markers on the figure.

plot_profile(ax=None, profile='x', position=None, title=None, diff=False, offset=0, vertical_line=None, xlim=None, ylim='auto')

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

Parameters:

• ax (matplotlib.pyplot.Axes, optional, default=None) – Axis in which to plot the graph. If None, a new plot is made.

• profile ({'x', 'y'}, optional, default='x') – The orientation of the profile to plot (x: horizontal, y: vertical).

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

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

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

• offset (int, optional, default=0) – 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 could have a known offset due to gantry sag, and you may want to correct for it on the profile.

• vertical_line (int, optional, default=None) – If set, a dashed vertical line is plotted on the profile at this position.

• xlim (tuple, optional, default=None) – If given, xlim will be passed to ax.set_xlim(xlim) to set the x-axis limits.

• ylim (tuple, 'max', or 'auto', optional, default='auto') – If given a tuple, ylim will be passed to ax.set_ylim(ylim) to set the y-axis limits. If ‘max’, ylim goes from 0 to 105% of the maximum reference dose. If ‘auto’, ylim goes from 0 to 105% of the maximum of either the current reference or film dose profile.

publish_pdf(filename=None, author=None, unit=None, notes=None, open_file=False, x=None, y=None, plot_clusters_analysis=False, iso_levels=None, xlim_margin_mm=10, **kwargs)

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)

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, rot=0, threshold=10, register_using_gradient=False, markers_center=None)

Starts the registration procedure between film and reference dose.

Parameters:

• shift_y (shift_x /) – Apply a shift [mm] in the x/y direction between reference dose and film dose. Used if there is a known shift between the registration point in the reference image and the film image.

• rot (float, optional, default=0) – Apply a known rotation [degrees] between reference dose and film dose. Used if the markers on the reference image are known to be not perfectly aligned in an horizontal/vertical line.

• threshold (int, optional, default=10) – Threshold value [cGy] used in detecting film edges for auto-cropping.

• register_using_gradient (bool, optional, default=False) – Determine if the registration results (overlay of film/ref dose) will be displayed after applying a sobel filter to improve visibility of sharp dose gradients.

• markers_center (list of 3 floats, optional, default=None) – Coordinates [mm] in the reference dose corresponding to the marks intersection on the film (R-L, I-S, P-A). It will be used to align the reference point on the film (given by the intersection of the two lines determined by the four marks made on the edges of the film) to an absolute position in the reference dose. If None, the film reference point will be positioned to the center of the reference dose.

remove_rotation()

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

save_current_figure(filename, **kwargs)

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()

Start the interactive plot where the 4 markers on the film must be identified.

set_profile(event, axes)

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

show_cluster_analysis(cluster_id=0, xlim_margin_mm=10, figsize=(10, 10), levels=None)

Display the dose distribution with cluster analysis, including dose distribution, cluster location, isodoses, and profiles.

Parameters:

• cluster_id (int, optional, default=0) – The ID of the cluster to display.

• xlim_margin_mm (int, optional, default=10) – The margin [mm] to add to the x-axis limits around the cluster location.

• figsize (tuple of (float, float), optional, default=(10, 10)) – Width and height of the figure in inches.

• levels (list of float, optional, default=None) – Specific dose levels to plot as isodose lines. If None, default levels are used.

show_gamma_stats(figsize=(10, 10), show_hist=True, show_pass_hist=True, show_varDistTA=False, show_varDoseTA=False)

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

Parameters:

• figsize (tuple of (float, float), optional, default=(10, 10)) – Width and height of the figure in inches.

• show_hist (bool, optional, default=True) – Whether to display the gamma map histogram subplot.

• show_pass_hist (bool, optional, default=True) – Whether to display the gamma pass rate vs dose histogram subplot.

• show_varDistTA (bool, optional, default=False) – Whether to display the gamma pass rate vs variable distance to agreement threshold subplot.

• show_varDoseTA (bool, optional, default=False) – Whether to display the gamma pass rate vs variable dose to agreement threshold subplot.

show_isodoses(ax=None, levels=None, colors=None, show_ruler=True, figsize=(15, 15))

Display isodose lines for the film dose and reference dose on a given axis.

Parameters:

• ax (matplotlib.pyplot.Axes, optional, default=None) – Axis in which to plot the isodose lines. If None, a new figure and axis are created.

• levels (list of float, optional, default=None) – Specific dose levels to plot as isodose lines. If None, levels are set to 20%, 40%, 60%, and 80% of the maximum reference dose.

• colors (list of str or matplotlib.colors, optional, default=None) – Colors to use for the isodose lines. If None, a default colormap is used.

• show_ruler (bool, optional, default=True) – Whether to add an interactive ruler to measure distances on the plot using the mouse.

• figsize (tuple of (float, float), optional, default=(15, 15)) – Width and height of the figure in inches if a new figure is created.

show_profiles(axes, x, y, figsize=(10, 10))

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')

Show 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 to increase dose gradients visibility.

show_results(fig=None, x=None, y=None, show=True)

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, default=None) – Figure in which to plot the graph. If None, a new figure is made.

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

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

tune_registration()

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.