evefile.boundaries.evefile module

High-level Python object representation of eveH5 file contents.

This module provides a high-level representation of the contents of an eveH5 file. Being a high-level, user-facing object representation, technically speaking this module is a facade. The corresponding resource (persistence-layer-facing interface) would be the eveh5 module.

Overview 

A first overview of the classes implemented in this module and their hierarchy is given in the UML diagram below.

../../_images/evefile.boundaries.evefile.svg — Fig. 8 Class hierarchy of the `evefile.boundaries.evefile` module, providing the facade (user-facing interface) for an eveH5 file. Basically, it inherits from `evefile.entities.file.File` and adds behaviour. Most of this behaviour is contributed by the various modules of the `controllers` subpackage.

Key aspects 

While the evefile module is the high-level interface (facade) of the evefile package, it is still, from a functional viewpoint, close to the actual eveH5 files, providing a faithful representation of all information contained in an eveH5 file. Nevertheless, it is clearly an abstraction from the actual data files. Hence, the key characteristics of the module are:

Stable interface to eveH5 files, regardless of their version.
- Some features may only be available for newer eveH5 versions, though.
Powerful abstractions on the device level.
- Options to devices appear as attributes of the device objects, not as separate datasets.
Actual data are loaded on demand, not when loading the file.
- This does not apply to the metadata of the individual datasets. Those are read upon reading the file.
- Reading data on demand should save time and resources, particularly for larger files.
- Often, you are only interested in a subset of the available data.

Usage 

Loading the contents of a data file of a measurement may be as simple as:

evefile = EveFile(filename="my_measurement_file.h5")

If you are interested in a convenient overview of the contents of the eveH5 file just loaded, try this:

evefile.show_info()

This will output a human-readable summary of the file metadata, log messages, and a list of datasets in the data, snapshot, and monitor section. See the documentation of the EveFile.show_info() method for details.

Data are stored within a EveFile object with their IDs rather than the “given” names users are familiar with. Hence, to get an overview of all the data(sets) contained in a file, use the EveFile.get_data_names() method:

evefile.get_data_names()

This will return a list of “given” data names.

Similarly, if you know the “given” name of a dataset or a list of datasets, you can retrieve the corresponding Data objects by using the EveFile.get_data() method:

# Get list of datasets by name
evefile.get_data(["name1", "name2"])

# Get single dataset by name
evefile.get_data("name")

To get the data marked as preferred in the scan, use the EveFile.get_preferred_data() method:

evefile.get_preferred_data()

This will return a list with three elements, [preferred_axis, preferred_channel, preferred_normalisation_channel], where each of these elements is either of type evefile.entities.data.Data or None.

Internals: What happens when reading an eveH5 file?

Reading an eveH5 file is not as simple as reading contents of an HDF5 file and present its contents as Python object hierarchy. At least, if you would like to view, process, and analyse your data more conveniently, you should not stop here. The idea behind the evefile package, and in parts behind the EveFile class, is to provide you as consumer of the data with powerful abstractions and structured information. To this end, a series of steps are necessary:

Read the eveH5 file (actually, an HDF5 file).
Get the correct VersionMapper class.
Map the file contents to the proper data structures provided by the evefile package.

Module documentation 

class evefile.boundaries.evefile.EveFile(filename='', load=True)

Bases: File

High-level Python object representation of eveH5 file contents.

This class serves as facade to the entire evefile package and provides a rather high-level representation of the contents of an individual eveH5 file.

Individual measurements are saved in HDF5 files using a particular schema (eveH5). Besides file-level metadata, there are log messages and the actual data.

The data are organised in three functionally different sections: data, snapshots, and monitors. While the “data” section contains the data of motor axes moved and detector channels read out during the scan, the “snapshot” section contains values at distinct times (usually at the very beginning of a scan), usually of more devices than used in the scan. The “monitors” section contains data of all those devices monitored during the scan, meaning that only changes in values are recorded, together with their timestamp (rather than position count).

Values from axes contained in the “snapshot” section are used for data joining, while all other values can be regarded as either options of individual devices or telemetry data for the setup. All values from the “monitors” section are strictly telemetry data for the setup.

metadata

File metadata

Type:: evefile.entities.file.Metadata

log_messages

Log messages from an individual measurement

Each item in the list is an instance of evefile.entities.file.LogMessage.

Type:: list

data

Data recorded from the devices involved in the scan.

The keys of the dictionary are the (guaranteed to be unique) HDF dataset names, not the “given” names usually familiar to the users. Use the get_data() method to retrieve data objects by their “given” name.

Each item is an instance of evefile.entities.data.Data.

Type:: dict

snapshots

Device data recorded as snapshot during a measurement.

Only those device data that are not options belonging to any of the devices in the data attribute are stored here.

The keys of the dictionary are the (guaranteed to be unique) HDF dataset names, not the “given” names usually familiar to the users.

Each item is an instance of evefile.entities.data.Data.

Type:: dict

monitors

Device data monitored during a measurement.

The keys of the dictionary are the (guaranteed to be unique) HDF dataset names, not the “given” names usually familiar to the users.

