TG-51 module documentation

Overview

The TG-51 module contains a number of helper functions and classes that can calculate parameters for performing the TG-51 absolute linac dose calibration although there are some modifications from the original TG-51. The modifications include updated kQ and kecal values from Muir and Rodgers’ set of papers. Functions include all relevant calculations for TG-51 including PDDx, kQ, Dref, and chamber reading corrections. Where Muir & Rodgers’ values/equations are used they are specified in the documentation.

Classes include photon and electron calibrations using cylindrical chambers. Pass all the relevant raw measurements and the class will compute all corrections and corrected readings and dose at 10cm and dmax/dref.

Equation Definitions

Equation definitions are as follows:

  • Ptp (Temp/Pressure correction) - TG-51 Eqn. 10:

    Warning

    Pressure values in pylinac are in mmHg, not kPa as in TG-51.

    \[\frac{273.2+T}{273.2+22} * \frac{760}{P}\]
  • Ppol (Polarity correction) - TG-51 Eqn. 9:

    \[|\frac{M^+_{raw}-M^-_{raw}}{2*M_{raw}}|\]
  • Pion (Ion collection correction; only for pulsed beams) - TG-51 Eqn. 12:

    \[\frac{1-\frac{V_{H}}{V_{L}}}{\frac{M^H_{raw}}{M^L_{raw}} - \frac{V_{H}}{V_{L}}}\]
  • Dref (Reference electron depth; cm) - TG-51 Eqn. 18:

    \[0.6*R_{50} - 0.1\]
  • R50 (Beam quality specifier; 50% dose depth; cm) - TG-51 Eqn. 16 & 17:

    \[\begin{split}\begin{cases} 1.029*I_{50}-0.06 (cm) & 2\leq I_{50}\leq 10 \\ 1.059*I_{50}-0.37 (cm) & I_{50}\gt 10 \\ \end{cases}\end{split}\]
  • k’R50 (k’R50 for cylindrical chambers) - TG-51 Eqn. 19:

    \[0.9905+0.0710e^\frac{-R_{50}}{3.67}\]
  • PQ_gr (PQ gradient correction for cylindrical chambers) - TG-51 Eqn. 21:

    \[\frac{M_{raw}(d_{ref}+0.5*r_{cav})}{M_{raw}*d_{ref}}\]
  • PDDx (PDD from photons only) - TG-51 Eqns. 13, 14 & 15:

    \[\begin{split}\begin{cases} PDD(10) & energy < 10 \\ 1.267*PDD(10)-20.0 & 75\leq PDD(10)\leq 89 \\ PDD(10)_{Pb} & lead@50cm, PDD(10)_{Pb} < 73 \\ (0.8905+0.00150*PDD(10)_{Pb})*PDD(10)_{Pb} & lead@50cm, PDD(10)_{Pb} \geq 73 \\ PDD(10)_{Pb} & lead@30cm, PDD(10)_{Pb} < 71 \\ (0.8116+0.00264*PDD(10)_{Pb})*PDD(10)_{Pb} & lead@30cm, PDD(10)_{Pb} \geq 71 \end{cases}\end{split}\]
  • M-corrected (corrected chamber reading) - TG-51 Eqn. 8:

    \[P_{ion}*P_{TP}*P_{elec}*P_{pol}*M_{raw}\]
  • kQ for Photons (cylindrical chamber-specific quality conversion factor) - TG-51 Addendum Eqn 1 & Table I:

    \[\begin{split}\begin{cases} A + B*10^-3*PDD(10)x+C*10^-5*(PDD(10)x)^2 & 63 < PDD(10)x < 86 \\ \end{cases}\end{split}\]

    Where A, B, and C are chamber-specific fitting values as given in Table I. Pylinac automatically retrieves values based on the chamber model passed to the function.

  • kQ for Electrons (cylindrical chamber-specific quality conversion factor) - Muir & Rodgers 2014

    The study of Muir & Rodgers was to find kecal values that could be determined soley from R50. Through Monte Carlo experiments, the optimal Pgradient was determined as well as fitting parameters for numerous common ion chambers. That study eliminates the need for Pgradient measurements. These kecal values will very likely be incorporated into the next TG-51 addendum (as has their kQ values for photons in the first addendum). From the paper, we can start with the known relationship given in Eqn. 9:

    \[k_{Q} = k_{Q,ecal} * k'_{Q}\]

    where Eqn. 11 states:

    \[k'_{Q} = a + b * R_{50}^{-c}\]

    Where a, b, and c are chamber-specific fitting values as given in Table VII. and where \(k_{Q,ecal}\) is given in Table VI.

  • \(D^Q_{w}\) photon (Dose to water at 10cm from a photon beam of quality Q - TG-51 Eqn. 3:

    \[M*k_{Q}*N^{60Co}_{D,w} (Gy)\]
  • \(D^Q_{w}\) electron (Dose to water at 10cm from an electron beam of quality Q - TG-51 Eqn. 6:

    \[M*P^Q_{gr}*k'_{R_{50}}*k_{ecal}*N^{60Co}_{D,w} (Gy)\]

Typical Use

Using the TG-51 module can be complementary to your existing workflow, or completely replace it. For example, you could use the kQ function to calculate kQ and then calculate the other corrections and values yourself. If you want something a little more complete, you can use the TG51Photon and TG51Electron classes which will completely calculate all necessary corrections and values.

Note

The Photon class uses kQ values from the TG-51 addendum and the Electron class uses kQ values from Muir & Rodgers 2014.

Function-based Use

"""A script to calculate TG-51 dose using pylinac functions and following the TG-51 photon form"""
from pylinac import tg51


ENERGY = 6
TEMP = 22.1
PRESS = 755.0
CHAMBER = '30013'  # PTW
P_ELEC = 1.000
ND_w = 5.443  # Gy/nC
MU = 200
CLINICAL_PDD = 66.5

# Section 4 (beam quality)
# since energy is 6MV, PDDx == PDD
pdd10x = 66.4

# Section 5 (kQ)
kq = tg51.kq(model=CHAMBER, pddx=pdd10x)

# Section 6 (Temp/Press)
p_tp = tg51.p_tp(temp=TEMP, press=PRESS)

# Section 7 (polarity)
m_raw = m_neg = (25.66, 25.67, 25.66)
m_pos = (25.67, 25.67, 25.68)
p_pol = tg51.p_pol(m_reference=m_neg, m_opposite=m_pos)

# Section 8 (ionization)
m_low = (25.64, 25.64, 25.65)
p_ion = tg51.p_ion(volt_high=300, volt_low=150, m_high=m_raw, m_low=m_low)

# Section 9 (M corrected)
m_corr = tg51.m_corrected(p_ion=p_ion, p_tp=p_tp, p_elec=P_ELEC, p_pol=p_pol, m_raw=m_raw)

# Section 10 (dose to water @ 10cm)
dose_10 = m_corr*kq*ND_w
dose_10_per_mu = dose_10 / MU

# Section 11 (dose/MU to water @ dmax)
dose_ddmax = dose_10_per_mu / CLINICAL_PDD

# Done!
print(dose_ddmax)

Class-based Use

"""A script to calculate TG-51 dose using pylinac classes and following the TG-51 photon form"""
from pylinac import tg51


ENERGY = 6
TEMP = 22.1
PRESS = 755.0
CHAMBER = '30013'  # PTW
P_ELEC = 1.000
ND_w = 5.443  # Gy/nC
MU = 200
CLINICAL_PDD = 66.5

tg51_6x = tg51.TG51Photon(temp=TEMP, press=PRESS, model=CHAMBER,
                          n_dw=ND_w, p_elec=P_ELEC,
                          measured_pdd=66.4, lead_foil=None,
                          clinical_pdd=66.5, energy=ENERGY,
                          volt_high=-300, volt_low=-150,
                          m_raw=(25.65, 25.66, 25.65),
                          m_opp=(25.64, 25.65, 25.65),
                          m_low=(25.64, 25.63, 25.63),
                          mu=MU, tissue_correction=1.0)

# Done!
print(tg51_6x.dose_mu_dmax)

# examine other parameters
tg51_6x.pddx
tg51_6x.kq
tg51_6x.p_ion

# change readings if you adjust output
tg51_6x.m_raw = (25.44, 25.44, 25.43)
# print new dose value
print(tg51_6x.dose_mu_dmax)

API Documentation

pylinac.tg51.p_tp(temp=22, press=760)[source]

Calculate the temperature & pressure correction.

Parameters:
  • temp (float) – The temperature in degrees Celsius.
  • press (float) – The pressure in mmHg.
pylinac.tg51.p_pol(m_reference=(1, 2), m_opposite=(-3, -4))[source]

Calculate the polarity correction.

Parameters:
  • m_reference (iterable) – The readings of the ion chamber at the reference polarity and voltage.
  • m_opposite (iterable) – The readings of the ion chamber at the polarity opposite the reference. This value should be of the opposite sign of the M reference value. If it’s not, its sign will automatically be flipped.
pylinac.tg51.p_ion(volt_high=300, volt_low=150, m_high=(1, 2), m_low=(3, 4))[source]

Calculate the ion chamber collection correction.

Parameters:
  • volt_high (int) – The “high” voltage; same as the TG51 measurement voltage.
  • volt_low (int) – The “low” voltage; usually half of the high voltage.
  • m_high (float, iterable) – The readings of the ion chamber at the “high” voltage.
  • m_low (float, iterable) – The readings of the ion chamber at the “low” voltage.
pylinac.tg51.d_ref(i_50)[source]

Calculate the dref of an electron beam based on the I50 depth.

Parameters:i_50 (float) – The value of I50 in cm.
pylinac.tg51.r_50(i_50)[source]

Calculate the R50 depth of an electron beam based on the I50 depth.

Parameters:i_50 (float) – The value of I50 in cm.
pylinac.tg51.kp_r50(r_50)[source]

Calculate k’R50 for Farmer-like chambers.

Parameters:r_50 (float) – The R50 value in cm.
pylinac.tg51.pq_gr(m_dref_plus=(1, 2), m_dref=(3, 4))[source]

Calculate PQ_gradient for a cylindrical chamber.

Parameters:
  • m_dref_plus (float, iterable) – The readings of the ion chamber at dref + 0.5rcav.
  • m_dref (float, iterable) – The readings of the ion chamber at dref.
pylinac.tg51.m_corrected(p_ion=1.0, p_tp=1.0, p_elec=1.0, p_pol=1.0, m_raw=(1.1, 2.2))[source]

Calculate M_corrected, the ion chamber reading with all corrections applied.

Parameters:
  • p_ion (float) – The ion collection correction.
  • p_tp (float) – The temperature & pressure correction.
  • p_elec (float) – The electrometer correction.
  • p_pol (float) – The polarity correction.
  • m_raw (float, iterable) – The raw ion chamber readings.
Returns:

Return type:

float

pylinac.tg51.pddx(pdd=66.4, energy=6, lead_foil=None)[source]

Calculate PDDx based on the PDD.

Parameters:
  • pdd ({>0.627, <0.890}) – The measured PDD. If lead foil was used, this assumes the pdd as measured with the lead in place.
  • energy (int) – The nominal energy in MV.
  • lead_foil ({None, '30cm', '50cm'}) – Applicable only for energies >10MV. Whether a lead foil was used to acquire the pdd. Use None if no lead foil was used and the interim equation should be used. Use 50cm if the lead foil was set to 50cm from the phantom surface. Use 30cm if the lead foil was set to 30cm from the phantom surface.
pylinac.tg51.kq(model='30010', pddx=None, tpr=None, r_50=None)[source]

Calculate kQ based on the model and clinical measurements. This will calculate kQ for both photons and electrons for CYLINDRICAL chambers only.

Parameters:
  • model (str) – The model of the chamber. Valid values are those listed in Table III of Muir and Rodgers and Table I of the TG-51 Addendum.
  • pddx ({>0.630, <0.860}) –

    The PHOTON-ONLY PDD measurement at 10cm depth for a 10x10cm2 field.

    Note

    Muir and Rogers state limits of 0.627 - 0.861. The TG-51 addendum states them as 0.63 and 0.86. The TG-51 addendum limits are used here.

  • tpr ({>0.623, <0.805}) – The TPR ratio of the 20cm measurement divided by the 10cm measurement.
  • r_50 (float) – The R50 value in cm of an electron beam.

Warning

Only 1 of pddx, tpr or r_50 can be defined.

class pylinac.tg51.TG51Photon(institution='', physicist='', unit='', measurement_date='', temp=22, press=760, model='30010', n_dw=5.9, p_elec=1.0, electrometer='', measured_pdd=66.4, lead_foil=None, clinical_pdd=66.4, energy=6, fff=False, volt_high=300, volt_low=150, m_raw=(1, 2), m_opp=(1, 2), m_low=(1, 2), mu=200, tissue_correction=1.0, adjusted_m_raw=None)[source]

Bases: pylinac.tg51.TG51Base

Class for calculating absolute dose to water using a cylindrical chamber in a photon beam.

temp
Type:float
press
Type:float
energy

Nominal energy of the beam in MV.

Type:float
model

Chamber model

Type:str
n_dw

NDW value in Gy/nC

Type:float
p_elec
Type:float
measured_pdd

The measured value of PDD(10); used for calculating kq.

Type:float
lead_foil

Whether a lead foil was used to acquire PDD(10)x and where its position was. Used to calculate kq.

Type:{None, ‘50cm’, ‘30cm’}
clinical_pdd

The PDD used to correct the dose at 10cm back to dmax. Usually the TPS PDD(10) value.

Type:float
volt_high
Type:float
volt_low
Type:float
m_raw
Type:float, tuple
m_opp
Type:float, tuple
m_low
Type:float, tuple
mu
Type:float
tissue_correction

Correction value to calibration to, e.g., muscle. A value of 1.0 means no correction (i.e. water).

Type:float
pddx

The photon-only PDD(10) value.

kq

The chamber-specific beam quality correction factor.

dose_mu_10

cGy/MU at a depth of 10cm.

dose_mu_dmax

cGy/MU at a depth of dmax.

adjusted_dose_mu_10

The dose/mu at 10cm depth after adjustment.

adjusted_dose_mu_dmax

The dose/mu at dmax depth after adjustment.

publish_pdf(filename, notes=None, open_file=False)[source]

Publish (print) a PDF containing the analysis and quantitative results.

Parameters:
  • filename (str, file-like object) – The file to write the results to.
  • notes (str, list) – Any notes to be added to the report. If a string, adds everything as one line. If a list, must be a list of strings; each string item will be a new line.
class pylinac.tg51.TG51Electron(institution='', physicist='', unit='', measurement_date='', energy=9, temp=22, press=760, model='30010', n_dw=5.9, electrometer='', p_elec=1.0, clinical_pdd=99.0, volt_high=300, volt_low=150, m_raw=(1, 2), m_opp=(1, 2), m_low=(1, 2), cone='15x15', mu=200, i_50=4, tissue_correction=1.0, adjusted_m_raw=None)[source]

Bases: pylinac.tg51.TG51Base

Class for calculating absolute dose to water using a cylindrical chamber in an electron beam.

temp
Type:float
press
Type:float
model

Chamber model

Type:str
n_dw

NDW value in Gy/nC

Type:float
p_elec
Type:float
clinical_pdd

The PDD used to correct the dose back to dref.

Type:float
volt_high
Type:float
volt_low
Type:float
m_raw
Type:float, tuple
m_opp
Type:float, tuple
m_low
Type:float, tuple
mu
Type:float
i_50

Depth of 50% ionization

Type:float
tissue_correction

Correction value to calibration to, e.g., muscle. A value of 1.0 means no correction (i.e. water).

Type:float
r_50

Depth of the 50% dose value.

dref

Depth of the reference point.

kq

The kQ value using the updated Muir & Rodgers values from their 2014 paper, equation 11.

dose_mu_dref

cGy/MU at the depth of Dref.

dose_mu_dmax

cGy/MU at the depth of dmax.

adjusted_dose_mu_dref

cGy/MU at the depth of Dref.

adjusted_dose_mu_dmax

cGy/MU at the depth of dmax.

publish_pdf(filename, notes=None)[source]

Publish (print) a PDF containing the analysis and quantitative results.

Parameters:
  • filename (str, file-like object) – The file to write the results to.
  • notes (str, list) – Any notes to be added to the report. If a string, adds everything as one line. If a list, must be a list of strings; each string item will be a new line.