TG51 module documentation¶
Overview¶
The TG51 module contains a number of helper functions and classes that can calculate parameters for performing the TG51 absolute linac dose calibration although there are some modifications from the original TG51. The modifications include updated kQ and kecal values from Muir and Rodgers’ set of papers. Functions include all relevant calculations for TG51 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)  TG51 Eqn. 10:
Warning
Pressure values in pylinac are in mmHg, not kPa as in TG51.
\[\frac{273.2+T}{273.2+22} * \frac{760}{P}\]Ppol (Polarity correction)  TG51 Eqn. 9:
\[\frac{M^+_{raw}M^_{raw}}{2*M_{raw}}\]Pion (Ion collection correction; only for pulsed beams)  TG51 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)  TG51 Eqn. 18:
\[0.6*R_{50}  0.1\]R50 (Beam quality specifier; 50% dose depth; cm)  TG51 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)  TG51 Eqn. 19:
\[0.9905+0.0710e^\frac{R_{50}}{3.67}\]PQ_gr (PQ gradient correction for cylindrical chambers)  TG51 Eqn. 21:
\[\frac{M_{raw}(d_{ref}+0.5*r_{cav})}{M_{raw}*d_{ref}}\]PDDx (PDD from photons only)  TG51 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}\]Mcorrected (corrected chamber reading)  TG51 Eqn. 8:
\[P_{ion}*P_{TP}*P_{elec}*P_{pol}*M_{raw}\]kQ for Photons (cylindrical chamberspecific quality conversion factor)  TG51 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 chamberspecific fitting values as given in Table I. Pylinac automatically retrieves values based on the chamber model passed to the function.
kQ for Electrons (cylindrical chamberspecific 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 TG51 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 chamberspecific 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  TG51 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  TG51 Eqn. 6:
\[M*P^Q_{gr}*k'_{R_{50}}*k_{ecal}*N^{60Co}_{D,w} (Gy)\]
Typical Use¶
Using the TG51 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 TG51 addendum and the Electron class uses kQ values from Muir & Rodgers 2014.
Functionbased Use¶
"""A script to calculate TG51 dose using pylinac functions and following the TG51 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)
Classbased Use¶
"""A script to calculate TG51 dose using pylinac classes and following the TG51 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 Farmerlike 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. Use50cm
if the lead foil was set to 50cm from the phantom surface. Use30cm
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 TG51 Addendum.
 pddx ({>0.630, <0.860}) –
The PHOTONONLY PDD measurement at 10cm depth for a 10x10cm2 field.
Note
Muir and Rogers state limits of 0.627  0.861. The TG51 addendum states them as 0.63 and 0.86. The TG51 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
orr_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 photononly PDD(10) value.

kq
¶ The chamberspecific 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, filelike 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, filelike 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.
