dvha.models.dvh

Class to retrieve DVH data from SQL, calculate parameters dependent on DVHs, and extract plotting data

class dvha.models.dvh.DVH(uid=None, dvh_condition=None, dvh_bin_width=5, group=1)[source]

Bases: object

This class will retrieve DVHs and other data in the DVH SQL table meeting the given constraints, it will also parse the DVH_string into python lists and retrieve the associated Rx dose

Parameters
  • uid (list) – study_instance_uid’s to be included in results

  • dvh_condition (str) – a string in SQL syntax applied to a DVH Table query

  • dvh_bin_width (int) – retrieve every nth value from dvh_string in SQL

  • group (int) – either 1 or 2

dvhs_to_abs_vol(dvhs)[source]

Get DVHs in absolute volume

Parameters

dvhs (np.ndarray) – relative DVHs (dvh[bin, roi_index])

Returns

absolute DVHs

Return type

np.ndarray

get_cds_data(keys=None)[source]

Get data from this class in a format compatible with bokeh’s ColumnDataSource.data

Parameters

keys (list, optional) – Specify a list of DVH properties to be included

Returns

data from this class

Return type

dict

get_dose_to_volume(volume, volume_scale='absolute', dose_scale='absolute', compliment=False)[source]

Get the minimum dose to a specified volume

Parameters
  • volume (int, float) – the specified volume in cm^3

  • volume_scale (str, optional) – either ‘relative’ or ‘absolute’

  • dose_scale (str, optional) – either ‘relative’ or ‘absolute’

  • compliment (bool, optional) – return the max dose - value

Returns

the dose in Gy to the specified volume

Return type

list

get_percentile_dvh(percentile)[source]

Get a population DVH based on percentile

Parameters

percentile (float) – the percentile to calculate for each dose-bin. Passed into np.percentile()

Returns

a single DVH such that each bin is the given percentile of each bin over the whole sample

Return type

np.ndarray

get_plan_values(plan_column)[source]

Get values from the Plans table and store in order matching mrn / study_instance_uid

Parameters

plan_column (str) – name of the SQL column to be returned

Returns

values from the Plans table for the DVHs stored in this class

Return type

list

get_resampled_x_axis(resampled_bin_count=5000)[source]

Get the x_axis of a resampled dvh

Parameters

resampled_bin_count (int, optional) – Specify the number of bins used

Returns

the x axis of a resampled dvh

Return type

np.ndarray

get_rx_values(rx_column)[source]

Get values from the Rxs table and store in order matching mrn / study_instance_uid

Parameters

rx_column (str) – name of the SQL column to be returned

Returns

values from the Rxs table for the DVHs stored in this class

Return type

list

get_standard_stat_dvh(dose_scale='absolute', volume_scale='relative')[source]

Get a min, mean, median, max, and quartiles DVHs

Parameters
  • dose_scale (str, optional) – either ‘absolute’ or ‘relative’

  • volume_scale (str, optional) – either ‘absolute’ or ‘relative’

Returns

a standard set of statistical dvhs (‘min’, ‘q1’, ‘mean’, ‘median’, ‘q1’, and ‘max’)

Return type

dict

get_stat_dvh(stat_type='mean', dose_scale='absolute', volume_scale='relative')[source]

Get population DVH by statistical function

Parameters
  • stat_type (str) – either ‘min’, ‘mean’, ‘median’, ‘max’, or ‘std’

  • dose_scale (str, optional) – either ‘absolute’ or ‘relative’

  • volume_scale (str, optional) – either ‘absolute’ or ‘relative’

Returns

a single dvh where each bin is the stat_type of each bin for the entire sample

Return type

np.ndarray

get_summary()[source]

Get a summary of the data in this class. Used in bottom left of main GUI

Returns

Summary data

Return type

str

get_volume_of_dose(dose, dose_scale='absolute', volume_scale='absolute', compliment=False)[source]

Get the volume of an isodose contour defined by dose

Parameters
  • dose (int, float) – input dose use to calculate a volume of dose for entire sample

  • dose_scale (str, optional) – either ‘absolute’ or ‘relative’

  • volume_scale (str, optional) – either ‘absolute’ or ‘relative’

  • compliment (bool, optional) – return the ROI volume - value

Returns

a list of V_dose

Return type

list

property has_data

Check that this class has queried data

Returns

True if there is data returned from SQL

Return type

bool

resample_dvh(resampled_bin_count=5000)[source]

Resample DVHs with a new bin count

Parameters

resampled_bin_count (int) – Number of bins in reampled DVH

Returns

x-axis, y-axis of resampled DVHs

Return type

tuple

property x_axis

Get the x-axis for plotting

Returns

Dose axis

Return type

list

property x_data

Get the x-axes for plotting (one row per DVH)

Returns

x data for plotting

Return type

list

property y_data

Get y-values of the DVHs

Returns

all DVHs in order (i.e., same as mrn, study_instance_uid)

Return type

list

dvha.models.dvh.calc_eud(dvh, a, dvh_bin_width=1)[source]

EUD = sum[ v(i) * D(i)^a ] ^ [1/a]

Parameters
  • dvh (np.ndarray) – a single DVH as a list of numpy 1D array with 1cGy bins

  • a (float) – standard a-value for EUD calculations, organ and dose fractionation specific

  • dvh_bin_width (int, optional) – dose bin width of dvh

Returns

equivalent uniform dose

Return type

float

dvha.models.dvh.calc_tcp(gamma, td_tcd, eud)[source]

Tumor Control Probability / Normal Tissue Complication Probability 1.0 / (1.0 + (td_tcd / eud) ^ (4.0 * gamma))

Parameters
  • gamma (float) – Gamma_50

  • td_tcd (float) – Either TD_50 or TCD_50

  • eud (float) – equivalent uniform dose

Returns

TCP or NTCP

Return type

float

dvha.models.dvh.dose_to_volume(dvh, rel_volume, dvh_bin_width=1)[source]

Calculate the minimum dose to a relative volume for one DVH

Parameters
  • dvh (np.ndarray) – a single dvh

  • rel_volume (float) – fractional volume

  • dvh_bin_width (int, optional) – dose bin width of dvh

Returns

minimum dose in Gy of specified volume

Return type

float

dvha.models.dvh.volume_of_dose(dvh, dose, dvh_bin_width=1)[source]

Calculate the relative volume of an isodose line definted by dose for one DVH

Parameters
  • dvh (np.ndarray) – a single dvh

  • dose (float) – dose in cGy

  • dvh_bin_width (int, optional) – dose bin width of dvh

Returns

volume in cm^3 of roi receiving at least the specified dose

Return type

float