You're reading the documentation for a development version. For the latest released version, please have a look at v0.2.
Metadata during data acquisition
(Numerical) data without accompanying metadata are pretty useless, as data can only be analysed (and the results somewhat reproduced) knowing the context of their recording, i.e. what (instrumental) parameters have been used for data acquisition and what sample has been measured. While the trepr package takes care of recording all metadata acquired during data processing and analysis, thanks to being based on the ASpecD framework, we are here concerned with metadata during data acquisition, i.e. the step before the trepr package enters the stage.
Important
While most spectrometers automatically record some instrumental parameters and include them in the vendor file format, usually these parameters are not sufficiently complete, and essential information such as what sample has been measured (by whom) is regularly not included. Hence, you need to manually record essential metadata during data acquisition, and to allow the trepr package to access these crucial metadata, you better use a file format that can automatically be imported together with the data.
The Infofile format
Recording metadata during data acquisition is both, an essential aspect of and as old as science itself. The Infofile format is a simple textual file format developed to document research data. It allows researchers in the lab to record all relevant metadata during data acquisition in a user-friendly and obvious way while minimising any external dependencies. The resulting machine-actionable metadata in turn allow processing and analysis software to access relevant information, besides making the research data more reproducible and FAIRer.
Tip
The trepr package will automatically look for a file with the same base name and the extension .info when importing files. Hence, the clear advice is to make it a habit to record all relevant metadata in an Infofile during data acquisition and store it next to the actual data files.
Further information on the format including the full specification and a discussion of the advantages (and disadvantages) compared to other formats can be found in the following publication:
Bernd Paulus, Till Biskup: Towards more reproducible and FAIRer research data: documenting provenance during data acquisition using the Infofile format. Digital Discovery 2:234–244, 2023, doi:10.1039/D2DD00131D
For actual Infofile example files, see the git repository available at GitHub:
An example of a tr-EPR Infofile is provided below for convenience as well.
Features
Simple text format
Storing structured, machine-actionable metadata
Minimum formatting overhead
Focussing on human-writability
No external (software) dependencies
Easily extendable
Benefits
No thinking required: never miss any relevant parameter
All information for the materials&methods part always available (even for collaboration partners)
Automatic import using the trepr package: information available during data processing and analysis (and in reports)
Big step forward towards truly reproducible research
Example
Below is a full example of a Infofile for a tr-EPR measurement. The format should be pretty self-explaining. Whether you need every block depends on your setup and type of experiment. For templates and information regarding further development, see the corresponding GitHub repository. A full format description is given in the accompanying publication.
trEPR Info file - v. 0.1.6 (2016-01-18)
GENERAL
Filename: sample42
Date start: 2014-12-01
Date end: 2014-12-01
Time start: 10:00:00
Time end: 10:15:00
Operator: John Doe
Label: #42 @ 120 K
Purpose: First overview
SAMPLE
Name: something
ID: 42
Description: frozen solution
Solvent: oDCB
Preparation: 1 mM, degassed
Tube: 3.8 x 3 x 180 mm
EXPERIMENT
Runs: 1
Shot Repetition Rate: 1 Hz
SPECTROMETER
Model: ESP380E
Software: Transient, Vers. 0.6
MAGNETIC FIELD
Field probe type: Hall
Field probe model: xxx
Start: 290 mT
Stop: 390 mT
Step: 0.4 mT
Sequence: inward
Controller: Bruker 032 T
Power supply: Bruker 083 C
BACKGROUND
Field: 300.0 mT
Occurrence: 10
Polarisation: absorptive
Intensity: 8.8 mV
BRIDGE
Model: Bruker ER 046 MRT
Controller: Bruker MBC
Attenuation: 20 dB
Power: 2.01 mW
Detection: mixer
Frequency counter: HP 5352B
MW frequency: 9.6657 GHz
VIDEO AMPLIFIER
Bandwidth: 25 MHz
Amplification: 42 dB
RECORDER
Model: LeCroy 9354A
Averages: 1000
Time base: 2 ns
Bandwidth: 500 MHz
Pretrigger: 1.001 us
Coupling: DC
Impedance: 50 Ohm
Sensitivity: 20 mV
TRANSIENT
Points: 5000
Length: 10 us
Trigger Position: 500
PROBEHEAD
Type: dielectric
Model: Bruker ER 4118X-MD5
Coupling: critical
PUMP
Type: Laser
Model: GCR 190-10
Wavelength: 460 nm
Power: 1 mJ
Repetition rate: 10 Hz
Tunable type: OPO
Tunable model: OPTA BBO VIS/IR
Tunable dye: N/A
Tunable position: 11450
Filter: ND T=0.25
TEMPERATURE
Temperature: 120 K
Controller: Oxford ITC 503
Cryostat: Oxford ESR935
Cryogen: LN2
FIELD CALIBRATION
Filename: N/A
Field probe type: Gaussmeter
Field probe model: xxx
Standard: LiLiF
Signal field: xx G
MW Frequency: xx GHz
COMMENT
Deviation GM-HP of about 1.1 G.
After 480 transients, coupling and field
had been drifted. Readjustment at 3499.2 G.
Metadata and commercial EPR spectrometers
While many commercially available EPR spectrometers do include a number of parameters in their vendor file formats (e.g., Bruker and Magnettech), these automatically obtained parameter values can have two problems:
Incomplete
More often than not, not all devices are directly connected to and controlled by the measurement program. Typical examples include temperature controllers. Those parameters cannot be obtained automatically by the measurement program and hence do not enter the parameter list of the written data files.
Other parameters are not readable per se, such as the actual resonator/probehead in the spectrometer, and for older setups the individual components and their model numbers, including microwave bridge, signal channel, field controller, power supply and alike. However, all that information is crucial for a sensible materials&methods part of your publication.
Wrong
Even more problematic, some vendors do not save the data after the measurement finished, but only when the operator explicitly tells the measurement program to store the data to disk. What might sound only annoying (as you can easily loose your data) is yet a bigger problem: The parameter values read from the devices and stored in the parameters section of the vendor file format get read at the time point when the operator saves the file. Imagine a long-running measurement ending in the middle of the night, with several hours passing between end of measurement and pressing the “save” button in the software. Whatever instrumental parameter has changed in the meantime (prime example: drifting microwave frequency) gets saved with a potential wrong parameter. Even worse: if you happen to accidentally change some parameter settings after finishing the measurement and before storing the data, the new settings will be saved, not those used for performing the measurement.
While highly integrated benchtop spectrometers are somewhat better in this respect (no exchangeable components, higher integration), there is a need to both, record additional metadata not stored in the vendor file formats, and to record parameters that are contained in the vendor file formats but may be the wrong values.