fileio

The fileio module contains functions to create inventory instances by reading nuclide quantities from a file.

The docstring code examples assume that radioactivedecay has been imported as rd:

>>> import radioactivedecay as rd
radioactivedecay.fileio.read_csv(filepath: str | Path, inventory_type: str = 'Inventory', units: str | None = None, decay_data: DecayData | None = None, delimiter: str = ',', skip_rows: int = 0, encoding: str = 'utf-8') → Inventory | InventoryHP

Create an inventory by reading from a CSV file.

The CSV file must contain at least two columns. The first column must contain nuclide strings / canonical ids. The second column must contain the quantities of each nuclide.

Optionally a third column may be included specifying the units of each nuclide’s quantity. If a unit is present on a row, it overrides the units set in the function parameter (i.e. units is ignored for that row).

A header row is not required. If the CSV file contains a header, you should ignore it using the skip_rows parameter.

Example valid CSV file (no units - ‘Bq’ will be inferred by inventory constructor default):

H-3,1.0
C-14,2.0

Example with tab separators (TSV format) and units specified:

H-3 3.0 Bq
He-3    17.0   mol
C-14    5.0 Ci
Parameters:

  • filepath (str or pathlib.Path) – Name or path of the file to read in.

  • inventory_type (str, optional) – The type of inventory you want to create. Either ‘Inventory’ (default) for a normal precision (SciPy) inventory, or ‘InventoryHP’ for a high precision (SymPy) inventory.

  • units (None or str, optional) – The units of all the nuclide quantities in the file. If a unit is specified on a row of the file in the third column, that unit will override this one. If units = None is specified (default) and there is no unit on the row, the default of the inventory constructor will be used (currently ‘Bq’).

  • decay_data (None or DecayData, optional) – The decay dataset to create the inventory with. If None is specified (default), the default of the inventory constructor will be used (which currently is the ICRP-107 dataset).

  • delimiter (str, optional) – The delimiter used to separate items in the file. Default is comma (‘,’, CSV format). Ex. if delimiter = '  ' (tab) will attempt to read a TSV file.

  • skip_rows (int, optional) – Number of rows to ignore at the start of the file. Default is 0. Use this parameter to ignore a header row if the file has one (e.g. nuclide,quantity,unit).

  • encoding (str, optional) – Encoding of the file. Default is ‘utf-8’.

Raises:

ValueError – If the file or function parameters are invalid in some way: e.g. i) if a row does not contain 2 (nuclide string/canonical id & quantity) or 3 values (if including unit), or ii) skip_rows means end of file is reached, or iii) invalid inventory_type specified.