Calibration module documentation¶
Overview¶
The calibration module actually consists of two submodules: tg51
and trs398
, each addressing their respective protocol.
Both modules contain functions and classes for calculation the protocol dose. The modules have some overlap, especially with
basic functions as well as helper functions. The modules have tried to use the vocabulary of the respective protocol, but
occasionally there are differences when we felt that using the same name was clearer. See the vocabulary section for full definitions.
Note
Besides the typical calculations one would expect, the modules also include helper functions, such as a PDD to TPR converter so that a TG51 calculation can determine kQ from TPR and avoid the tedious PDDx. Additionally, pressure unit converters exist to go from the various units of pressure to kPa which is what pylinac uses.
Vocabulary that may be different than the protocol¶
voltage_reference
: Used in both TG51 and TRS398 for the voltage used when taking a reference reading; commonly 300V.voltage_reduced
: Use in both TG51 and TRS398 for the lower voltage used to determine ks/Pion; commonly 150V.m_reference
: The ion chamber reading at the reference voltage.m_reduced
: The ion chamber reading at the reduced voltage.m_opposite
: The ion chamber reading at the opposite polarity of the reference voltage: commonly +300V.
Vocabulary not listed here should be the same as the respective protocol.
TG51¶
Equation Definitions¶
Equation definitions are as follows:
Ptp (Temp/Pressure correction)  TG51 Eqn. 10:
\[\frac{273.2+T}{273.2+22} * \frac{101.33}{P}\]Warning
Temperature is in Celsius and pressure is in kPa. Use the helper functions
fahrenheit2celsius()
,mmHg2kPa()
, andmbar2kPa()
as needed.Ppol (Polarity correction)  Rather than using TG51 Eqn. 9, we opt instead for TRS398 Eqn xx, which uses the absolute values of the positive and negative voltages. This is the same results as Eqn. 9 but without worrying about signs.:
\[\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 & Rogers 2014
The study of Muir & Rogers 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)\]
Functionbased 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
,
TG51ElectronLegacy
and TG51ElectronModern
classes which will calculate all necessary corrections and
values.
Note
The Photon class uses kQ values from the TG51 addendum. The Legacy Electron class will make the user specify a kecal value and measure Pgradient. The Modern Electron class will calculate kQ completely from R50 and the chamber from Muir & Rogers 2014 paper, no kecal or Pgradient needed.
"""A script to calculate TG51 dose using pylinac functions and following the TG51 photon form"""
from pylinac.calibration import tg51
ENERGY = 6
TEMP = 22.1
PRESS = tg51.mmHg2kPa(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, but we'll run it through anyway just for show
pdd10x = tg51.pddx(pdd=66.4, energy=ENERGY)
# Section 5 (kQ)
kq = tg51.kq_photon_pddx(chamber=CHAMBER, pddx=pdd10x)
# Alternatively, get kQ from TPR (way quicker to measure, without needing to measure TPR!)
tpr = tg51.tpr2010_from_pdd2010(pdd2010=(38.0/66.4))
kq = tg51.kq_photon_tpr(chamber=CHAMBER, tpr=tpr)
# Section 6 (Temp/Press)
p_tp = tg51.p_tp(temp=TEMP, press=PRESS)
# Section 7 (polarity)
m_reference = (25.66, 25.67, 25.66)
m_opposite = (25.67, 25.67, 25.68)
p_pol = tg51.p_pol(m_reference=m_reference, m_opposite=m_opposite)
# Section 8 (ionization)
m_reduced = (25.61, 25.62)
p_ion = tg51.p_ion(voltage_reference=300, voltage_reduced=150, m_reference=m_reference, m_reduced=m_reduced)
# 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_reference=m_reference)
# 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.calibration import tg51
ENERGY = 6
TEMP = 22.1
PRESS = tg51.mmHg2kPa(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(
unit='TrueBeam1',
chamber=CHAMBER,
temp=TEMP, press=PRESS,
n_dw=ND_w, p_elec=P_ELEC,
measured_pdd10=66.4, lead_foil=None,
clinical_pdd10=66.5, energy=ENERGY,
voltage_reference=300, voltage_reduced=150,
m_reference=(25.65, 25.66, 25.65),
m_opposite=(25.64, 25.65, 25.65),
m_reduced=(25.64, 25.63, 25.63),
mu=MU, tissue_correction=1.0
)
# Done!
print(tg51_6x.dose_mu_dmax)
# examine other parameters
print(tg51_6x.pddx)
print(tg51_6x.kq)
print(tg51_6x.p_ion)
# change readings if you adjust output
tg51_6x.m_reference_adjusted = (25.44, 25.44, 25.43)
# print new dose value
print(tg51_6x.dose_mu_dmax_adjusted)
# generate a PDF for recordkeeping
tg51_6x.publish_pdf('TB1 6MV TG51.pdf', notes=['My notes', 'I used Pylinac to do this; so easy!'], open_file=False)
TRS398¶
Warning
Pylinac does not calculate electron dose in any other conditions than water; i.e. no solid water.
Equation Definitions¶
Ktp (Temp/Pressure correction):
\[\frac{273.2+T}{273.2+22} * \frac{101.33}{P}\]Warning
Temperature is in Celsius and pressure is in kPa. Use the helper functions fahrenheit2celsius, mmHg2kPa, and mbar2kPa as needed.
Kpol (Polarity correction):
\[\frac{M^+_{raw}+M^_{raw}}{2*M_{raw}}\]Ks (Ion collection correction; only for pulsed beams):
\[a_{0} + a_{1}*(\frac{M_{1}}{M_{2}}) + a_{2}*(\frac{M_{1}}{M_{2}})^2\]Zref (Reference electron depth; cm)  TRS398 7.2:
\[0.6*R_{50}  0.1\]R50 (Beam quality specifier; 50% dose depth; cm)  TRS398 7.1:
\[\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}\]\(D^Q_{w}\) photon (Dose to water at Zref from a photon or electron beam of quality Q  TRS398 7.3:
\[D_{w,Q} = M_{Q}*N_{D,w,Qo}*k_{Q,Qo} (Gy)\]Mcorrected (corrected chamber reading):
\[M_{Q} = k_{s}*k_{TP}*K_{elec}*K_{pol}*M_{1}\]kQ,Qo for Photons (cylindrical chamberspecific quality conversion factor): TRS398 Table 6.III
kQ for Electrons (cylindrical chamberspecific quality conversion factor; calibrated in Co60): TRS398 Table 7.III
Functionbased Use¶
"""A script to calculate TRS398 dose using pylinac functions and following the TRS398 photon form"""
from pylinac.calibration import trs398
TEMP = 22.1
PRESS = trs398.mmHg2kPa(755.0)
CHAMBER = '30013' # PTW
K_ELEC = 1.000
ND_w = 5.443 # Gy/nC
MU = 200
# Section 3 (dosimeter corrections)
k_tp = trs398.k_tp(temp=TEMP, press=PRESS)
k_pol = trs398.k_pol(m_reference=(25.66, 25.67, 25.66), m_opposite=(25.65, 25.66, 25.66))
k_s = trs398.k_s(voltage_reference=300, voltage_reduced=150,
m_reference=(25.66, 25.67, 25.66), m_reduced=(25.63, 25.65, 25.64))
m_corrected = trs398.m_corrected(m_reference=(25.66, 25.67, 25.66),
k_tp=k_tp, k_elec=K_ELEC, k_pol=k_pol, k_s=k_s) \
/ MU
# Section 4 (kQ + dose at zref)
kq = trs398.kq_photon(chamber=CHAMBER, tpr=(39.2/68.1))
dose_mu_zref = m_corrected * ND_w * kq
# Section 5 (Dose at zmax)
# SSD setup
CLINICAL_PDD = 66.5
dose_mu_zmax = dose_mu_zref * 100 / CLINICAL_PDD
# SAD setup
CLINICAL_TMR = 0.666
dose_mu_zmax = dose_mu_zref / CLINICAL_TMR
# Done!
print(dose_mu_zmax)
Classbased Use¶
"""A script to calculate TRS398 dose using pylinac classes and following the TRS398 photon form"""
from pylinac.calibration import trs398
ENERGY = 6
TEMP = 22.1
PRESS = trs398.mmHg2kPa(755.0)
CHAMBER = '30013' # PTW
K_ELEC = 1.000
ND_w = 5.443 # Gy/nC
MU = 200
CLINICAL_PDD = 66.5
trs398_6x = trs398.TRS398Photon(
unit='TrueBeam1',
setup='SSD',
chamber=CHAMBER,
temp=TEMP, press=PRESS,
n_dw=ND_w,
clinical_pdd_zref=CLINICAL_PDD,
tpr2010=(38.2/66.6),
energy=ENERGY,
fff=False,
k_elec=K_ELEC,
voltage_reference=300, voltage_reduced=150,
m_reference=(25.65, 25.66, 25.65),
m_opposite=(25.64, 25.65, 25.65),
m_reduced=(25.64, 25.63, 25.63),
mu=MU, tissue_correction=1.0
)
# Done!
print(trs398_6x.dose_mu_zmax)
# examine other parameters
print(trs398_6x.kq)
print(trs398_6x.k_s)
print(trs398_6x.k_tp)
# change readings if you adjust output
trs398_6x.m_reference_adjusted = (25.44, 25.44, 25.43)
# print new dose value
print(trs398_6x.dose_mu_zmax_adjusted)
# generate a PDF for recordkeeping
trs398_6x.publish_pdf('TB1 6MV TRS398.pdf', notes=['My notes', 'I used Pylinac to do this; so easy!'], open_file=False)
TG51 API Documentation¶

pylinac.calibration.tg51.
mmHg2kPa
(mmHg: float) → float[source]¶ Utility function to convert from mmHg to kPa.

pylinac.calibration.tg51.
mbar2kPa
(mbar: float) → float[source]¶ Utility function to convert from millibars to kPa.

pylinac.calibration.tg51.
fahrenheit2celsius
(f: float) → float[source]¶ Utility function to convert from Fahrenheit to Celsius.

pylinac.calibration.tg51.
tpr2010_from_pdd2010
(*, pdd2010: float) → float[source]¶ Calculate TPR20,10 from PDD20,10. From TRS398 pg 62 and Followill et al 1998 eqn 1.

pylinac.calibration.tg51.
p_tp
(*, temp: Union[int, float], press: Union[int, float]) → float[source]¶ Calculate the temperature & pressure correction.
Parameters:  temp (float (1727)) – The temperature in degrees Celsius.
 press (float (91111)) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.

pylinac.calibration.tg51.
p_pol
(*, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_opposite: Union[int, float, list, tuple, numpy.ndarray]) → float[source]¶ Calculate the polarity correction.
Parameters:  m_reference (number, array) – The readings of the ion chamber at the reference polarity and voltage.
 m_opposite (number, array) – The readings of the ion chamber at the polarity opposite the reference. The sign does not make a difference.
Raises: BoundsError if calculated Ppol is >1% from 1.0.

pylinac.calibration.tg51.
p_ion
(*, voltage_reference: int, voltage_reduced: int, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_reduced: Union[int, float, list, tuple, numpy.ndarray]) → float[source]¶ Calculate the ion chamber collection correction.
Parameters:  voltage_reference (int) – The “high” voltage; same as the TG51 measurement voltage.
 voltage_reduced (int) – The “low” voltage; usually half of the high voltage.
 m_reference (float, iterable) – The readings of the ion chamber at the “high” voltage.
 m_reduced (float, iterable) – The readings of the ion chamber at the “low” voltage.
Raises: BoundsError if calculated Pion is outside the range 1.001.05.

pylinac.calibration.tg51.
d_ref
(*, i_50: float) → float[source]¶ Calculate the dref of an electron beam based on the I50 depth.
Parameters: i_50 (float) – The value of I50 in cm.

pylinac.calibration.tg51.
r_50
(*, i_50: float) → float[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.calibration.tg51.
kp_r50
(*, r_50: float) → float[source]¶ Calculate k’R50 for Farmerlike chambers.
Parameters: r_50 (float (29)) – The R50 value in cm.

pylinac.calibration.tg51.
pq_gr
(*, m_dref_plus: Union[int, float, list, tuple, numpy.ndarray], m_dref: Union[int, float, list, tuple, numpy.ndarray]) → float[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.calibration.tg51.
m_corrected
(*, p_ion: float, p_tp: float, p_elec: float, p_pol: float, m_reference: Union[int, float, list, tuple, numpy.ndarray]) → float[source]¶ Calculate M_corrected, the ion chamber reading with all corrections applied.
Parameters:  p_ion (float (1.001.05)) – The ion collection correction.
 p_tp (float (0.921.08)) – The temperature & pressure correction.
 p_elec (float (0.981.02)) – The electrometer correction.
 p_pol (float (0.981.02)) – The polarity correction.
 m_reference (float, iterable) – The raw ion chamber reading(s).
Returns: Return type: float

pylinac.calibration.tg51.
pddx
(*, pdd: float, energy: int, lead_foil: Optional[str] = None) → float[source]¶ Calculate PDDx based on the PDD.
Parameters:  pdd ({>62.7, <89.0}) – 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. This is the default 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.calibration.tg51.
kq_photon_pddx
(*, chamber: str, pddx: float) → float[source]¶ Calculate kQ based on the chamber and clinical measurements of PDD(10)x. This will calculate kQ for photons for CYLINDRICAL chambers only.
Parameters:  chamber (str) – The chamber of the chamber. Valid values are those listed in Table III of Muir and Rogers and Table I of the TG51 Addendum.
 pddx ({>63.0, <86.0}) –
The PHOTONONLY PDD measurement at 10cm depth for a 10x10cm2 field.
Note
Use the
pddx()
function to convert PDD to PDDx as needed.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.

pylinac.calibration.tg51.
kq_photon_tpr
(*, chamber: str, tpr: float) → float[source]¶ Calculate kQ based on the chamber and clinical measurements of TPR20,10. This will calculate kQ for photons for CYLINDRICAL chambers only.
Parameters:  chamber (str) – The chamber of the chamber. Valid values are those listed in Table III of Muir and Rogers and Table I of the TG51 Addendum.
 tpr ({>0.630, <0.860}) –
The TPR(20,10) value.
Note
Use the
tpr2010_from_pdd2010()
function to convert from PDD without needing to take TPR measurements.

pylinac.calibration.tg51.
kq_electron
(*, chamber: str, r_50: float) → float[source]¶ Calculate kQ based on the chamber and clinical measurements. This will calculate kQ for electrons for CYLINDRICAL chambers only according to Muir & Rogers.
Parameters:  chamber (str) – The chamber of the chamber. Valid values are those listed in Tables VI and VII of Muir and Rogers 2014.
 r_50 (float) – The R50 value in cm of an electron beam.

class
pylinac.calibration.tg51.
TG51Photon
(*, institution: str = '', physicist: str = '', unit: str, measurement_date: str = '', temp: Union[int, float], press: Union[int, float], chamber: str, n_dw: float, p_elec: float, electrometer: str = '', measured_pdd10: Optional[float] = None, lead_foil: Optional[str] = None, clinical_pdd10: float, energy: int, fff: bool = False, voltage_reference: int, voltage_reduced: int, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_opposite: Union[int, float, list, tuple, numpy.ndarray], m_reduced: Union[int, float, list, tuple, numpy.ndarray], mu: int, tissue_correction: float = 1.0, m_reference_adjusted: Union[int, float, list, tuple, numpy.ndarray, None] = None)[source]¶ Bases:
pylinac.calibration.tg51.TG51Base
Class for calculating absolute dose to water using a cylindrical chamber in a photon beam.
Parameters:  institution (str) – Institution name.
 physicist (str) – Physicist performing calibration.
 unit (str) – Unit name; e.g. TrueBeam1.
 measurement_date (str) – Date of measurement. E.g. 10/22/2018.
 temp (float) – The temperature in Celsius. Use
fahrenheit2celsius()
to convert if necessary.  press (float) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.  energy (float) – Nominal energy of the beam in MV.
 chamber (str) – Chamber model. Must be one of the listed chambers in TG51 Addendum.
 n_dw (float) – NDW value in Gy/nC.
 p_elec (float) – Electrometer correction factor; given by the calibration laboratory.
 measured_pdd10 (float) – The measured value of PDD(10); will be converted to PDDx(10) and used for calculating kq.
 lead_foil ({None, '50cm', '30cm'}) – Whether a lead foil was used to acquire PDD(10)x and where its position was. Used to calculate kq.
 clinical_pdd10 (float) – The PDD used to correct the dose at 10cm back to dmax. Usually the TPS PDD(10) value.
 voltage_reference (int) – Reference voltage; i.e. voltage when taking the calibration measurement.
 voltage_reduced (int) – Reduced voltage; usually half of the reference voltage.
 m_reference (float, tuple) – Ion chamber reading(s) at the reference voltage.
 m_opposite (float, tuple) – Ion chamber reading(s) at the opposite voltage of reference.
 m_reduced (float, tuple) – Ion chamber reading(s) at the reduced voltage.
 mu (int) – The MU delivered to measure the reference reading. E.g. 200.
 fff (bool) – Whether the beam is FFF or flat.
 tissue_correction (float) – Correction value to calibration to, e.g., muscle. A value of 1.0 means no correction (i.e. water).

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.

dose_mu_10_adjusted
¶ The dose/mu at 10cm depth after adjustment.

dose_mu_dmax_adjusted
¶ The dose/mu at dmax depth after adjustment.

publish_pdf
(filename: str, notes: Optional[list] = None, open_file: bool = False, metadata: Optional[dict] = 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.
 open_file (bool) – Whether to open the file after creation. Will use the default PDF program.
 metadata (dict) – Any data that should be appended to every page of the report. This differs from notes in that metadata is at the top of every page while notes is at the bottom of the report.

class
pylinac.calibration.tg51.
TG51ElectronLegacy
(*, institution: str = '', physicist: str = '', unit: str = '', measurement_date: str = '', energy: int, temp: Union[int, float], press: Union[int, float], chamber: str, k_ecal: float, n_dw: float, electrometer: str = '', p_elec: float, clinical_pdd: float, voltage_reference: int, voltage_reduced: int, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_opposite: Union[int, float, list, tuple, numpy.ndarray], m_reduced: Union[int, float, list, tuple, numpy.ndarray], m_gradient: Union[int, float, list, tuple, numpy.ndarray], cone: str, mu: int, i_50: float, tissue_correction: float = 1.0, m_reference_adjusted=None)[source]¶ Bases:
pylinac.calibration.tg51.TG51Base
Class for calculating absolute dose to water using a cylindrical chamber in an electron beam.
Parameters:  institution (str) – Institution name.
 physicist (str) – Physicist performing calibration.
 unit (str) – Unit name; e.g. TrueBeam1.
 measurement_date (str) – Date of measurement. E.g. 10/22/2018.
 temp (float (1727)) – The temperature in degrees Celsius.
 press (float (91111)) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.  chamber (str) – Chamber model; only for bookkeeping.
 n_dw (float) – NDW value in Gy/nC. Given by the calibration laboratory.
 k_ecal (float) – Kecal value which is chamber specific. This value is the major difference between the legacy class and modern class where no kecal is needed.
 p_elec (float) – Electrometer correction factor; given by the calibration laboratory.
 clinical_pdd (float) – The PDD used to correct the dose back to dref.
 voltage_reference (float) – Reference voltage; i.e. voltage when taking the calibration measurement.
 voltage_reduced (float) – Reduced voltage; usually half of the reference voltage.
 m_reference (float, tuple) – Ion chamber reading(s) at the reference voltage.
 m_opposite (float, tuple) – Ion chamber reading(s) at the opposite voltage of reference.
 m_reduced (float, tuple) – Ion chamber reading(s) at the reduced voltage.
 mu (int) – The MU delivered to measure the reference reading. E.g. 200.
 i_50 (float) – Depth of 50% ionization.
 tissue_correction (float) – Correction value to calibration to, e.g., muscle. A value of 1.0 means no correction (i.e. water).

r_50
¶ Depth of the 50% dose value.

dref
¶ Depth of the reference point.

pq_gr
¶ Gradient factor

kq
¶ The kQ value using classic TG51

dose_mu_dref
¶ cGy/MU at the depth of Dref.

dose_mu_dmax
¶ cGy/MU at the depth of dmax.

dose_mu_dref_adjusted
¶ cGy/MU at the depth of Dref.

dose_mu_dmax_adjusted
¶ cGy/MU at the depth of dmax.

publish_pdf
(filename: str, notes: Optional[list] = None, open_file: bool = False, metadata: Optional[dict] = 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.
 open_file (bool) – Whether to open the file after creation. Will use the default PDF program.
 metadata (dict) – Any data that should be appended to every page of the report. This differs from notes in that metadata is at the top of every page while notes is at the bottom of the report.

class
pylinac.calibration.tg51.
TG51ElectronModern
(*, institution: str = '', physicist: str = '', unit: str = '', measurement_date: str = '', energy: int, temp: Union[int, float], press: Union[int, float], chamber: str, n_dw: float, electrometer: str = '', p_elec: float, clinical_pdd: float, voltage_reference: int, voltage_reduced: int, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_opposite: Union[int, float, list, tuple, numpy.ndarray], m_reduced: Union[int, float, list, tuple, numpy.ndarray], cone: str, mu: int, i_50: float, tissue_correction: float, m_reference_adjusted=None)[source]¶ Bases:
pylinac.calibration.tg51.TG51Base
Class for calculating absolute dose to water using a cylindrical chamber in an electron beam.
Warning
This class uses the values of Muir & Rogers. These values are likely to be included in the new TG51 addendum, but are not official. The results can be up to 1% different. Physicists should use their own judgement when deciding which class to use. To use a manual kecal value, Pgradient and the classic TG51 equations use the
TG51ElectronLegacy
class.Parameters:  institution (str) – Institution name.
 physicist (str) – Physicist performing calibration.
 unit (str) – Unit name; e.g. TrueBeam1.
 measurement_date (str) – Date of measurement. E.g. 10/22/2018.
 press (float) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.  temp (float) – The temperature in Celsius.
 voltage_reference (int) – The reference voltage; i.e. the voltage for the calibration reading (e.g. 300V).
 voltage_reduced (int) – The reduced voltage, usually a fraction of the reference voltage (e.g. 150V).
 m_reference (array, float) – The reading(s) of the chamber at reference voltage.
 m_reduced (array, float) – The reading(s) of the chamber at the reduced voltage.
 m_opposite (array, float) – The reading(s) of the chamber at the opposite voltage from reference. Sign of the reading does not matter.
 k_elec (float) – The electrometer correction value given by the calibration laboratory. jyh,lykllp;ljljuhyk nmdrzj
 chamber (str) – Ion chamber model.
 n_dw (float) – NDW value in Gy/nC
 p_elec (float) – Electrometer correction given by the calibration laboratory.
 clinical_pdd (float) – The PDD used to correct the dose back to dref.
 mu (int) – MU delivered.
 i_50 (float) – Depth of 50% ionization
 tissue_correction (float) – Correction value to calibration to, e.g., muscle. A value of 1.0 means no correction (i.e. water).

r_50
¶ Depth of the 50% dose value.

dref
¶ Depth of the reference point.

kq
¶ The kQ value using the updated Muir & Rogers values from their 2014 paper, equation 11, or classically if kecal is passed.

dose_mu_dref
¶ cGy/MU at the depth of Dref.

dose_mu_dmax
¶ cGy/MU at the depth of dmax.

dose_mu_dref_adjusted
¶ cGy/MU at the depth of Dref.

dose_mu_dmax_adjusted
¶ cGy/MU at the depth of dmax.

publish_pdf
(filename: str, notes: Optional[list] = None, open_file: bool = False, metadata: Optional[dict] = 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.
 open_file (bool) – Whether to open the file after creation. Will use the default PDF program.
 metadata (dict) – Any data that should be appended to every page of the report. This differs from notes in that metadata is at the top of every page while notes is at the bottom of the report.
TRS398 API Documentation¶

pylinac.calibration.trs398.
k_s
(*, voltage_reference: int, voltage_reduced: int, m_reference: Union[int, float, list, tuple, numpy.ndarray], m_reduced: Union[int, float, list, tuple, numpy.ndarray]) → float[source]¶ Calculate the ion recombination effect using readings at two voltages. The voltages should have a ratio of 2, 2.5, 3, 3.5, 4, or 5.
Parameters:  voltage_reference (int) – The voltage at which calibration will be performed (e.g. 300V)
 voltage_reduced (int) – The voltage which is lower than reference (e.g. 150V)
 m_reference (array, float) – The reading(s) at the reference voltage.
 m_reduced (array, float) – The reading(s) at the reduced voltage.
Returns: k_s – The ion recombination factor.
Return type: float
Raises: ValueError
– If the voltage ratio is not valid.ValueError
– If the calculated ks value is outside the range (1.0, 1.05).

pylinac.calibration.trs398.
kq_photon
(*, chamber: str, tpr: float) → float[source]¶ Calculate the kQ factor for a photon beam given the chamber model and TPR20/10 using Table 6.III. Linear interpolation is used between given TPR ratios.
Parameters:  chamber (str) – Allowable chambers are those listed in Table 6.III that are also Farmertype (e.g. Exradin A14 Farmer).
 tpr (float) – The ratio of measured TPR(20cm) / TPR(10cm). Note that this can also be calculated from PDD. See
tpr2010_from_pdd2010()
.
Returns: kQ – The calculated kQ given table Table 6.III
Return type: float
Raises: KeyError
– If the passed chamber is not within the acceptable list.ValueError
– If the TPR is not within the range defined by Table 6.III

pylinac.calibration.trs398.
kq_electron
(*, chamber: str, r_50: float) → float[source]¶ Calculate the kQ factor for an electron beam given the chamber model and R50 using Table 7.III. Linear interpolation is used between given R50 values.
Parameters:  chamber (str) – The Farmertype chambers listed in Table 7.III (e.g. PTW 30004/30012).
 r_50 (float) – The depth of R50 in cm in water.
Returns: kQ – The calculated kQ from Table 7.III
Return type: float
Raises: KeyError
– If the passed chamber is not within the acceptable list.ValueError
– If the R50 is not within the range defined by Table 7.III

pylinac.calibration.trs398.
m_corrected
(*, m_reference, k_tp, k_elec, k_pol, k_s) → float[source]¶ The fully corrected chamber reading.
Parameters:  m_reference (array, float) – The chamber reading(s) at the calibration position.
 k_tp (float) – Temperature/Pressure correction. See
p_tp()
.  k_elec (float) – Electrometer correction; given by the calibration laboratory.
 k_pol (float) – Polarity correction. See
p_pol()
.  k_s (float) – Ion recombination correction. See
k_s()
.
Returns: m – The fully corrected chamber reading.
Return type: float

class
pylinac.calibration.trs398.
TRS398Photon
(*, institution: str = '', physicist: str = '', unit: str = '', measurement_date: str = '', electrometer: str = '', setup: str, chamber: str, n_dw: float, mu: int, tpr2010: float, energy: int, fff: bool, press: float, temp: float, voltage_reference: int, voltage_reduced: int, m_reference: Union[tuple, float], m_reduced: Union[tuple, float], m_opposite: Union[tuple, float], k_elec: float, clinical_pdd_zref: Optional[float] = None, clinical_tmr_zref: Optional[float] = None, tissue_correction: float = 1.0)[source]¶ Bases:
pylinac.calibration.trs398.TRS398Base
Calculation of dose to water at zmax and zref from a high energy photon beam. Setup can be SSD or SAD.
Parameters:  setup ({'SSD', 'SAD'}) – The physical setup of the calibration.
 institution (str) – Institution name.
 physicist (str) – Physicist performing calibration.
 unit (str) – Unit name; e.g. TrueBeam1.
 measurement_date (str) – Date of measurement. E.g. 10/22/2018.
 chamber (str) – Farmertype chamber model from Table 6.III.
 n_dw (float) – NDw of the chamber given by the calibration laboratory.
 mu (float, int) – The number of MU given per reading
 energy (int) – Nominal energy of the linac in MV; e.g. 6. Bookkeeping only.
 fff (bool) – Whether the beam is FFF or flat. Bookkeeping only.
 tpr2010 (float) – The value of TPR(20)/TPR(10). Can be derived from PDD; see
tpr2010_from_pdd2010()
.  press (float) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.  temp (float) – The temperature in Celsius.
 voltage_reference (int) – The reference voltage; i.e. the voltage for the calibration reading (e.g. 300V).
 voltage_reduced (int) – The reduced voltage, usually a fraction of the reference voltage (e.g. 150V).
 m_reference (array, float) – The reading(s) of the chamber at reference voltage.
 m_reduced (array, float) – The reading(s) of the chamber at the reduced voltage.
 m_opposite (array, float) – The reading(s) of the chamber at the opposite voltage from reference. Sign of the reading does not matter.
 k_elec (float) – The electrometer correction value given by the calibration laboratory.
 clinical_pdd_zref (optional, float) – The PDD at the depth of calibration. Use the actual percentage (e.g. 66.7 not 0.667). If not supplied the clinical_tmr_zref value must be supplied.
 clinical_tmr_zref (optional, float) – The TMR at the depth of calibration. If not supplied the clinical_pdd_zref value must be supplied.
 tissue_correction (float) – The correction of calibration to a medium other than water. Default value is 1 which is water. E.g. use 0.99 if calibrating to muscle.

kq
¶ kQ of the chamber and TPR.

dose_mu_zmax
¶ cGy/MU at a depth of zmax.

dose_mu_zmax_adjusted
¶ The dose/mu at dmax depth after adjustment.

publish_pdf
(filename: str, notes: Optional[list] = None, open_file: bool = False, metadata: Optional[dict] = 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.
 open_file (bool) – Whether to open the file after creation. Will use the default PDF program.
 metadata (dict) – Any data that should be appended to every page of the report. This differs from notes in that metadata is at the top of every page while notes is at the bottom of the report.

class
pylinac.calibration.trs398.
TRS398Electron
(*, institution: str = '', physicist: str = '', unit: str = '', measurement_date: str = '', electrometer: str = '', energy: str, cone: str, chamber: str, n_dw: float, mu: int, i_50: float, press: float, temp: float, voltage_reference: int, voltage_reduced: int, m_reference: tuple, m_reduced: tuple, m_opposite: tuple, k_elec: float, clinical_pdd_zref: float, tissue_correction: float = 1.0)[source]¶ Bases:
pylinac.calibration.trs398.TRS398Base
Calculation of dose to water at zmax and zref from a high energy electron beam.
Parameters:  institution (str) – Institution name.
 physicist (str) – Physicist performing calibration.
 unit (str) – Unit name; e.g. TrueBeam1.
 measurement_date (str) – Date of measurement. E.g. 10/22/2018.
 chamber (str) – Farmertype chamber model from Table 6.III.
 n_dw (float) – NDw of the chamber given by the calibration laboratory.
 mu (float, int) – The number of MU given per reading.
 i_50 (float) – The depth of ionization 50% in cm.
 press (float) – The value of pressure in kPa. Can be converted from mmHg and mbar; see
mmHg2kPa()
andmbar2kPa()
.  temp (float) – The temperature in Celsius.
 voltage_reference (int) – The reference voltage; i.e. the voltage for the calibration reading (e.g. 300V).
 voltage_reduced (int) – The reduced voltage, usually a fraction of the reference voltage (e.g. 150V).
 m_reference (array, float) – The reading(s) of the chamber at reference voltage.
 m_reduced (array, float) – The reading(s) of the chamber at the reduced voltage.
 m_opposite (array, float) – The reading(s) of the chamber at the opposite voltage from reference. Sign of the reading does not matter.
 k_elec (float) – The electrometer correction value given by the calibration laboratory.
 pdd_zref (optional, float) – The PDD at the depth of calibration. Use the actual percentage (e.g. 66.7 not 0.667). If not supplied the tmr_zref value should be supplied.
 tissue_correction (float) – The correction of calibration to a medium other than water. Default value is 1 which is water. E.g. use 0.99 if calibrating to muscle.

r_50
¶ The depth of R50 in cm, derived from I50.

zref
¶ Depth of the reference point.

kq
¶ kQ given the chamber and R50.

dose_mu_zmax
¶ cGy/MU at a depth of zmax.

dose_mu_zmax_adjusted
¶ The dose/mu at dmax depth after adjustment.

publish_pdf
(filename: str, notes: Optional[list] = None, open_file: bool = False, metadata: Optional[dict] = 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.
 open_file (bool) – Whether to open the file after creation. Will use the default PDF program.
 metadata (dict) – Any data that should be appended to every page of the report. This differs from notes in that metadata is at the top of every page while notes is at the bottom of the report.