famewoks package#

Subpackages#

famewoks.tests package

Submodules#

famewoks.bliss2larch module#

Data Reduction Workflow from BLISS to Larch.

Currently applied to BLISS data collected at ESRF/BM16 beamline

famewoks.bliss2larch.render_tree(level: int, message: str) → str[source]#

famewoks.bliss2larch.safe_pre_edge(session: ExpSession, group: Group, verbose: bool = True) → Group[source]#: Apply pre_edge to a group, safely catching errors and checking for correct E0.

famewoks.bliss2larch.search_samples(session: ExpSession, verbose: bool = True, ignore_names: list[str] = ['rack', 'mount', 'align', 'bl_', 'sample', 'holder'])[source]#

Search for sample names in the {session.datadir}/{session.raw_data_name} directory.

Parameters:

session (ExpSession) – The experimental session containing metadata and directory information. see the documentation famewoks.datamodel.ExpSession.
verbose (bool, optional [True]) – If True, logs detailed information about the found samples (default is True).
ignore_names (List[str], optional) –
Ignores files with names containing a list of strings. Default is:
- ’rack’
- ’mount’
- ’align’
- ’bl_’,
- ’.h5’. (always is ignored, to avoid top level HDF5 files)

Returns:

A list of ExpSample objects representing the found samples.

Return type:

list of ExpSample

Notes

Searches for files in the {session.datadir}/{session.raw_data_name} directory.
Found samples are sorted by their creation time.
Updates the session.samples attribute with the found samples.
If session.bad_samples is not None, it applies famewoks.bliss2larch.set_bad_samples() filter bad samples.

famewoks.bliss2larch.show_samples_info(session: ExpSession, all: bool = False, show_datasets: bool = False)[source]#

Show the list of samples in a given session.

Parameters:

session (ExpSession) – The session containing the samples to display information about.
all (bool, optional [False]) – If True, displays information about all samples in the session. If False, only displays information about samples with a flag of 1

Return type:

None

famewoks.bliss2larch.show_datasets_info(sample: ExpSample, verbose: bool = True)[source]#: Show datasets info.

famewoks.bliss2larch.search_datasets(session: ExpSession, sample: int | str | None = None, verbose: bool = True) → list[ExpDataset] | ExpSession | None[source]#

Search for HDF5 files and energy scans, grouped by datasets.

Parameters:

session (ExpSession) – Experimental session with metadata -> famewoks.datamodel.ExpSession.
sample (Union[int, str, None], optional) – The specific sample to search for datasets. If None, searches all samples in the session. Can be an index (int) or a sample name (str) (default is None).
verbose (bool, optional) – If True, logs detailed information about the found datasets (default is True).

Returns:

If a specific sample is searched, returns a list of ExpDataset objects representing the found datasets. If all samples are searched, returns the updated ExpSession.

Return type:

Union[List[ExpDataset], ExpSession]

Notes

The function searches for HDF5 files within the {session.datadir}/{session.raw_data_name}/{sample_name}/**/*.h5 directory.
It identifies scans containing session.search_scanno (e.g. .1) in their scan number and session.search_scantitle (e.g. ‘trigscan’) in their title.
Updates the session.samples attribute with the found datasets.
Detailed information about the found datasets is logged if verbose is True.
If no samples are found in the session, it logs an error and returns without making changes.

famewoks.bliss2larch.get_scans(dataset: ExpDataset, verbose: bool = False, ignore_flag: bool = False) → list[list[int | str | XasScanGroup]][source]#

Get a list of enabled scans from a dataset.

Parameters:

dataset (ExpDataset) – dataset
verbose (bool) – show selected scans infos

Returns:

outscans – [ [index, ScanXASGroup, title] ]

Return type:

list of list

famewoks.bliss2larch.get_scan(dataset: ExpDataset, scanint: int, ignore_flag: bool = False) → XasScanGroup[source]#

Get scan object from the scans in the given dataset.

Parameters:

dataset (ExpDataset) – The dataset containing the list of scans. see the documentation of famewoks.datamodel.ExpDataset.
scanint (int) – The integer identifier of the scan to retrieve.

Returns:

The XasScanGroup object corresponding to the provided scan integer identifier

Return type:

ExpScan

famewoks.bliss2larch.get_groups(scan: XasScanGroup, data: str) → list[Group][source]#

Get a list of enabled data groups from a scan.

Parameters:

scan (XasScanGroup) – scan object
data (str)

Returns:

outgroups

Return type:

list of Group

famewoks.bliss2larch.get_group(datain: ExpSession | ExpSample | ExpDataset, scanint: int, data: str, sample: ExpSample | int | str | None = None, dataset: ExpDataset | int | str | None = None) → Group[source]#: Get a data group from dataset and scan number.

