Merge pull request #87 from ericpre/improve_docstring_elements_database

Mention source of `elements` database in docstring

doc/reference/material.rst

@@ -18,7 +18,9 @@
 .. autoattribute:: exspy.material.elements
  :annotation:
 
-Database of element properties. The following properties are included:
+Database of element properties.
+
+The following properties are included:
 
 .. code::
 
@@ -32,32 +34,50 @@ Database of element properties. The following properties are included:
  └── Physical_properties
  └── density_gcm3
 
-Examples:
+The X-ray lines energies are taken from Chantler et al. [1]_.
 
-.. code::
+The line weight, more precisely the approximate line weight for K, L, M
+shells are taken from the Electron Probe Quantification (EPQ) library [2]_.
+
+The field ``threshold`` and ``edge`` are taken from the Gatan EELS atlas
+https://eels.info/atlas, as retrieved in June 2020.
+
+Examples
+
+>>> exspy.material.elements.Fe.General_properties
+├── Z = 26
+├── atomic_weight = 55.845
+└── name = iron
+>>> exspy.material.elements.Fe.Physical_properties
+└── density (g/cm^3) = 7.874
+>>> exspy.material.elements.Fe.Atomic_properties.Xray_lines
+├── Ka
+│ ├── energy (keV) = 6.404
+│ └── weight = 1.0
+├── Kb
+│ ├── energy (keV) = 7.0568
+│ └── weight = 0.1272
+├── La
+│ ├── energy (keV) = 0.705
+│ └── weight = 1.0
+├── Lb3
+│ ├── energy (keV) = 0.792
+│ └── weight = 0.02448
+├── Ll
+│ ├── energy (keV) = 0.615
+│ └── weight = 0.3086
+└── Ln
+ ├── energy (keV) = 0.62799
+ └── weight = 0.12525
+
+
+References
+
+.. [1] Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R.,
+ Kotochigova, S.A., and Zucker, D.S. (2005), X-Ray Form Factor,
+ Attenuation and Scattering Tables (version 2.1).
+ https://dx.doi.org/10.18434/T4HS32
 
- >>> exspy.material.elements.Fe.General_properties
- ├── Z = 26
- ├── atomic_weight = 55.845
- └── name = iron
- >>> exspy.material.elements.Fe.Physical_properties
- └── density (g/cm^3) = 7.874
- >>> exspy.material.elements.Fe.Atomic_properties.Xray_lines
- ├── Ka
- │ ├── energy (keV) = 6.404
- │ └── weight = 1.0
- ├── Kb
- │ ├── energy (keV) = 7.0568
- │ └── weight = 0.1272
- ├── La
- │ ├── energy (keV) = 0.705
- │ └── weight = 1.0
- ├── Lb3
- │ ├── energy (keV) = 0.792
- │ └── weight = 0.02448
- ├── Ll
- │ ├── energy (keV) = 0.615
- │ └── weight = 0.3086
- └── Ln
- ├── energy (keV) = 0.62799
- └── weight = 0.12525
+.. [2] Ritchie, N. EPQ is the Electron Probe Quantification library
+ - the basis for DTSA-II.
+ https://github.com/usnistgov/EPQ

doc/user_guide/bibliography.rst

@@ -17,12 +17,9 @@ Bibliography
 .. _Chantler2005:
 
 :ref:`[Chantler2005] <Chantler2005>`
- C. Chantler, K. Olsen, R. Dragoset,
- J. Chang, A. Kishore, S. Kotochigova, and D. Zucker, "Detailed Tabulation
- of Atomic Form Factors, Photoelectric Absorption and Scattering Cross
- Section, and Mass Attenuation Coefficients for Z = 1-92 from E = 1-10 eV
- to E = 0.4-1.0 MeV" *NIST Standard Reference Data*
- [`<https://physics.nist.gov/ffast>`_].
+ Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
+ S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
+ Scattering Tables (version 2.1). https://dx.doi.org/10.18434/T4HS32.
 
 .. _Egerton2011:
 

exspy/_misc/elements.py

@@ -4996,6 +4996,14 @@
  └── Physical_properties
  └── density_gcm3
 
