IO read module¶

The io_read submodule offers functions to perform the following tasks:

Read XAFS files in common formats;
Read data from report files of Linear Combination Fitting (LCF) analysis.

Read XAFS files¶

The following functions are currently implemented to read XAFS files:

Function	Description
`read_p65()`	Reads a XAFS file from the P65 beamline (PETRA III).
`read_dnd()`	Reads a XAFS file fom the DND-CAT beamline (APS).
`read_xmu()`	Reads a XAFS file based on specified columns.
`read_file()`	Utility function to read a XAFS file based on specified columns.
`read_rawfile()`	Utility function to read a XAFS file based on specified count columns.

By convention these read functions will return a group class with the following attributes:

group.energy: the energy array.
group.mu: the transmission mu(E) array. Returned if scan='mu'.
group.fluo : the fluorescence mu(E) array. Returned if scan='fluo'.
group.mu_ref: the transmission reference array. Returned if ref=True.

The attribute mu_ref is also returned by default when scan is either ‘mu’ or ‘fluo’.

Choose scan = None and ref=True to return only the transmission reference.

Tip

The group returned by any read method will contain either a mu or a fluo ìnstance, but not both. If both instances are required, create an additional group by calling the read method with a different scan value.

Read LCF files¶

The following functions can be used to extract batch information from linear combination fit (LCF) report files:

Function	Description
`read_lcf_coefs()`	Returns amplitude coefficients for a given reference.
`read_lcf_chisqr()`	Returns chi-square statistics.

Important

The previous functions expect valid LCF report files generated by write_lcf_report().

araucaria.io.io_read.read_p65(fpath, scan='mu', ref=True, tol=0.0001)[source]¶

Reads a XAFS file from the P65 beamline.

P65 is located in the PETRA III storage ring (DESY, Hamburg, Germany).

Parameters

fpath (Path) – Path to file.
scan (str) – Requested mu(E). Accepted values are transmission (‘mu’), fluorescence (‘fluo’), or None. The default is ‘mu’.
ref (bool) – Indicates if the transmission reference (‘mu_ref’) should also be returned. The default is True.
tol (float) – Tolerance in energy units to remove duplicate values. The default is 1e-4,

Return type

Group

Returns

Group containing the requested arrays.

See also

read_file: Reads a XAFS file based on specified columns.

Examples

>>> from araucaria import Group
>>> from araucaria.io import read_xmu
>>> from araucaria.testdata import get_testpath
>>> from araucaria.utils import check_objattrs
>>> fpath = get_testpath('xmu_testfile.xmu')
>>> # extracting mu and mu_ref scans
>>> group_mu = read_xmu(fpath, scan='mu')
>>> check_objattrs(group_mu, Group, attrlist=['mu', 'mu_ref'])
[True, True]

>>> # extracting only fluo scan
>>> group_fluo = read_xmu(fpath, scan='fluo', ref=False)
>>> check_objattrs(group_fluo, Group, attrlist=['fluo'])
[True]

>>> # extracting only mu_ref scan
>>> group_ref = read_xmu(fpath, scan=None, ref=True)
>>> check_objattrs(group_ref, Group, attrlist=['mu_ref'])
[True]

araucaria.io.io_read.read_file(fpath, usecols, scan, ref, tol)[source]¶

Utility function to read a XAFS file based on specified columns.

Parameters

fpath (Union[Path, HTTPResponse]) – Path to file, or output from url open request.
usecols (tuple) – Tuple with column indexes to extract from the file.
scan (str) – Assigned mu(E), either transmission (‘mu’), fluorescence (‘fluo’), or None.
ref (bool) – Indicates if the transmission reference (‘mu_ref’) should also be returned.
tol (float) – Tolerance in energy units to remove duplicate values.

Return type

Group

Returns

Group containing the requested arrays.

Raises

IOError – If the file does not exist in the specified path.
ValueError – If no mu(E) or transmission reference are requested.
TypeError – If ref is not a valid boolean.

