LIF Data Storage

LIF data are stored inside the same experiment folder as CP-FTMW data. For the experiment-folder naming convention and the files that every experiment writes (header.csv, hardware.csv, auxdata.csv, etc.), see Data Storage.

LIF-specific files are placed in a lif/ subdirectory of the experiment folder:

experiments/Z/Y/X/
├── header.csv
├── hardware.csv
├── auxdata.csv
├── ...
└── lif/
    ├── lifparams.csv
    ├── processing.csv
    ├── 0.csv
    ├── 1.csv
    └── ...

LIF parameters in header.csv

Before any LIF-specific files are read, the scan-axis parameters and digitizer configuration can be recovered from the experiment’s header.csv. Two sections are written:

  • LifConfig — the scan parameters set on the wizard’s LIF group (see LIF Experiment Setup).

  • LifDigitizer.<key> — the digitizer settings set on the LIF Configuration (the section name embeds the configured digitizer hardware key, e.g. LifDigitizer.Default).

For example, an experiment with a 6×6 (delay × laser) grid, 10 shots per point, randomized delay order, and a single-channel LIF acquisition writes the following LifConfig section to header.csv:

LifConfig;;;CompleteMode;StopWhenComplete;
LifConfig;;;DelayPoints;6;
LifConfig;;;DelayRandom;true;
LifConfig;;;DelayStart;200;μs
LifConfig;;;DelayStep;10;μs
LifConfig;;;LaserPoints;6;
LifConfig;;;LaserStart;250;nm
LifConfig;;;LaserStep;5;nm
LifConfig;;;ScanOrder;DelayFirst;
LifConfig;;;ShotsPerPoint;10;

The companion LifDigitizer.Default section captures the digitizer configuration that produced the trace files:

LifDigitizer.Default;;;BlockAverageEnabled;false;
LifDigitizer.Default;;;ByteOrder;LittleEndian;
LifDigitizer.Default;;;BytesPerPoint;1;
LifDigitizer.Default;;;LifChannel;1;
LifDigitizer.Default;;;LifRefChannel;2;
LifDigitizer.Default;;;LifRefEnabled;false;
LifDigitizer.Default;;;RecordLength;10000;
LifDigitizer.Default;;;SampleRate;1.25e+09;Hz
LifDigitizer.Default;;;TriggerChannel;0;
LifDigitizer.Default;;;TriggerDelay;0;μs
LifDigitizer.Default;;;TriggerEdge;RisingEdge;
LifDigitizer.Default;;;TriggerLevel;0.3;V
LifDigitizer.Default;AnalogChannel;0;Enabled;true;
LifDigitizer.Default;AnalogChannel;0;FullScale;0.05;V
LifDigitizer.Default;AnalogChannel;0;Index;1;
LifDigitizer.Default;AnalogChannel;0;VerticalOffset;0;V
LifDigitizer.Default;AnalogChannel;1;Enabled;false;
LifDigitizer.Default;AnalogChannel;1;FullScale;0.05;V
LifDigitizer.Default;AnalogChannel;1;Index;2;
LifDigitizer.Default;AnalogChannel;1;VerticalOffset;0;V

Together these sections fully describe how the trace files in lif/ were acquired. ShotsPerPoint is needed to convert the on-disk accumulated values to per-shot voltages (see below).

lif/lifparams.csv

This file is the index of all acquired trace files. One row is written per scan point that has been acquired. The columns are:

lIndex;dIndex;shots;lifsize;refsize;spacing;lifymult;refymult

  • lIndex — laser position index (0-based).

  • dIndex — delay index (0-based).

  • shots — number of waveforms accumulated at this point.

  • lifsize — number of samples per LIF channel waveform.

  • refsize — number of samples per reference channel waveform (0 when no reference channel is enabled).

  • spacing — time between samples, in seconds.

  • lifymult — scale factor to convert one LIF integer sample to volts.

  • refymult — scale factor to convert one reference integer sample to volts (0 when no reference channel is enabled).

For a single-channel acquisition with ShotsPerPoint = 10, a 10000-sample record at 1.25 GS/s, and a 50 mV / 128-step LIF range, lifparams.csv begins:

lIndex;dIndex;shots;lifsize;refsize;spacing;lifymult;refymult
0;0;10;10000;0;8e-10;0.000390625;0
1;0;10;10000;0;8e-10;0.000390625;0
2;0;10;10000;0;8e-10;0.000390625;0
...

lif/N.csv — trace files

Each acquired scan point is stored as a separate CSV file. The file name is an integer index N computed as:

N = dIndex * laserPoints + lIndex

This ordering matches the row order in lifparams.csv and allows direct file lookup given a delay and laser index pair. The same encoding scheme is used for FTMW data (see Data Storage): values are written as signed base-36 integers, one row per sample point. When only the LIF channel is recorded the file has a single lif column; when a reference channel is enabled, a second ref column is added.

A single-channel trace file from the example above begins:

lif
4b
-1b
-4i
-94
c0
3r
58
3n
3g
...

With the reference channel enabled, the file is:

lif;ref
<lifvalue0>;<refvalue0>
<lifvalue1>;<refvalue1>
...

Important

The on-disk values are the sum of raw digitizer samples across all shots, not the co-averaged waveform. To recover the per-shot voltage for sample i of a given scan point, divide by shots first and then apply the y-multiplier:

\[V_i = \frac{v_i}{N_\text{shots}} \times y_\text{mult}\]

where shots and ymult come from the matching row of lifparams.csv. This convention matches the FTMW FID files and lets Blackchirp resume averaging when an experiment is reopened.

The blackchirp Python package (pip install blackchirp) provides loader functions that perform the base-36 decoding and per-shot voltage conversion for both LIF and FTMW data, returning numpy arrays.

lif/processing.csv

This file records the integration gate positions and waveform-filter settings associated with the experiment. It is always present: when an experiment begins, Blackchirp writes the gate and filter values active on the LIF Configuration at that moment, so the file captures the processing state used during acquisition. Clicking Save in the LIF tab’s processing panel (see Viewing LIF Data) overwrites the file with the current values, making them the new defaults when the experiment is reopened.

The file uses the standard ObjKey;Value metadata layout:

ObjKey;Value
LifGateEndPoint;1421
LifGateStartPoint;240
LowPassAlpha;0
RefGateEndPoint;1
RefGateStartPoint;0
SavGolEnabled;false
SavGolPoly;3
SavGolWindow;11

The keys correspond to the controls described on the LIF tab processing panel:

  • LifGateStartPoint, LifGateEndPoint — LIF integration gate bounds, in sample points.

  • RefGateStartPoint, RefGateEndPoint — reference integration gate bounds, in sample points.

  • LowPassAlpha — IIR low-pass filter coefficient (0 = disabled).

  • SavGolEnabled — whether the Savitzky-Golay filter is active.

  • SavGolWindow, SavGolPoly — Savitzky-Golay window size and polynomial order.