Radiation protection quantities for x-rays with uncertainties using SpekPy and Monte Carlo techniques
Project description
USpekPy
Radiation protection quantities for x-rays with uncertainties
Table of Contents
- What is USpekPy?
- Main features of USpekPy
- How to install USpekPy?
- Quick user guide
- How to get support?
- Documentation
- Contributors
- License
- Contributing to USpekPy
What is USpekPy?
USpekPy is a Python package that allows to compute mean radiation protection quantities for a simulated x-ray spectrum with uncertainties using Monte Carlo techniques. It is an open source, GPLv3-licensed library for the Python programming language. It is compatible with Python 3. USpekPy is based on the SpekPy package, which is a Python software toolkit for modelling the x-ray spectra from x-ray tubes.
Main features of USpekPy
USpekPy provides three features:
- Compute mean values of radiation protection quantities of an x-ray spectrum simulated using SpekPy. Specifically, it allows to compute the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient.
- Compute mean radiation protection quantities of an x-ray spectrum simulated using SpekPy with uncertainties using Monte Carlo techniques. Specifically, it allows to compute the first and second half-value layer for aluminium and copper, the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient.
- Perform batch simulation to compute the mean values and uncertainties of radiation protection quantities for several x-ray spectra simulated with SpekPy.
How to install USpekPy?
USpekPy can be installed from the Python Package Index (PyPI) by running the following command from a terminal:
pip install uspekpy
Quick user guide
Units and uncertainties
All the uncertainties are standard uncertainties, i.e., with a coverage factor of k = 1. The units of relative uncertainties are expressed as fraction of one. The next table shows the units of the quantities used in the package.
| Quantity | Unit |
|---|---|
| Distance | mm |
| Voltage | kV |
| Angle | deg |
| Energy | keV |
| Fluence | 1/cm² |
| Mass energy transfer coefficients of air | cm²/g |
| Air kerma | uGy |
| Mono-energetic K to H conversion coefficients | Sv/Gy |
Compute mean radiation protection quantities
This first example shows how to compute the mean values of some radiation protection quantities of an x-ray spectrum simulated using SpekPy. The considered x-ray spectrum is the one corresponding to the radiation quality N-60, which is obtained using 60 KeV of peak kilovoltage in the x-ray tube and filters of aluminum (4 mm) and copper (0.6 mm). The considered operational quantity is ambient dose equivalent, H*(10), with a radiation incidence angle of 0º at a distance of 1 m from the x-ray tube. The tool that USpekPy provides to do this is the SpekWrapper class.
The next python script shows how to compute the first and second half-value layers for aluminium and copper, the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient.
from uspekpy import SpekWrapper
# Define x-ray beam parameters for radiation quality N-60 (filter thickness, peak kilovoltage and anode angle)
my_filters = [
('Al', 4), # mm
('Cu', 0.6), # mm
('Sn', 0), # mm
('Pb', 0), # mm
('Be', 0), # mm
('Air', 1000) # mm
]
my_kvp = 60 # kV
my_th = 10 # deg
# Define path to CSV file containing mass energy transfer coefficients of air in terms of the energy
my_mu_csv = 'data/mu_tr_rho.csv'
# Define path to CSV file containing the monoenergetic air kerma-to-dose-equivalent conversion coefficients for H*(10)
my_hk_csv = 'data/h_k_h_amb_10.csv'
# Initialize an SpeckWrapper object and add filters
spectrum = SpekWrapper(kvp=my_kvp, th=my_th)
spectrum.multi_filter(my_filters)
# Calculate half-value layers for aluminum and copper
hvl1_al = spectrum.get_hvl1()
hvl2_al = spectrum.get_hvl2()
hvl1_cu = spectrum.get_hvl1(matl='Cu')
hvl2_cu = spectrum.get_hvl2(matl='Cu')
# Calculate mean energy
mean_energy = spectrum.get_mean_energy()
# Calculate mean air kerma
mean_kerma = spectrum.get_air_kerma(mass_transfer_coefficients=my_mu_csv)
# Calculate mean air kerma-to-dose-equivalent conversion coefficient for H*(10)
mean_hk = spectrum.get_mean_conversion_coefficient(
mass_transfer_coefficients=my_mu_csv, conversion_coefficients=my_hk_csv)
# Print results
print(f'First HVL for Al: {hvl1_al} mm')
print(f'Second HVL for Al: {hvl2_al} mm')
print(f'First HVL for Cu: {hvl1_cu} mm')
print(f'Second HVL for Cu: {hvl2_cu} mm')
print(f'Mean energy: {mean_energy} keV')
print(f'Air kerma: {mean_kerma} uGy')
print(f'Mean conversion coefficient for H*(10): {mean_hk} Sv/Gy')
The script output is:
First HVL for Al: 5.904510251136515 mm
Second HVL for Al: 6.239790098050192 mm
First HVL for Cu: 0.23502729534875702 mm
Second HVL for Cu: 0.2624330033450075 mm
Mean energy: 47.797974735384756 keV
Air kerma: 1.5902735973543143 uGy
Mean conversion coefficient for H*(10): 1.5909359863722154 Sv/Gy
Compute mean radiation protection quantities with uncertainties
This second example shows how to compute the mean values and uncertainties of some radiation protection quantities of an x-ray spectrum simulated using SpekPy. The considered x-ray spectrum is the one corresponding to the radiation quality N-60, which is obtained using 60 KeV of peak kilovoltage in the x-ray tube and filters of aluminum (4 mm) and copper (0.6 mm). The considered operational quantity is ambient dose equivalent, H*(10), with a radiation incidence angle of 0º at a distance of 1 m from the x-ray tube. The tool that USpekPy provides to do this is the USpek class.
The next python script shows how to compute the first and second half-value layers for aluminium and copper, the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient.
from uspekpy import USpek
# Define values and relative uncertainty (k=1) of x-ray beam parameters for radiation quality N-60
# (filter thickness, peak kilovoltage and anode angle)
my_beam = {
'kVp': (60, 0.01), # mm, fraction of one
'th': (20, 0.01), # mm, fraction of one
'Al': (4, 0.01), # mm, fraction of one
'Cu': (0.6, 0.01), # mm, fraction of one
'Sn': (0, 0), # mm, fraction of one
'Pb': (0, 0), # mm, fraction of one
'Be': (0, 0), # mm, fraction of one
'Air': (1000, 0.01) # mm, fraction of one
}
# Define path to CSV file containing mass energy transfer coefficients of air in terms of the energy
my_mu_csv = 'data/mu_tr_rho.csv'
# Define path to CSV file containing the monoenergetic air kerma-to-dose-equivalent conversion coefficients for H*(10)
my_hk_csv = 'data/h_k_h_amb_10.csv'
# Define relative uncertainty (k=1) of mass energy transfer coefficients of air
my_mu_std = 0.01 # fraction of one
# Initialize a USpekPy object with the defined beam parameters, mass energy transfer coefficients of air
# and monoenergetic air kerma-to-dose-equivalent conversion coefficients for H*(10)
s = USpek(beam_parameters=my_beam, mass_transfer_coefficients=my_mu_csv,
mass_transfer_coefficients_uncertainty=my_mu_std, conversion_coefficients=my_hk_csv)
# Run simulation with a given number of iterations
df = s.simulate(simulations_number=3)
# Define the path of the output file where the simulation results will be saved
my_output_csv = 'output/output.csv'
# Save results to a CSV file
df.to_csv(my_output_csv, index=True)
# Print results
print(df.to_string())
The script output is a table containing the randomly sampled values of the beam parameters and the computed mean radiation protection quantities of the simulated x-ray spectrum for each iteration of the Monte Carlo simulation. It also contains their mean values and standard uncertainties (k=1). The units are kV for the peak kilovoltage, deg for the anode angle, mm for the filter thickness, air gap and half-value layers, keV for the mean energy, Gy for the air kerma and Sv/Gy for the mean air kerma-to-dose-equivalent conversion coefficient.
# kVp (kV) th (deg) Air (mm) Al (mm) Cu (mm) Sn (mm) Pb (mm) Be (mm) HVL1 Al (mm) HVL2 Al (mm) HVL1 Cu (mm) HVL2 Cu (mm) Mean energy (keV) Air kerma (uGy) Mean conv. coeff. (Sv/Gy)
0 Iteration 1 59.929717 20.070882 996.150291 4.031398 0.591599 0.0 0.0 0.0 5.831812 6.172730 0.230861 0.258297 47.538305 1.599452 1.585449
1 Iteration 2 59.534814 20.485473 996.406825 4.003680 0.589934 0.0 0.0 0.0 5.781268 6.117909 0.227873 0.254629 47.303424 1.533225 1.581466
2 Iteration 3 59.596255 19.678848 996.920532 3.935728 0.606411 0.0 0.0 0.0 5.826152 6.157480 0.230388 0.256981 47.453653 1.488258 1.585720
3 Mean 59.686929 20.078401 996.492549 3.990269 0.595981 0.0 0.0 0.0 5.813078 6.149373 0.229707 0.256636 47.431794 1.540312 1.584211
4 Standard deviation 0.173500 0.329346 0.320239 0.040192 0.007406 0.0 0.0 0.0 0.022611 0.023103 0.001311 0.001517 0.097127 0.045670 0.001945
5 Relative uncertainty 0.002907 0.016403 0.000321 0.010073 0.012427 NaN NaN NaN 0.003890 0.003757 0.005708 0.005913 0.002048 0.029650 0.001228
Compute batch simulation for several x-ray spectra
This third example shows how to perform batch simulation to compute the mean values and uncertainties of radiation protection quantities for several x-ray spectra simulated with SpekPy. The considered x-ray spectrum is the one corresponding to the radiation quality N-60, which is obtained using 60 KeV of peak kilovoltage in the x-ray tube and filters of aluminum (4 mm) and copper (0.6 mm). The considered operational quantity is ambient dose equivalent, H*(10), with a radiation incidence angle of 0º at a distance of 1 m from the x-ray tube. The tool that USpekPy provides to do this is the batch_simulation() function.
To perform the batch simulation you need and input file where the parameters of each simulation are specified. This can be a CSV file or an Excel file.
- First column: simulation parameters' names: The first column contain the names of the quantities used as simulation parameters. They are grouped in general parameters (radiation quality, operational quantity, irradiation angle and number of simulations), value parameters (filters thickness, air gap, peak kilovoltage, anode angle, mass energy transfer coefficients of air and monoenergetic air kerma-to-dose-equivalent conversion coefficients) and relative uncertainty parameters (filters thickness, air gap, peak kilovoltage, anode angle, mass energy transfer coefficients). Units of value parameters are specified in the column. Relative uncertainties are fractional uncertainties, i.e., they are expressed as fractions of one. The name of the parameters must not be changed, since they are used for data parsing.
- Next columns: simulation parameters' values: The next columns contain the values of the simulation parameters, one column for each simulation case.
The next table shows the content of the input file for this example.
Case1 Case2
General NaN NaN
Quality N-60 N-60
Operational quantity H*(10) H*(10)
Irradiation angle (deg) 0 0
Number of simulations 3 3
Values NaN NaN
Al filter width (mm) 4 4
Cu filter width (mm) 0.6 0.6
Sn filter width (mm) 0 0
Pb filter width (mm) 0 0
Be filter width (mm) 0 0
Air gap width (mm) 1000 1000
Peak kilovoltage (kV) 60 60
Anode angle (deg) 20 20
Mass energy transfer coefficients of air file (keV and cm²/g) data/mu_tr_rho.csv data/mu_tr_rho.csv
Mono-energetic K to H conversion coefficients file (keV and Sv/Gy) data/h_k_h_amb_10.csv data/h_k_h_amb_10.csv
Relative uncertainties (k=1) NaN NaN
Al filter width (fraction of one) 0.01 0.01
Cu filter width (fraction of one) 0.01 0.01
Sn filter width (fraction of one) 0 0
Pb filter width (fraction of one) 0 0
Be filter width (fraction of one) 0 0
Air gap width (fraction of one) 0.01 0.01
Peak kilovoltage (fraction of one) 0.01 0.01
Anode angle (fraction of one) 0.01 0.01
Mass energy transfer coefficients of air (fraction of one) 0.01 0.01
The next python script shows how to compute the first and second half-value layers for aluminium and copper, the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient for the previous input file in CSV format.
from uspekpy import batch_simulation
# Define the path to the input CSV file
my_csv = 'data/input.csv'
# Call the batch_simulation function with the defined input CSV file
df = batch_simulation(input_file_path=my_csv)
# Define the path of the output file where the simulation results will be saved
my_output_csv = 'output/output.csv'
# Save results to a CSV file
df.to_csv(my_output_csv, index=True)
# Print results
print(df.to_string())
The next python script shows how to compute the first and second half-value layers for aluminium and copper, the mean energy, the air kerma and the mean air kerma-to-dose-equivalent conversion coefficient for the previous input file in Excel format.
from uspekpy import batch_simulation
# Define the path to the input Excel file
my_excel = 'data/input.xlsx'
# Define the name of the sheet in the input Excel file
my_sheet = 'input'
# Call the batch_simulation function with the defined input Excel file and sheet
df = batch_simulation(input_file_path=my_excel, sheet_name=my_sheet)
# Define the path of the output file where the simulation results will be saved
my_output_csv = 'output/output.csv'
# Save results to a CSV file
df.to_csv(my_output_csv, index=True)
# Print results
print(df.to_string())
In both cases, the script output is a table in which the simulation results for each case are concatenated to the input table. Simulation results includes the computed mean values and standard uncertainties (k=1) for the radiation protection quantities of each simulated x-ray spectrum. The units are mm for the half-value layers, keV for the mean energy, Gy for the air kerma and Sv/Gy for the mean air kerma-to-dose-equivalent conversion coefficient.
Case1 Case2
General NaN NaN
Quality N-60 N-60
Operational quantity H*(10) H*(10)
Irradiation angle (deg) 0 0
Number of simulations 3 3
Values NaN NaN
Al filter width (mm) 4 4
Cu filter width (mm) 0.6 0.6
Sn filter width (mm) 0 0
Pb filter width (mm) 0 0
Be filter width (mm) 0 0
Air gap width (mm) 1000 1000
Peak kilovoltage (kV) 60 60
Anode angle (deg) 20 20
Mass energy transfer coefficients of air file (keV and cm²/g) data/mu_tr_rho.csv data/mu_tr_rho.csv
Mono-energetic K to H conversion coefficients file (keV and Sv/Gy) data/h_k_h_amb_10.csv data/h_k_h_amb_10.csv
Relative uncertainties (k=1) NaN NaN
Al filter width (fraction of one) 0.01 0.01
Cu filter width (fraction of one) 0.01 0.01
Sn filter width (fraction of one) 0 0
Pb filter width (fraction of one) 0 0
Be filter width (fraction of one) 0 0
Air gap width (fraction of one) 0.01 0.01
Peak kilovoltage (fraction of one) 0.01 0.01
Anode angle (fraction of one) 0.01 0.01
Mass energy transfer coefficients of air (fraction of one) 0.01 0.01
Results None None
HVL1 Al Mean (mm) 5.895819 5.931133
HVL1 Al Standard deviation (mm) 0.020477 0.022359
HVL1 Al Relative uncertainty (fraction of one) 0.003473 0.00377
HVL2 Al Mean (mm) 6.238907 6.275384
HVL2 Al Standard deviation (mm) 0.017694 0.024303
HVL2 Al Relative uncertainty (fraction of one) 0.002836 0.003873
HVL1 Cu Mean (mm) 0.234631 0.236732
HVL1 Cu Standard deviation (mm) 0.00116 0.001351
HVL1 Cu Relative uncertainty (fraction of one) 0.004946 0.005706
HVL2 Cu Mean (mm) 0.262671 0.265111
HVL2 Cu Standard deviation (mm) 0.001065 0.001673
HVL2 Cu Relative uncertainty (fraction of one) 0.004053 0.00631
Mean energy Mean (keV) 47.815274 47.968429
Mean energy Standard deviation (keV) 0.067034 0.104718
Mean energy Relative uncertainty (fraction of one) 0.001402 0.002183
Air kerma Mean (uGy) 1.609083 1.622638
Air kerma Standard deviation (uGy) 0.039089 0.029723
Air kerma Relative uncertainty (fraction of one) 0.024293 0.018318
Mean conv. coeff. Mean (Sv/Gy) 1.589867 1.592054
Mean conv. coeff. Standard deviation (Sv/Gy) 0.001307 0.001274
Mean conv. coeff. Relative uncertainty (fraction of one) 0.000822 0.0008
Data files
For these scripts to work you need to have several data files. The content of these files for the previous examples are show below.
CSV file with the mass energy transfer coefficients of air in terms of the energy (mu_tr_rho.csv):
E (keV),mu_tr/rho (cm^2/g)
1.000000,3487.700000000000000
1.172600,2271.660000000000000
1.250000,1907.850000000000000
1.400000,1396.250000000000000
1.500000,1152.410000000000000
1.750000,746.850000000000000
2.000000,510.495000000000000
2.500000,267.712000000000000
3.000000,156.677000000000000
3.206300,128.597000000000000
3.206301,139.322000000000000
3.223910,139.220000000000000
3.250510,136.749000000000000
3.500000,110.244000000000000
3.618810,99.946700000000000
4.000000,74.386300000000000
5.000000,38.316500000000000
6.000000,22.138700000000000
7.000000,13.863800000000000
8.000000,9.209547628642890
9.000000,6.407464852253970
10.000000,4.626920149961950
12.500000,2.307431530377440
14.000000,1.615050752537630
15.000000,1.301309790375540
17.500000,0.801145676760343
20.000000,0.525990443101652
25.000000,0.262079759969996
28.663300,0.172139443801020
30.000000,0.150643910752649
35.000000,0.096166283094939
40.000000,0.067006659158694
50.000000,0.040350724533314
60.000000,0.030060380204255
70.000000,0.025736225862943
80.000000,0.023919178948042
90.000000,0.023273564441493
100.000000,0.023169137685326
125.000000,0.023905175732908
140.000000,0.024501233602389
150.000000,0.024926643691358
175.000000,0.025877217107796
187.083000,0.026274062287156
200.000000,0.026655131026205
250.000000,0.027882238669658
300.000000,0.028683812435718
324.037000,0.028972447929017
350.000000,0.029148771809045
386.867000,0.029415131704691
400.000000,0.029490249846129
474.342000,0.029698178702551
500.000000,0.029685041261757
574.456000,0.029603764611649
600.000000,0.029549718949812
673.537000,0.029405101930449
700.000000,0.029197657857256
800.000000,0.028890614121642
900.000000,0.028390536220701
1000.000000,0.027936798166738
1250.000000,0.026719405747041
1500.000000,0.025621217869820
1558.930000,0.025359438553807
1750.000000,0.024631087150390
1870.830000,0.024240842040503
2000.000000,0.023753744772526
2345.210000,0.022671649894621
2500.000000,0.022309768351513
3000.000000,0.021132688079239
3240.370000,0.020639133403572
3500.000000,0.020121558259145
4000.000000,0.019347638398287
4500.000000,0.018700741656237
5000.000000,0.018185053120065
6000.000000,0.017326066208925
6480.740000,0.016966042150857
7000.000000,0.016690444038446
8000.000000,0.016199645451199
9000.000000,0.015809252632524
CSV file with the monoenergetic air kerma-to-dose-equivalent conversion coefficients for H*(10) (h_k_h_amb_10.csv):
E (keV),h_k(0 deg) (Sv/Gy)
7,0.000012
8,0.000095
9,0.00145
10,0.008
11,0.0331
12,0.0737
13,0.127
14,0.19
15,0.26
16,0.326
17,0.395
18,0.466
19,0.538
20,0.61
30,1.1
40,1.47
50,1.67
60,1.74
80,1.72
100,1.65
150,1.49
200,1.4
300,1.31
400,1.26
500,1.23
600,1.21
800,1.19
1000,1.17
1500,1.15
2000,1.13
3000,1.12
4000,1.11
5000,1.19
6000,1.09
8000,1.08
10000,1.06
Please note that there must be no zeros or empy-valued energy gaps in these files, since it will lead to errors in the interpolation to the energy values of the x-ray spectrum.
Future developments
In future versions of USpekPy we would like to make the following enhancements:
- Include the uncertainty contribution of the monoenergetic air kerma-to-dose-equivalent conversion coefficients.
- Manage zeros or empy-valued energy gaps in data files for mass energy transfer coefficients and monoenergetic air kerma-to-dose-equivalent conversion coefficients.
- Expand the documentation of the package.
If you have any other suggestions please let us know (please check the Contributing to USpekPy section).
How to get support?
If you need support, please check the USpekPy documentation at GitHub (README).
If you need further support, please send an e-mail to Paz Avilés or to Xandra Campo.
Documentation
The official documentation of USpekPy is hosted on GitHub. Check its README file for a quick start guide.
Contributors
USpekPy is developed and maintained by Paz Avilés and Xandra Campo. It is one of the projects of the Ionizing Radiation Metrology Laboratory (LMRI), which is the Spanish National Metrology Institute for ionizing radiation.
License
USpekPy is distributed under the GNU GPLv3 License.
Contributing to USpekPy
All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. Please check the USpekPy issues page if you want to contribute.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
