Merge module¶

The merge module offers the following functions to pre-process and merge scans:

Function	Description
`calibrate()`	Calibrates the absorption threshold energy of a scan.
`align()`	Aligns a scan with respect to a reference.
`merge()`	Merge groups in a collection.

araucaria.xas.merge.calibrate(group, e0, update=True)[source]¶

Calibrates the absorption threshold energy of the reference scan.

Parameters

group (Group) – Group containing the spectrum to calibrate.
e0 (float) – Arbitrary value for the absorption threshold.
update (bool) – Indicates if the group should be updated following calibration. The default is True.

Return type

float

Returns

Energy difference between e0 and the initial energy threshold.

Raises

TypeError – If group is not a valid Group instance.
AttributeError – If attribute energy does not exist in group.
AttributeError – If attribute mu_ref does not exist in group.

Notes

Calibration is performed by offsetting the group.energy attribute in order to match the absorption threshold energy of group.mu_ref with the given e0 value.

If update=True the following attributes of group will be modified or created:

group.energy: modified by the e_offset value.
group.e_offset: difference between e0 and the initial| threshold energy.

If update=False the e_offset value will be returned but not stored in group.

Warning

If e_offset already exists in the provided group, the group.energy array will be reverted to its original values before performing calibration with the new e0 value.

See also

find_e0: Finds the absorption threshold value.

Example

>>> from araucaria.testdata import get_testpath
>>> from araucaria.io import read_dnd
>>> from araucaria.xas import calibrate
>>> fpath = get_testpath('dnd_testfile1.dat')
>>> group_mu = read_dnd(fpath, scan='mu')  # extracting mu and mu_ref scans
>>> e0       = 29200  # threshold energy for calibration
>>> e_offset = calibrate(group_mu, e0, update=False)  # energy offset
>>> print('%1.3f' % e_offset)
-3.249

araucaria.xas.merge.align(group, refgroup, offset=0.0, window=[- 50, 50], use_mu_ref=True, update=True)[source]¶

Aligns the scan of a data group with respect to a reference.

Parameters

group (Group) – Group containing the spectrum to align.
refgroup (Group) – Reference group for alignment.
offset (float) – Initial energy offset for alignment. The default is 0.
window (list) – Energy window with respect to e0 to perform the alignent. The detaulf is [-50, 50].
use_mu_ref (bool) – Indicates if the reference scan of each group should be used for alignment. The default is True.
update (bool) – Indicates if the group should be updated following alignment. The default is True.

Return type

float

Returns

Energy offset for the group after alignment.

Raises

TypeError – If either group or refgroup is not a valid Group instance.
AttributeError – If attribute energy does not exist in either group or refgroup.
AttributeError – If attribute mu_ref does not exist in either group or refgroup when use_mu_ref = True.

Notes

The energy alignment is performed by minimizing the squared residuals between the derivative scans of group and refgroup, considering an energy window computed with respect to the absorption threshold e0 of refgroup.

If use_mu_ref=True the group.mu_ref array will be aligned with respect to the refgroup.mu_ref array. This is the default behavior.

If use_mu_ref=False the scan attributes of group and refgroup will be used for alignment, as determined by the get_mode() method.

If update=True the following attributes of group will be modified or created:

group.energy: modified by the e_offset value.
group.e_offset: energy offset following the alignment.

If update=False the e_offset will be returned but not stored in group.

Important

The energy alignment performs a local optimization that depends on the initial offset parameter. Therefore a judicious selection of offset is required in order to obtain meaningful results.

Warning

If e_offset already exists in the provided group, the group.energy array will be reverted to its original values before performing alignment.

See also

find_e0: Finds the absorption threshold value.

Examples

>>> from numpy import allclose
>>> from araucaria import Group
>>> from araucaria.testdata import get_testpath
>>> from araucaria.io import read_dnd
>>> from araucaria.xas import align
>>> fpath = get_testpath('dnd_testfile1.dat')
>>> # extracting mu and mu_ref scans
>>> group_mu = read_dnd(fpath, scan='mu')
>>> # creating a reference group with an offset
>>> offset = 3.125
>>> ref = Group(**{'energy': group_mu.energy + offset,
...                'mu': group_mu.mu,
...                'mu_ref': group_mu.mu_ref})
>>> # aligning with respect to 'mu_ref'
>>> e_offset = align(group_mu, ref, update=False)
>>> allclose(offset, e_offset)
True

>>> # aligning with respect to 'mu'
>>> offset = 4.233
>>> ref = Group(**{'energy': group_mu.energy + offset,
...                'mu': group_mu.mu})
>>> e_offset = align(group_mu, ref, use_mu_ref=False, update=False)
>>> allclose(offset, e_offset)
True

araucaria.xas.merge.merge(collection, taglist=['all'], name='merge', only_mu_ref=False)[source]¶

Merge groups in a collection.

Parameters

collection (Collection) – Collection with the groups to be merged.
taglist (List[str]) – List with keys to filter groups to be merged based on their tags attributes in the Collection. The default is [‘all’].
name (str) – Name for the merged group. The default is ‘merge’.
only_mu_ref (bool) – Indicates if only the reference scans should be merged. The default is False.

Return type

Tuple[Report, Group]

Returns

report – Report for the merged scan.
group – Group containing the merged scan.

Raises

TypeError – If collection is not a valid Collection instance.
AttributeError – If collection has no tags attribute.
AttributeError – If attribute mu_ref does not exist in the selected groups.
ValueError – If any item in taglist is not a key of the tags attribute.

Warning

If only one group in collection is selected for merge, a None report and the single group will be returned.

If different scan types are being merged, the scan attribute of the merge group will be labeled mu.

Notes

If only_mu_ref=False the scan arrays of the selected groups will be merged, as determined by the get_mode() method. The mu_ref arrays of the selected groups will also be merged separately. This is the detault behavior.

If only_mu_ref=True only the mu_ref arrays of the selected groups will be merged.

The following attribute will be created for the returned group:

group.merged_scans: list with the merged scan files.