You're reading the documentation for a development version. For the latest released version, please have a look at v0.2.
trepr.dataset module
Datasets: units containing data and metadata.
The dataset is one key concept of the ASpecD framework and hence the trepr package derived from it, consisting of the data as well as the corresponding metadata. Storing metadata in a structured way is a prerequisite for a semantic understanding within the routines. Furthermore, a history of every processing, analysis and annotation step is recorded as well, aiming at a maximum of reproducibility. This is part of how the ASpecD framework and therefore the trepr package tries to support good scientific practice.
Therefore, each processing and analysis step of data should always be performed using the respective methods of a dataset, at least as long as it can be performed on a single dataset.
Datasets
Generally, there are two types of datasets: Those containing experimental data and those containing calculated data. Therefore, two corresponding subclasses exist:
Metadata
Furthermore, in this module, the individual metadata classes are defined which contain the individual information about the experiment:
What may sound like a minor detail is one key aspect of the trepr package:
The metadata and their structure provide a unified interface for all
functionality operating on datasets. Furthermore, the metadata contained
particularly in the trepr.dataset.ExperimentalDatasetMetadata class
are the result of more than fifteen years of practical experience. Reproducible
research is only possible if all information necessary is always recorded,
and this starts with all the metadata accompanying a measurement. Defining
what kind of metadata is important and needs to be recorded, together with
metadata formats easily writable by the experimenters during recording the
data requires a thorough understanding of both, the method and the setup(s)
used. For an overview of the structures of the dataset classes and their
corresponding metadata, see the dataset structure
section.
Dataset factory
Particularly in case of recipe-driven data analysis (c.f. aspecd.tasks),
there is a need to automatically retrieve datasets using nothing more than a
source string that can be, e.g., a path or LOI. This is where the
DatasetFactory comes in. This is a factory in the sense of the factory
pattern described by the “Gang of Four” in their seminal work, “Design
Patterns” (Gamma et al., 1995):
Module documentation
- class trepr.dataset.Dataset
Bases:
DatasetBase class for all kinds of datasets.
Generally, there are two types of datasets: Those containing experimental data and those containing calculated data. Therefore, two corresponding subclasses exist:
As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the
aspecd.dataset.Datasetclass for details.
- class trepr.dataset.ExperimentalDataset
Bases:
ExperimentalDatasetEntity consisting of experimental data and metadata.
On the one hand this class extends the metadata contained in the metadata property. On the other hand this class extends the dataset by further
aspecd.dataset.Dataobjects containing additional variable parameters with independent axes useful for further analysis.- metadata
Metadata of dataset.
- time_stamp
Time stamp of each individual time trace.
Note: actual time stamp data will not be available for each file format.
- Type:
- microwave_frequency
Microwave frequency of each individual time trace.
Note: actual frequency data will not be available for each file format.
- Type:
- class trepr.dataset.CalculatedDataset
Bases:
CalculatedDatasetEntity consisting of calculated data and metadata.
As the class is fully inherited from ASpecD for simple usage, see the ASpecD documentation of the
aspecd.dataset.CalculatedDatasetclass for details.
- class trepr.dataset.DatasetFactory
Bases:
DatasetFactoryFactory for creating dataset objects based on the source provided.
Particularly in case of recipe-driven data analysis, there is a need to automatically retrieve datasets using nothing more than a source string that can be, e.g., a path or LOI.
The DatasetFactory operates in conjunction with a
trepr.io.DatasetImporterFactoryto import the actual dataset. See the respective class documentation for more details.- importer_factory
ImporterFactory instance used for importing datasets
- class trepr.dataset.ExperimentalDatasetMetadata
Bases:
ExperimentalDatasetMetadataMetadata for an experimental TREPR dataset.
The metadata and their structure implemented in this class are one key aspect of the trepr package. They provide a unified interface for all functionality operating on datasets. Additionally, the metadata and their structure are the result of more than fifteen years of practical experience. Defining what kind of metadata is important and needs to be recorded, together with metadata formats easily writable by the experimenters during recording the data requires a thorough understanding of both, the method and the setup(s) used.
Each attribute is an instance of the respective subclass. For details of the attributes of these classes, see their respective documentation.
Metadata can be converted to dict via
aspecd.utils.ToDictMixin.to_dict(), e.g., for generating reports using templates and template engines.- measurement
Metadata corresponding to the measurement.
- sample
Metadata corresponding to the sample.
- Type:
- transient
Metadata corresponding to the transient.
- Type:
- experiment
Metadata corresponding to the experiment.
- Type:
- spectrometer
Metadata corresponding to the spectrometer.
- magnetic_field
Metadata corresponding to the magnetic field.
- background
Metadata corresponding to the background.
- Type:
- bridge
Metadata corresponding to the bridge.
- Type:
- video_amplifier
Metadata corresponding to the video amplifier.
- recorder
Metadata corresponding to the recorder.
- Type:
- probehead
Metadata corresponding to the probehead.
- Type:
- pump
Metadata corresponding to the pump.
- Type:
- temperature_control
Metadata corresponding to the temperature control.
- class trepr.dataset.CalculatedDatasetMetadata
Bases:
CalculatedDatasetMetadataMetadata for a calculated dataset.
This class contains the minimal set of metadata for a dataset consisting of calculated data, i.e.,
trepr.dataset.CalculatedDataset.Metadata of actual datasets should extend this class by adding properties that are themselves classes inheriting from
aspecd.metadata.Metadata.Metadata can be converted to dict via
aspecd.utils.ToDictMixin.to_dict(), e.g., for generating reports using templates and template engines.
- class trepr.dataset.Measurement(dict_=None)
Bases:
MeasurementMetadata corresponding to the measurement.
As this class inherits from
aspecd.metadata.Measurement, see the documentation of the parent class for details and the full list of inherited attributes.- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- class trepr.dataset.Sample(dict_=None)
Bases:
SampleMetadata corresponding to the sample.
As this class inherits from
aspecd.metadata.Sample, see the documentation of the parent class for details and the full list of inherited attributes.- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- class trepr.dataset.Transient(dict_=None)
Bases:
MetadataMetadata corresponding to the transient.
A transient or time trace is the EPR signal intensity over time for a given magnetic field point. A full 2D TREPR dataset usually consists of a series of transients for different magnetic field points that are sequentially recorded.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- length
Object of the PhysicalQuantity class from ASpecD.
- class trepr.dataset.Experiment(dict_=None)
Bases:
MetadataMetadata corresponding to the experiment.
Two parameters are relevant for a TREPR experiment that are not contained in other parts of the metadata: Number of runs and the shot repetition rate. The latter is determined by the laser system used as pump source.
Note that a TREPR experiment can be understood as a special variant of a pump-probe experiment with the laser excitation acting as pump and the EPR signal intensity recording as function of time as probe.
Typical shot repetition rates range from 20 Hz to less than 1 Hz and are mostly determined not only by the laser system used but as well by the kinetics of the sample investigated. To prevent degradation, the sample should be fully returned to its ground state between two excitations. The TREPR signal decay can not be used as a valid measure of the kinetics and the return of the sample to its ground state, as the spin polarisation usually decays much faster than the sample returns to its ground state.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- shot_repetition_rate
Shot repetition rate of the experiment.
- class trepr.dataset.Spectrometer(dict_=None)
Bases:
MetadataMetadata corresponding to the spectrometer.
TREPR spectrometers almost always consist of several exchangeable components, even if commercially available modular systems (e.g. Bruker EMX or ELEXSYS) are used. Therefore, the spectrometer model and the software (including its version information) need to be recorded.
All the other components of the (TR)EPR spectrometer, such as magnet system, microwave bridge and amplifier, recorder, probehead and laser system, as well as the temperature controller have their own respective classes containing the necessary information.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- class trepr.dataset.MagneticField(dict_=None)
Bases:
MetadataMetadata corresponding to the magnetic field.
The external magnetic field is a crucial component of EPR spectroscopy, and the corresponding metadata contain both, information about the settings relevant for the experiment conducted as well as the devices ( field probe, controller, power supply) used. The latter is crucial, as most EPR spectrometers (with the exception of highly integrated benchtop devices) are modular and consist of exchangeable components.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- field_probe_type
Type of field probe used.
Usually, a Hall probe will be used, with a somewhat limited accuracy. The other option is to use a Teslameter, i.e. a small NMR device, providing much higher accuracy.
- Type:
- start
Start of the magnetic field sweep.
- stop
End of the magnetic field sweep.
- step
Step size of the magnetic field sweep.
- class trepr.dataset.Background(dict_=None)
Bases:
MetadataMetadata corresponding to the background.
When recording TREPR data, the laser excitation typically creates a field-independent background signal that needs to be subtracted from the data.
There are different ways of how to measure the background signal. The simplest (and most often used) approach is to record sufficient baseline at the lower and upper magnetic field range. Other approaches are to record the background every Nth time trace and directly subtract this background signal in the transient recorder. Both methods have their advantages and disadvantages. For details, see the literature.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- field
Magnetic field position of background trace.
- polarisation
Type of background polarisation i.e. absorptive or emissive.
An emissive polarisation is a clear hint that the phase is set 180° off.
- Type:
- intensity
Amplitude of background signal.
Sometimes, the background signal intensity can be much larger than the actual signal intensity, and in this case, the signal shape strongly depends on the stability of the setup, as a large background intensity gets subtracted. Therefore, knowing the background signal intensity is particulary important in case it is directly subtracted during data recording.
- class trepr.dataset.Bridge(dict_=None)
Bases:
MetadataMetadata corresponding to the microwave bridge.
The microwave bridge contains the microwave source and parts of the detection system. Therefore, the crucial experimental parameters such as attenuation and power, microwave frequency and detection system used are contained as well as the description of the devices, i.e. the bridge itself, its controller, and the frequency counter, as these can be different interchangeable components.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- attenuation
Attenuation of the microwave power in dB.
Without knowing the unattenuated source power, the attenuation is a rather useless value, although it gets often used, particularly in lab jargon. Typical microwave bridges have source powers of 200 mW in X-Band, but newer devices sometimes deliver only 150 mW.
- power
Output power of the microwave.
The actual output power of the microwave used for the experiment, i.e. the source power reduced by the attenuation. Typical values are in the range of 20 mW to 20 µW.
- detection
Type of the detection used.
There are two types of detection: diode and mixer. The latter usually allows for quadrature detection, i.e. detecting both, the absorptive and dispersive signal components.
For the best time resolution, mixer detection in conjunction with a video amplifier get used, whereas conventional cw-EPR bridges only have diode detection combined with a rather low-bandwidth preamplifier.
- Type:
- frequency_counter
Model of the frequency counter used.
Depending on the setup used, this can be included in the bridge. Otherwise, it will often be a HP device.
- Type:
- mw_frequency
Microwave frequency.
The actual microwave frequency used for the experiment. Usually, this is a scalar number. Depending on the experiment control software used, the microwave frequency for each transient will be recorded, thus allowing for analysing frequency drifts. This is particularly helpful in case of long-running experiments (12+ h). By comparing the amplitude of the frequency drift with the field step width, the potential impact in the signal shape can be directly calculated.
- class trepr.dataset.VideoAmplifier(dict_=None)
Bases:
MetadataMetadata corresponding to the video amplifier.
Depending on the detection (diode or mixer), either a low-bandwidth preamplifier will be used or a high-bandwidth video amplifier. The latter is only true for dedicated transient or pulsed bridges.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- bandwidth
Bandwidth of the video amplifier.
Depending on the specific model, values such as 20, 50, 100, and 200 dB are typically found. Newer devices have only reduced settings.
The bandwidth of the amplifier is one of the parameters determining the overall time resolution of the system, but higher bandwidth usually comes with higher noise levels.
- amplification
Amplification in dB.
- class trepr.dataset.Recorder(dict_=None)
Bases:
MetadataMetadata corresponding to the recorder.
The recorder works as an A/D converter, recording the time-dependent EPR signal intensity with high time resolution.
Typically, digital oscilloscopes are used as transient recorders for TREPR spectroscopy. In case of commercially available pulsed EPR setups (Bruker ELEXSYS), the SpecJet can be used, basically a digital oscilloscope as well.
Two characteristics of a transient recorder are particularly important: the time resolution (determined by the bandwidth and time base), and the vertical resolution. While the former is rarely limiting for TREPR spectra, the vertical resolution is often rather an issue. While stand-alone digital oscilloscopes provided a vertical resolution of 11 bit already in the 1990s, only with the advent of the Bruker SpecJet III the vertical resolution for commercial Bruker spectrometers has increased beyond 8 bit. The latter is rather useless for recording TREPR data, as it translates to only 256 discrete steps. Having in mind that typically, TREPR spectra consist of both, absorptive and emissive signal components, this amounts to at most only 128 discrete steps per direction in the signal maximum. Therefore, weaker parts of the overall signal are usually not well resolved in this case.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- averages
Number of accumulations recorded.
Typically, at least 20, but often several hundreds of accumulations are recorded for each individual field point to increase the signal-to-noise ratio.
- Type:
- time_base
Time base of the recorder.
The time base is the time between two data points recorded. The time base should be much shorter (by a factor of 5–10) than the inverse bandwidth of the slowest component of the signal to faithfully digitise the actual signal shape (Nyquist sampling theorem).
Note: While the time base is part of the time resolution of the overall system, usually, the time base of the recorder is not the limiting characteristic, but rather either the bandwidth of the microwave amplifier or the probehead.
- bandwidth
Bandwidth of the recorder.
Typically, bandwidth and time base are connected. For the bandwidth, the same applies that has been said for the time base.
- pretrigger
Length of time trace before the actual trigger.
Transients should never start with the actual laser excitation, but rather some time before, in order to allow for compensating for DC offsets.
Note that the trigger point does not necessarily allow for determining the true signal rise time, due to the time the electrical signal takes to travel through the cables. After all, the speed of light translates “only” to 30 cm per nanosecond, and with typical cable lengths of several metres, this translates well into tens of nanoseconds.
- impedance
Impedance of the recorder input channel.
The impedance setting of the recorder input should match that of the output of the detector. Take care of any additional filters or alike in the signal pathway that typically change the impedance. While microwave bridges usually have 50 Ohm impedance, high-pass filters will typically translate this to several kOhm, making it necessary to change the impedance of the recorder input channel to 1 MOhm.
- sensitivity
Sensitivity of the recorder.
The sensitivity setting determines the vertical resolution of the signal. Therefore, the optimum should be sought after between maximum vertical resolution and not clipping the signal.
- class trepr.dataset.Probehead(dict_=None)
Bases:
MetadataMetadata corresponding to the probehead.
Often, resonating structures get used in EPR spectroscopy, but as this is not always the case, the term “probehead” is more generic.
In all except of fully integrated benchtop spectrometers, the probehead can readily be exchanged. As each probehead has its own characteristics, it is crucially important to note at least type and model. The coupling (critically or overcoupled) determines the bandwidth of the resonator, and in all but pulsed experiments, usually, critical coupling is used.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- type
Type of the probehead used.
There are several different types of probeheads regularly used. For resonators, there are, e.g., dielectic and split-ring resonators, cylindrical and rectangular cavities. More special would be Fabry-Perot and stripline resonators. Sometimes, even resonator-free designs are used as probeheads.
- Type:
- model
Model of the probehead used.
Commercial probeheads come with a distinct model that goes in here. In all other cases, use a short, memorisable, and unique name.
- Type:
- class trepr.dataset.Pump(dict_=None)
Bases:
MetadataMetadata corresponding to the optical excitation..
A TREPR experiment can be understood as a special variant of a pump-probe experiment with the laser excitation acting as pump and the EPR signal intensity recording as function of time as probe.
This class contains all information necessary to describe the laser system used as a pump. This includes, besides wavelength, power, and repetition rate, the type of tunable (if any), and filters situated within the beam path.
- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class
- type
Type of the pump used.
This typically translates to “laser”, and it may be extended by the actual type of laser (e.g., Nd:YAG).
- Type:
- wavelength
Wavelength of the optical excitation.
Depending on whether a tunable light source (OPO, dye laser) is used, this can be either rather discrete wavelengths (the harmonics of the fundamental wavelength of the laser used), or specific wavelengths (typically with an accuracy of 1 nm).
- power
Power of the optical excitation.
Values are typically in the range of 0.5–5 mJ. Make sure to always record the laser power, as too high laser powers can damage your sample (or even your setup).
Note that measuring the laser power is typically done outside the probehead. Therefore, the actual laser power incident at the sample is much less, depending on how well you’ve focussed/collimated the excitation beam as well as on the physical structure of the window in the probehead. Often, the window contains a metal grid used to prevent moo much micrwove leakage, but reducing the incident laser power on the sample further.
- repetition_rate
Repetition rate of the optical excitation.
Typical values range from 20 Hz to <1 Hz. The repetition rate of the pump determines the shot repetition rate of the whole experiment.
The kinetics of the sample investigated is crucial for determining the correct repetition rate. To prevent degradation, the sample should be fully returned to its ground state between two excitations. The TREPR signal decay can not be used as a valid measure of the kinetics and the return of the sample to its ground state, as the spin polarisation usually decays much faster than the sample returns to its ground state.
- tunable_position
Position of the tunable used.
In case of an OPO, you may provide the position of the stepper motor here. Please note that these values can only be used for comparision within one setup and one calibration.
- Type:
- class trepr.dataset.TemperatureControl(dict_=None)
Bases:
TemperatureControlMetadata corresponding to the temperature control.
As this class inherits from
aspecd.metadata.TemperatureControl, see the documentation of the parent class for details and the full list of inherited attributes.- Parameters:
dict (
dict) – Dictionary containing fields corresponding to attributes of the class