You're reading an old version of this documentation. For up-to-date information, please have a look at v0.2.
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:
-
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.
-
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.
-
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.
-
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.DatasetImporterFactoryFactory 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.DatasetImporterFactorybase 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
-
-
class
trepr.io.SpeksimImporter(source='')¶ Bases:
aspecd.io.DatasetImporterImporter 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.
-
class
trepr.io.TezImporter(source='')¶ Bases:
aspecd.io.DatasetImporterImporter 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.
-
class
trepr.io.Fsc2Importer(source='')¶ Bases:
aspecd.io.DatasetImporterImporter 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.DatasetImporterImporter 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.