trepr.io module

General facilities for input (and output).

In order to work with tr-EPR data, these data need to be imported into the trepr package. Therefore, the module provides importers for specific file formats. In case of tr-EPR spectroscopy, the measurement control software is often lab-written and specific for a local setup. One exception is the Bruker BES3T file format written by Bruker Xepr and Xenon software that can be used to record tr-EPR data in combination with a pulsed EPR spectrometer.

Another class implemented in this module is the trepr.io.DatasetImporterFactory, a prerequisite for recipe-driven data analysis. This factory returns the correct dataset importer for a specific dataset depending on the information provided (usually, a filename).

Importers for specific file formats

Currently, the following importers for specific file formats are available:

  • SpeksimImporter

    The Speksim format was developed in Freiburg in the group of Prof. G. Kothe and used afterwards in the group of Prof. S. Weber. The spectrometer control software was developed by Prof. U. Heinen.

    One speciality of this file format is that each transient is stored in an individual file. For each of these transients, a timestamp as well as the microwave frequency are recorded as well, allowing to analyse frequency drifts and irregularities in the data acquisition.

  • TezImporter

    The tez file format is the internal format used by the MATLAB(r) trepr toolbox developed by T. Biskup. It vaguely resembles the OpenDocument format used, e.g., by OpenOffice and LibreOffice. In short, the metadata are contained in an XML file, while the numerical data are stored as IEEE 754 standard binaries in separate files. The ASpecD dataset format (adf) is similar in some respect.

    tez files usually carry “.tez” as file extension.

  • Fsc2Importer

    The fsc2 file format originates from the fsc2 spectrometer control software developed by J. T. Törring at the FU Berlin and used in a number of labs. For details of the software, see the fsc2 homepage. As the actual experiments are defined in the “Experiment Description Language” (EDL), the importer necessarily makes a number of assumptions that work with the particular set of data recorded at a given time at FU Berlin.

    fsc2 files usually carry “.dat” as file extension, although they are bare text files.

  • BES3TImporter

    The Bruker BES3T file format written by Bruker Xepr and Xenon software that can be used to record tr-EPR data in combination with a pulsed EPR spectrometer. This importer currently only supports a smaller subset of the specification, e.g. only data without additional axes data files and only real values.

Implementing importers for additional file formats is rather straight-forward. For details, see the documentation of the aspecd.io module.

Note to developers

As a convention, the first axis of a dataset is always the magnetic field axis, and only the second axis is the time axis. When implementing importers for additional file formats, it is important to follow this convention to provide a consistent experience throughout the trepr package.

Module documentation

class trepr.io.DatasetImporterFactory

Bases: aspecd.io.DatasetImporterFactory

Factory for creating importer objects based on the source provided.

Often, data are available in different formats, and deciding which importer is appropriate for a given format can be quite involved. To free other classes from having to contain the relevant code, a factory can be used.

Currently, the sole information provided to decide about the appropriate importer is the source (a string). A concrete importer object is returned by the method get_importer(). If no source is provided, an exception will be raised.

If the source string does not match any of the importers handled by this module, the standard importers from the ASpecD framework are checked. See the documentation of the aspecd.io.DatasetImporterFactory base class for details.

supported_formats

Dictionary who’s keys correspond to the base name of the respective importer (i.e., without the suffix “Importer”) and who’s values are a list of file extensions to detect the correct importer.

Type

dict

data_format

Name of the format that has been detected.

Type

str

class trepr.io.SpeksimImporter(source='')

Bases: aspecd.io.DatasetImporter

Importer for data in Freiburg Speksim format including its metadata.

Datasets in this format consist of several time traces, each of which is stored in a text file. In order to analyse the raw data, it is necessary to store the time traces all together in one dataset.

The corresponding metadata are read from an external file in infofile format. For further information about the infofile format see: https://www.till-biskup.de/en/software/info/format.

Parameters

source (str) – Path to the raw data.

dataset

Entity containing data and metadata.

Type

trepr.dataset.ExperimentalDataset

class trepr.io.TezImporter(source='')

Bases: aspecd.io.DatasetImporter

Importer for MATLAB(r) trepr toolbox format.

The MATLAB(r) trepr toolbox format is basically a ZIP archive consisting of a list of standard IEEE 754 binary files containing the data and an XML file containing the accompanying metadata in structured form, enriched with information necessary to directly convert them back into MATLAB structures (corresponding to a Python dict).

Parameters

source (str) – Path to the raw data.

dataset

Entity containing data and metadata.

Type

trepr.dataset.ExperimentalDataset

load_infofile

Whether to load metadata from info file.

If no info file is found, import will proceed nevertheless.

Default: True

Type

bool

class trepr.io.Fsc2Importer(source='')

Bases: aspecd.io.DatasetImporter

Importer for data in Berlin fsc2 format.

These data have been recorded using the flexible fsc2 spectrometer control software written by J. T. Törring, allowing to define user-specific experiments. For details, see the fsc2 homepage. As the actual experiments are defined in the “Experiment Description Language” (EDL), the importer necessarily makes a number of assumptions that work with the particular set of data recorded at a given time at FU Berlin.

Key aspects of the data format are:

  • The data files are bare text files (ASCII)

  • The entire EDL program defining the experiment is contained in a header

  • The header usually starts with %

  • The data are stored as ASCII numbers in one (very) long column.

  • At the bottom of the header is a series of key-value pairs with crucial metadata necessary to reshape the data and assign the axes.

The following strategy has been applied to reading the data:

  • Read the header first, separately storing the key-value pairs at the end.

  • Read the data using numpy.loadtxt().

  • Reshape the data according to the parameters read from the header.

Only those parameters that can definitely be obtained from the header are stored within the metadata of the dataset. Note that using this format by the authors predates the development of the info file format, hence many parameters can only implicitly be guessed, as most of the time no corresponding record of metadata exists.

Note

While it may seem strange to store the data as one long column, this is actually a very robust way of storing data, as each individual trace gets written to the file immediately after obtaining the data from the transient recorder. Thus, even if something crashed during a measurement (blackout, …), all data up to this event are usually retained.

New in version 0.2.

class trepr.io.BES3TImporter(source=None)

Bases: aspecd.io.DatasetImporter

Importer for data in Bruker BES3T format.

The Bruker BES3T format consists of at least two files, a data file with extension “DTA” and a descriptor file with extension “DSC”. In case of multidimensional data, additional data files may be written (e.g. with extension “.YGF”), similarly to the case where the X axis is not equidistant (at least the BES3T specification allows this situation).

This importer currently only supports a smaller subset of the specification, e.g. only data without additional axes data files and only real values. This may, however, change in the future.

New in version 0.2.