Load data from disk into the data model (=memory).

Parameters:

session – the session object famewoks.models.ExpSession
sample – sample identification, int (=index), str (=sample name) or famewoks.models.ExpSample
dataset – dataset identification, int (=index), str (=dataset name) or famewoks.models.ExpDataset
use_fluo_corr (bool [False]) – when True, use the dead-time corrected fluorescence channels otherwise the uncorrected roi is used
filter_spikes (bool [False]) – if True, remove spikes via median filter (with default parameters)
skip_scans (List[int], str or None) – the scans to exclude. if a string is given is parsed by _str2rng()
iskip (int [None]) – skip first iskip points
istrip (int [None]) – strip last istrip points
calc_eshift (bool [False]) – to calculate the energy shift

Return type:

None

famewoks.bliss2larch.get_eshift(scan: Group, scan_ref: Group, emin: float = -15, emax: float = 35, **kws: dict[str, Any])[source]#: Get the energy shift between two Groups

famewoks.bliss2larch.apply_eshift(dset: ExpDataset, data: str)[source]#

famewoks.bliss2larch.set_bad_samples(session: ExpSession, samples: str | int | list[int | str] | None)[source]#: Set bad samples.

famewoks.bliss2larch.set_bad_scans(session: ExpSession, sample: int | str | ExpSample, dataset: int | str | ExpDataset, scans: str | int | list[int] | None)[source]#: Set flag=0 to bad scans -> not included in merge.

Set bad fluo channels.

Parameters:

session – ExpSession object
dataset – int, str or ExpDataset object
sample – int, str or ExpSession object
channels – str (parsed by str2rng) or list of int if None: all channels are enabled back!
scan – int, or list of ints, if None: set for all scans in the current dataset

famewoks.bliss2larch.sum_fluo_channels(dataset: ExpDataset, scan: XasScanGroup)[source]#

Merge fluorescence channels for a given scan.

Parameters:: scan (Scan) – The scan object containing the fluorescence channels to be merged. The Scan object should have a fluo attribute (list of data groups) and fluos attribute (list of fluorescence channels), each with a flag attribute indicating if the channel should be processed.

Notes

Only fluorescence channels with the flag attribute set to True are processed.
The filename of the merged data group is updated to reflect the number of channels summed.
The function applies a pre-edge correction to the merged data group.

famewoks.bliss2larch.merge_data(dset: ExpDataset)[source]#

Merge scans in ExpDataset for datas (“fluo”, “ref”, “trans”).

This function merges data from the scans of an ExpDataset object based on the specified method. It processes the fluorescence (‘fluo’), reference (‘ref’), and transmission (‘trans’) data from the scans, merges the data groups, and applies pre-edge correction and rebins the dataset.

Parameters:

dset (ExpDataset) – The dataset containing scans to be merged. see the documentation of famewoks.datamodel.ExpDataset.
method (str, optional) – The method to use for merging data. Currently, only “sum” is supported. (default is “sum”)

Notes

Only scans with the flag attribute set to True are processed.
The function applies a pre-edge correction to the merged data group before saving it back to the dataset.
The merged data group’s filename is updated to reflect the number of scans merged.
The function logs the name of the merged data group and rebins the dataset after merging.

famewoks.bliss2larch.rebin_data(dset: ExpDataset, rebin_pars: dict[str, Any] | None = None)[source]#

Rebin merged data groups in an ExpDataset object.

This function rebins the fluorescence (‘fluo’), reference (‘ref’), and transmission (‘trans’) data groups in the dataset after they have been merged. It applies rebinning and pre-edge correction to the rebinned data groups.

Parameters:: dset (ExpDataset) – The dataset containing the merged data groups to be rebinned. The ExpDataset object should have fluo, ref, and trans attributes which are the data groups to be rebinned.

Notes

This function assumes that the data groups have already been merged using the merge_data function.
If the data groups are not found in the dataset, an error is logged indicating that merge_data should be run first.
The function logs any errors encountered during the rebinning process.

famewoks.bliss2larch.rebin_group(grp: Group, **kws: dict[str, Any])[source]#

Rebin a single Larch group.

Parameters:

grp (Group) – The group to be rebinned
kws (dict) – Keyword arguments to be passed to the rebin_xafs() function
function* (*Default parameters for Larch rebin_xafs())
pre1 (-)
pre2 (-)
pre_step (-)
exafs1 (-)
exafs2 (-)
xanes_step (-)
method (-)

famewoks.bliss2larch.save_data(dset: ExpDataset, data: list[str] | str = 'all', datadir: str | None = None, save_rebinned: bool = False, suffix: str | None = None)[source]#

Save all data to an Athena project file.

Parameters:

