evefile.entities.file module

Entities representing an eveH5 file on the entire file level.

While the entities in this module represent the contents of an eveH5 file, they clearly abstract from the internal structure of these files. Furthermore, there are different versions of the underlying schema (i.e., organisation) of these files, and the entities abstract away from these differences as well. The key concept is to provide users of the evefile interface with useful abstractions allowing to conveniently access all the data present in an eveH5 file.

Overview

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

../../_images/evefile.entities.file.svg — Fig. 12 Class hierarchy of the `evefile.entities.file` module. The `File` class is sort of the central interface to the entire subpackage, as this class provides a faithful representation of all information available from a given eveH5 file. To this end, it incorporates instances of classes of the other modules of the subpackage. Furthermore, “Scan” inherits from the identically named facade of the scan functional layer and contains the full information of the SCML file (if the SCML file is present in the eveH5 file).

Module documentation

class evefile.entities.file.File

Bases: object

Representation of all information available from a given 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.

metadata

File metadata

Type:: Metadata

log_messages

Log messages from an individual measurement

Each item in the list is an instance of LogMessage.

Type:: list

data

Data recorded from the devices involved in the scan.

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

Type:: dict

snapshots

Device data recorded as snapshot during a measurement.

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

Type:: dict

monitors

Device data monitored during a measurement.

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

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

Examples

The File class is not meant to be used directly, as any entities, but rather indirectly by means of the respective facades in the boundaries technical layer of the evefile package. Hence, for the time being, there are no dedicated examples how to use this class. Of course, you can instantiate an object as usual.

class evefile.entities.file.Metadata

Bases: object

Metadata of a given eveH5 file.

As measurements result in individual files, there is a series of crucial metadata of such a measurement on this global level.

filename

Name (full path) of the eveH5 file.

Type:: str

eveh5_version

Version of the eveH5 schema.

Type:: str

eve_version

Version of the eve engine used to record the data.

Type:: str

xml_version

Version of the schema used for the scan description (SCML/XML)

Type:: str

measurement_station

Name of the measurement station used to record the data.

Type:: str

start

Timestamp of the start of the measurement

Type:: datetime.datetime

end

Timestamp of the end of the measurement

Type:: datetime.datetime

description

User-entered description of the entire scan.

Type:: str

simulation

Flag signalling whether the measurement was a simulation.

Default: False

Type:: bool

preferred_axis

Name of the axis marked as preferred in the scan description.

Default: “”

Type:: string

preferred_channel

Name of the channel marked as preferred in the scan description.

Default: “”

Type:: string

preferred_normalisation_channel

Name of the channel marked as preferred for normalising.

Default: “”

Type:: string

Examples

The Metadata class is not meant to be used directly, as any entities, but rather indirectly by means of the respective facades in the boundaries technical layer of the evefile package. Hence, for the time being, there are no dedicated examples how to use this class. Of course, you can instantiate an object as usual.

Nevertheless, as you may use the class indirectly, one important feature should be highlighted here: the string representation used if you just apply print() to an object of the class:

print(Metadata())

The output of an (empty) object would look as follows:

                       filename:
                  eveh5_version:
                    eve_version:
                    xml_version:
            measurement_station:
                          start: 2025-08-07 10:57:16.849298
                            end: 2025-08-07 10:57:16.849307
                    description:
                     simulation: False
                 preferred_axis:
              preferred_channel:
preferred_normalisation_channel:

This can be used to get a convenient overview of the metadata contained in a loaded eveH5 file.

class evefile.entities.file.LogMessage

Bases: object

Log message from an individual measurement.

Operators can enter log messages during a measurement using the eve-gui. In such case, the respective message appears in the eveH5 file together with a timestamp.

timestamp

Timestamp of the log message

Type:: datetime.datetime

message

Actual content of the log message.

Type:: str

Examples

The Scan class is not meant to be used directly, as any entities, but rather indirectly by means of the respective facades in the boundaries technical layer of the evefile package. Hence, for the time being, there are no dedicated examples how to use this class. Of course, you can instantiate an object as usual.

from_string(string='')

Set attributes from string.

In eveH5 files up to v7, the log messages are single strings with the ISO timestamp at the beginning, followed by the actual message. Timestamp and message are separated by “: “.

This method separates both parts and converts the timestamp into an actual datetime.datetime object, consistent with the timestamp attribute.

Parameters:: string (str) – Log message consisting of timestamp and actual message.