Each item is an instance of evefile.entities.data.MonitorData.

Type:: dict

position_timestamps

Timestamps for each individual position.

Monitors have timestamps (milliseconds since start of the scan) rather than positions as primary quantisation axis. This object provides a mapping between timestamps and positions and can be used to map monitor data to positions.

Type:: evefile.entities.data.TimestampData

Parameters:

filename (str) – Name of the file to be loaded.

Raises:

ValueError – Raised if no filename is provided.
FileNotFoundError – Raised if provided file could not be found.

Examples

Loading the contents of a data file of a measurement may be as simple as:

evefile = EveFile(filename="my_measurement_file.h5")

property filename

Name of the file to be loaded.

Returns:: filename – Name of the file to be loaded.
Return type:: str

get_data(name=None)

Retrieve data objects by name.

While generally, you can get the data objects by accessing the data attribute directly, there, they are stored using their HDF5 dataset name as key. Usually, however, data are accessed by their “given” name.

Parameters:

name (str | list) – Name or list of names of data to retrieve

Returns:

data – Data object(s) corresponding to the name(s).

In case of a list of data objects, each object is of type evefile.entities.data.Data.

Return type:

evefile.entities.data.Data | list

get_data_names()

Retrieve “given” names of data objects.

Data are stored in the data attribute using their HDF5 dataset name as key. Usually, however, data are accessed by their “given” name.

This method returns a list of all “given” names of the datasets stored in data.

Returns:: data – List of names of the data object(s) in data.
Return type:: list

get_preferred_data()

Retrieve data objects marked as preferred.

Within a scan, a preferred motor axis, a preferred detector channel, and a preferred channel for normalisation can be named explicitly. The preferred axis and channel are used for plotting within the eve GUI during measurement.

Note

The datasets returned are guaranteed to be commensurate and compatible and can hence directly be plotted against each other. This is due to the fact that preferred axis and channel currently must come from the same scan module of a scan.

Returns:

data – Data objects corresponding to the preference settings.

A list with three elements:

preferred axis
preferred channel
preferred normalisation channel

If the preference has been set in the scan description, the item in the list is of type evefile.entities.data.MeasureData, otherwise None.

Return type:

list

get_joined_data(data=None, mode='AxisOrChannelPositions')

Retrieve data objects with commensurate dimensions.

For details on joining see the joining module.

Parameters:

data (list) –
(Names/IDs of) data objects whose data should be joined.

You can provide either names or IDs or the actual data objects.

If no data are given, by default all data available will be joined.

Default: None
mode (str) –
Name of the join mode to be used. This must be a mode understood by the JoinFactory.

Default: “AxisOrChannelPositions”

Returns:

data – List of data objects.

Each item in the list is of type evefile.entities.data.MeasureData.

Return type:

list

get_dataframe(data=None, mode='AxisOrChannelPositions')

Retrieve Pandas DataFrame with given data objects as columns.

Internally, the get_joined_data() method will be called with the data provided. If the data parameter is omitted, all datasets will be used.

The names of the columns of the returned DataFrame are the names (not IDs) of the respective datasets.

Important

While working with a Pandas DataFrame may seem convenient, you’re loosing basically all the relevant metadata of the datasets. Hence, this method is rather a convenience method to be backwards-compatible to older interfaces, but it is explicitly not suggested for extensive use.

Parameters:

data (list) –
(Names/IDs of) data objects whose data should be joined.

You can provide either names or IDs or the actual data objects.

If no data are given, by default all data available will be joined.

Default: None
mode (str) –
Name of the join mode to be used. This must be a mode understood by the JoinFactory.

Default: “AxisOrChannelPositions”

Returns:

dataframe – Pandas DataFrame containing the given data objects as columns.

The names of the columns are the names (not IDs) of the respective datasets.

Return type:

pandas.DataFrame

show_info()

Print basic information regarding the contents of the loaded file.

Often, it is convenient to get a brief overview of the contents of a file after it has been loaded. The output of this method currently contains the following sections:

metadata
log messages
data
snapshots
monitors

The output could look similar to the following:

METADATA
                       filename: file.h5
                  eveh5_version: 7
                    eve_version: 2.0
                    xml_version: 9.2
            measurement_station: Unittest
                          start: 2024-06-03 12:01:32
                            end: 2024-06-03 12:01:37
                    description:
                     simulation: False
                 preferred_axis: SimMot:01
              preferred_channel: SimChan:01
preferred_normalisation_channel: SimChan:01

LOG MESSAGES
20250812T09:06:05: Lorem ipsum

DATA
foo (SimMot:01) <AxisData>
bar (SimChan:01) <SinglePointChannelData>

SNAPSHOTS
bar (SimChan:01) <AxisData>
bazfoo (SimChan:03) <AxisData>
foo (SimMot:01) <AxisData>

MONITORS

evefile.boundaries.evefile module

Overview

Key aspects

Usage

Internals: What happens when reading an eveH5 file?

Module documentation

Overview 

Key aspects 

Usage 

Module documentation 