Notes

usecols should provide column indexes in the following order:

energy.
transmission/fluorescence mu(E).
transmission reference, if mu_ref=True.

If only mu_ref scan is requested , usecols should provide column indexes in the following order:

energy.
transmission reference.

Warning

The indexing order of usecols must be respected, or the assigned mu(E) will be incorrect.

araucaria.io.io_read.read_rawfile(fpath, usecols, scan, ref, tol)[source]¶

Utility function to read a XAFS file based on specified count columns.

Parameters

fpath (Union[Path, HTTPResponse]) – Path to file, or output from url open request.
usecols (tuple) – Tuple with columns indexes to extract from the file.
scan (str) – Computed mu(E), either transmission (‘mu’), fluorescence (‘fluo’), or None.
ref (bool) – Indicates if the transmission reference (‘mu_ref’) should also be returned.
tol (float) – Tolerance value to remove duplicate energy values.

Return type

Group

Returns

Group containing the requested arrays.

Raises

IOError – If the file does not exist in the specified path.
ValueError – If no mu(E) or transmission reference are requested.
TypeError – If ref is not a valid boolean.

Notes

usecols should provide column indexes in the following order:

energy.
monochromator intensity (I0).
transmitted intensity (IT1).
fluorescence intensity(IF), if scan='fluo'.
transmitted intensity (IT2), if mu_ref=True.

If mu_ref scan is not requested, usecols should provide column indexes in the following order:

energy
monochromator intensity (I0).
transmitted intensity (IT1)/fluorescence intensity(IF).

If only mu_ref scan is requested , usecols should provide column indexes in the following order:

energy.
transmitted intensity (IT1).
transmitted intensity (IT2).

Warning

The indexing order of usecols must be respected, or the computed mu(E) will be incorrect.

Important

If scan='fluo' and mu_ref is requested, all column indexes must be provided.

araucaria.io.io_read.read_lcf_coefs(fpaths, refgroup, error=True)[source]¶

Returns amplitude coefficients for a given LCF reference.

Amplitude coefficients are read directly from a list of paths to LCF report files generated by write_lcf_report().

Parameters

fpaths (List[Path]) – List of paths to valid LCF report files.
refgroup (str) – Name of the reference group.
error (bool) – If True the error of the fit will also be returned. The default is True.

Return type

Union[Tuple[List], list]

Returns

Amplitude coefficients and error for the reference in the LCF.

Raises

IOError – If a file does not exist in the specified path.
TypeError – If a file is not a valid LCF report.
ValueError – If refgroup was fitted during the LCF analysis (i.e. not a reference).

Examples

>>> from araucaria.testdata import get_testpath
>>> from araucaria.io import read_lcf_coefs
>>> fpath = get_testpath('test_lcf_report.log')
>>> read_lcf_coefs([fpath], 'group1')
([0.40034377], [0.01195335])
>>> read_lcf_coefs([fpath], 'group2', error=False)
[0.59428689]

araucaria.io.io_read.read_lcf_chisqr(fpaths, redchi=False)[source]¶

Returns chi square statistic for LCF reports.

Chi square values are read directly from a list of paths to LCF report files generated by write_lcf_report().

Parameters

fpaths (List[Path]) – List of paths to valid LCF report files.
redchi (bool) – Indicates if the reduced chi square statistic should be returned instead.

Return type

list

Returns

Chi square values. Reduced chi square values are optionally returned if redchi=True.

Raises

IOError – If a file does not exist in the specified path.
TypeError – If a file is not a valid LCF report.

Examples

>>> from araucaria.testdata import get_testpath
>>> from araucaria.io import read_lcf_chisqr
>>> fpath = get_testpath('test_lcf_report.log')
>>> read_lcf_chisqr([fpath])
[1.40551323]
>>> read_lcf_chisqr([fpath], redchi=True)
[0.01011161]