evedata.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 evedata 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.

Fig. 39 Class hierarchy of the evedata.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 evedata.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, a scan description (originally an XML/SCML file), 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

scan

Description of the actual scan.

Type:

Scan

scan_modules

Modules the scan consists of.

Each item is an instance of ScanModule and contains the data recorded within the given scan module.

In case of no scan description present, a “dummy” scan module will be created containing all data.

Type:

dict

snapshots

Device data recorded as snapshot during a measurement.

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

Type:

dict

monitors

Device data monitored during a measurement.

Each item is an instance of evedata.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:

evedata.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 evedata.evefile subpackage. 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 evedata.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 evedata.evefile subpackage. 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 evedata.evefile.entities.file.Scan

Bases: Scan

Description of a scan used to record data.

Measurements are described and defined as scans using a special XML schema termed Scan Markup Language (SCML).

author

Author of a given scan description, as set in the SCML file.

Type:

str

filename

Name of the SCML file containing the scan description.

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 evedata.evefile subpackage. Hence, for the time being, there are no dedicated examples how to use this class. Of course, you can instantiate an object as usual.

extract(filename='')

Extract SCML from the user part of an eveH5 file.

Parameters:

filename (str) – Name of the file to load.

A short description of the way the scan description (SCML) is contained in eveH5 files:

• Generally, the SCML is located at the beginning of the file, therefore interpreted by HDF5 as “user data”.

• The first eight bytes of an eveH5 file containing the SCML read “EVEcSCML”.

• The next four bytes are the length of the compressed SCML file (encoded as big-endian unsigned integer, “!L”).

• The next four bytes are the length of the uncompressed SCML file (encoded as big-endian unsigned integer, “!L”) - an information that is not needed here.

• The next (length compressed SCML file) bytes are the ZIP-compressed contents of the actual SCML file.

• As a user data block in HDF5 files needs to be 2^n bytes long, the remaining space to the next power of 2 is padded with zeros.

load(filename='')

Load contents of an SCML file.

Parameters:

filename (str) – Name of the file to load.

class evedata.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 evedata.evefile subpackage. 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.

class evedata.evefile.entities.file.ScanModule

Bases: object

Representation of a scan module, containing the corresponding data.

Scans are organised in scan modules, and despite the flat organisation of the data files up to eveH5 v7, organising the data according to the scan modules they are recorded in is not only sensible, but sometimes necessary to properly deal with the data.

How does this class differ from evedata.scan.entities.scan.ScanModule having the same name? Both represent scan modules as building blocks of a scan/measurement, but serve different purposes on different abstraction layers. While evedata.scan.entities.scan.ScanModule represents the scan modules as defined in a scan (in an SCML file) quite closely, the present class provides the organisation layer for the representation of the actual data, be it in the EveFile or Measurement interfaces.

name

Given name of the scan module, as displayed in the eve GUI.

Type:

str

id

Unique (numeric) ID of the scan module.

Typically, when a scan gets created using the eve GUI, a unique ID will automatically be assigned to each individual scan module.

IDs are required to be unique.

Type:

int

parent

Unique ID of the parent scan module.

In case of the first scan module, this is 0.

Default: 0

Type:

id

appended

Unique ID of the appended scan module.

A scan module can have 0..1 appended and 0..1 nested scan modules.

Default: None

Type:

int

nested

Unique ID of the nested scan module.

A scan module can have 0..1 appended and 0..1 nested scan modules.

Default: None

Type:

int

data

Data recorded from the devices involved in the scan module.

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

Type:

dict

position_counts

Actual position counts created during the scan module.

These position counts cannot necessarily be inferred from the definition of the scan module itself, but sometimes only be obtained from the actual measurement.

Type:

numpy.array

Examples

The ScanModule 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 evedata.evefile subpackage. Hence, for the time being, there are no dedicated examples how to use this class. Of course, you can instantiate an object as usual.

property device_names

Name of the devices contained in data.

The keys used in data are the XML-IDs and names of the HDF5 datasets. However, usually each device has a more readable and pronounceable name that it is known by.

Note that device names are not guaranteed to be unique. For all devices in the data attribute, this should be the case, though.

Returns:

device_names – Names of the devices contained in data.

The keys are the readable and pronounceable names of the devices, the values are the corresponding XML-IDs.

Return type:

dict