dset (ExpDataset) – The famewoks.datamodel.ExpDataset object containing the data to be saved.
data (list of str or str, optional (default: 'all')) – list of the data channel to be saved within [“fluo”, “trans”, “ref”]
datadir (str or None, optional) – The directory where the data will be saved. If None, defaults to “/tmp”.
save_rebinned (bool, optional) – Whether to save rebinned data. Defaults to False.
suffix (str or None, optional) – Add an additional string to the output filename.

Notes

This function saves all data from the provided ExpDataset object to an Athena project file. It creates a directory named ‘{session.processed_data_name} within the specified {session.datadir}, if it does not already exist, and saves the project file with a filename based on the dataset name and current timestamp. If save_rebinned is True, rebinned data will be saved with “_rebin” appended to the filename.

famewoks.bliss2larch.get_scans_types(scans_emin: list[float], scans_emax: list[float], energy_window: float = 10) → list[tuple[float, float, list[int]]][source]#

Cluster scans based on their energy ranges.

Parameters:

scans_emin (list) – A list of minimum energy values for each scan.
scans_emax (list) – A list of maximum energy values for each scan.
energy_window (int, optional) – The energy window used for clustering (default is 10).

Returns:

list of scan types with the following format: (emin, emax, [iscans]) where iscans is a list of scan indices

Return type:

list

famewoks.bliss2larch.set_enealign(session: ExpSession, gref: Group, data: str = 'ref')[source]#

Set the energy alignment reference group.

Parameters:

(ExpSession) (session)
(Group) (gref)
(str (data)
optional) (The type of data used for energy calibration. Defaults to "ref".)

Return type:

None (sets session.enealign and .pars_energy_align attribute)

famewoks.bliss2larch.set_eshift(dset: ExpDataset, scan: int, eshift: float)[source]#

famewoks.datamodel module#

famewoks.plots module#

Collection of custom plots.

famewoks.plots.plot_data(dset: ExpDataset, data: str | None = 'fluos', ynorm: str | None = None, show_i0: bool = False, show_e0: bool = False, show_deriv: bool = False, show_slide: bool = True, show_merge: bool | str = False)[source]#

Plot all scans in a dataset with or without a slider.

Parameters:

dset (ExpDataset) – The dataset containing the scans to be plotted. see the documentation of famewoks.datamodel.ExpDataset.
data (str, optional) – The name of the data to visualize (default is “fluos”).
ynorm (str or None, optional) –

Normalization method for the y-axis data. Options are: None
View raw data.

flat
Apply flat normalization.

area
Normalize by area under the curve.
show_i0 (bool, optional) – If True, plot the i0 data (default is False).
show_e0 (bool, optional) – If True, plot the e0 data (default is False).
show_deriv (bool, optional) – If True, plot the derivative of the data (default is False).
show_slide (bool, optional) – If True, plot the data scan by scan with a slider (default is True).
show_merge (bool, optional) – If True, plot the merged data (default is False).
maxplots (int, optional) – Maximum number of plots to display (default is 1000).
skip_scans – list of the scans to skip

Returns:

fig – The Plotly figure object containing the plot.

Return type:

plotly.graph_objects.Figure

Notes

The function performs the following steps: - Checks if the data is in the available plot data names. - Uses a helper function get_y to apply the necessary transformations to the y data. - Iterates over the scans in the dataset, creating Plotly traces for each scan and applying the necessary visibility and annotations. - If show_merge is True, plots the merged data. - If show_i0 is True, plots the i0 data on a secondary y-axis. - If show_e0 is True, adds vertical lines for e0 values. - Adds a slider for navigating through scans if show_slide is True. Here’s a figure showing more details :

famewoks.plots.plot_eshift(session: ExpSession, dset: ExpDataset, array: str = 'dmude', show_e0: bool = True)[source]#

famewoks.plots.plot_monitoring(df: DataFrame, pltcnts: list[list[int, str, bool, float]], range_slider: bool = True)[source]#

Build an interactive figure with Plotly.

Parameters:

df (pandas.DataFrame) – data container
pltcnts (list of list) – counters settings for the plot [[flag, counter_name, is_y2, yscale]]
range_slider (boolean [True]) – show the range slider

famewoks.plots.plot_curves(dset: ExpDataset, scan: int | None = None, yoffset: int = 0, ynorm: str | None = None)[source]#: Plot curves.

famewoks.plots.plot_groups(dset, data='fluo')[source]#: Plot merged Larch groups.

famewoks.plots_wip module#

Module contents#

FAMEwoks: data processing workflows useful at X-ray spectroscopy beamlines.#

FAMEwoks is a collection of workflows, written in Python, to process X-ray absorption and emission spectroscopy data. It is designed to be used at (ESRF) synchrotron beamlines, but can also be used for any X-ray data.