+The X-ray lines energies are taken from Chantler et al. [1]_.
+
+The line weight, more precisely the approximate line weight for K, L, M
+shells are taken from the Electron Probe Quantification (EPQ) library [2]_.
+
+The field ``threshold`` and ``edge`` are taken from the Gatan EELS atlas
+https://eels.info/atlas, as retrieved in June 2020.
+
 Examples
 --------
 >>> exspy.material.elements.Fe.General_properties
@@ -5023,6 +5031,18 @@
 └── Ln
  ├── energy (keV) = 0.62799
  └── weight = 0.12525
+
+ 
+References
+----------
+.. [1] Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R.,
+ Kotochigova, S.A., and Zucker, D.S. (2005), X-Ray Form Factor,
+ Attenuation and Scattering Tables (version 2.1).
+ https://dx.doi.org/10.18434/T4HS32
+
+.. [2] Ritchie, N. EPQ is the Electron Probe Quantification library
+ - the basis for DTSA-II.
+ https://github.com/usnistgov/EPQ
 """
 
 # read dictionary of atomic numbers from eXSpy, and add the elements that

exspy/_misc/material.py

@@ -314,7 +314,7 @@ def mass_absorption_coefficient(element, energies):
  Mass absorption coefficient (mu/rho) of a X-ray absorbed in a pure
  material.
 
- The mass absorption is retrieved from the database of Chantler2005
+ The mass absorption is retrieved from the database of Chantler et al. [*]_.
 
  Parameters
  ----------
@@ -339,12 +339,11 @@ def mass_absorption_coefficient(element, energies):
  --------
  exspy.material.mass_absorption_mixture
 
- Note
- ----
- See https://dx.doi.org/10.18434/T4HS32
- Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
- S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
- Scattering Tables (version 2.1).
+ References
+ ----------
+ .. [*] Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
+ S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
+ Scattering Tables (version 2.1). https://dx.doi.org/10.18434/T4HS32
  """
  energies_db = np.array(ffast_mac[element].energies_keV)
  macs = np.array(ffast_mac[element].mass_absorption_coefficient_cm2g)
@@ -372,7 +371,7 @@ def _mass_absorption_mixture(weight_percent, elements, energies):
  mixture of elements.
 
  The mass absorption coefficient is calculated as a weighted mean of the
- weight percent and is retrieved from the database of Chantler2005.
+ weight percent and is retrieved from the database of Chantler et al. [*]_.
 
  Parameters
  ----------
@@ -400,12 +399,11 @@ def _mass_absorption_mixture(weight_percent, elements, energies):
  --------
  exspy.material.mass_absorption
 
- Note
- ----
- See https://dx.doi.org/10.18434/T4HS32
- Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
- S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
- Scattering Tables (version 2.1).
+ References
+ ----------
+ .. [*] Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
+ S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
+ Scattering Tables (version 2.1). https://dx.doi.org/10.18434/T4HS32
  """
  if len(elements) != len(weight_percent):
  raise ValueError("Elements and weight_fraction should have the same length")
@@ -430,7 +428,7 @@ def mass_absorption_mixture(weight_percent, elements="auto", energies="auto"):
  mixture of elements.
 
  The mass absorption coefficient is calculated as a weighted mean of the
- weight percent and is retrieved from the database of Chantler2005.
+ weight percent and is retrieved from the database of Chantler et al. [*]_.
 
  Parameters
  ----------
@@ -461,13 +459,11 @@ def mass_absorption_mixture(weight_percent, elements="auto", energies="auto"):
  --------
  exspy.material.mass_absorption_coefficient
 
- Note
- ----
- See https://dx.doi.org/10.18434/T4HS32
- Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
- S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
- Scattering Tables (version 2.1).
-
+ References
+ ----------
+ .. [*] Chantler, C.T., Olsen, K., Dragoset, R.A., Kishore, A.R., Kotochigova,
+ S.A., and Zucker, D.S. (2005), X-Ray Form Factor, Attenuation and
+ Scattering Tables (version 2.1). https://dx.doi.org/10.18434/T4HS32
  """
  from hyperspy.signals import BaseSignal
 

upcoming_changes/87.enhancements.rst

@@ -0,0 +1 @@
+Mention source of :attr:`~exspy.material.elements` database in docstring