BCLIF

BCLIF is the LIF-scan container exposed by BCExperiment as exp.lif whenever the experiment folder contains a lif/ subdirectory. On construction it reads lif/lifparams.csv and lif/processing.csv and pulls the DelayPoints / DelayStart / DelayStep and LaserPoints / LaserStart / LaserStep rows out of the experiment header so the full delay × laser scan grid is known up-front. Per-point trace files are read lazily through get_trace; opening an LIF experiment is therefore cheap regardless of grid size.

The class provides three aggregating helpers — delay_slice, laser_slice, and image — that integrate every present scan point with one processing-override surface, returning numpy arrays sized against the full scan axes. Scan grids are routinely incomplete: acquisitions can stop partway through, leaving some (lIndex, dIndex) positions with no trace file. Those positions are filled with np.nan by default; pass fill=0.0 (or any other numeric value) when a zero-baseline image is preferred. The has_ref attribute reports whether any point in the scan recorded a reference channel, derived from the refsize column of lifparams.csv.

The on-disk format that BCLIF reads — the lif/ subdirectory layout, the meaning of each lifparams.csv column, the processing.csv integration-gate settings — is documented in detail on the LIF Data Storage user-guide page.

API Reference

class blackchirp.BCLIF(path: str, sep: str, header: pandas.DataFrame)

Container for a complete LIF scan.

Loads lif/lifparams.csv and lif/processing.csv and reads the scan-axis parameters (DelayStart, LaserStart, etc.) from the supplied experiment header. Exposes per-point access via get_trace() and aggregating helpers (delay_slice(), laser_slice(), image()) that integrate every present point with a single processing-override surface.

This class is not intended to be instantiated directly; it is constructed by BCExperiment whenever the experiment folder contains a lif/ subdirectory.

Parameters:

  • path – Experiment folder path.

  • sep – CSV delimiter for the experiment.

  • header – Experiment header DataFrame (BCExperiment.header) used to read LifConfig scan-axis rows.

lifparams

Contents of lif/lifparams.csv.

Type:

pd.DataFrame

proc

Contents of lif/processing.csv parsed to typed values (ints, floats, bools).

Type:

dict

delay_points

Number of delay-axis points.

Type:

int

delay_start

First delay value, in delay_units.

Type:

float

delay_step

Delay-axis step, in delay_units.

Type:

float

delay_units

Units of delay_start / delay_step.

Type:

str

laser_points

Number of laser-axis points.

Type:

int

laser_start

First laser value, in laser_units.

Type:

float

laser_step

Laser-axis step, in laser_units.

Type:

float

laser_units

Units of laser_start / laser_step.

Type:

str

has_ref

True if any lifparams row has refsize > 0.

Type:

bool

numtraces

Number of populated scan points (len(lifparams)).

Type:

int

delay_axis() → Tuple[numpy.ndarray, str]

Return the delay-axis sample values and their units string.

delay_slice(l_index: int, fill=numpy.nan, **proc) → Tuple[numpy.ndarray, numpy.ndarray]

Integrate every present trace at one laser index.

Parameters:

  • l_index – Laser-axis index to slice.

  • fill – Value substituted at delay indices that have no acquired trace (np.nan by default; pass 0.0 to represent missing points as zero).

  • **proc – Optional processing overrides, forwarded to BCLifTrace.integrate().

Returns:

Tuple (delay_axis, integrals). Length of both is delay_points.

get_trace(l_index: int, d_index: int) → BCLifTrace

Load a single BCLifTrace from disk.

Parameters:

  • l_index – Laser-axis index.

  • d_index – Delay-axis index.

Returns:

A freshly loaded BCLifTrace.

Raises:

KeyError – If no row exists in lifparams.csv for the requested (l_index, d_index) pair (i.e. the scan point was not acquired).

image(fill=numpy.nan, **proc) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Integrate every present trace into a 2D delay × laser image.

Parameters:

  • fill – Value substituted at (d, l) positions that have no acquired trace.

  • **proc – Optional processing overrides, forwarded to BCLifTrace.integrate().

Returns:

Tuple (delay_axis, laser_axis, integrals) where integrals has shape (delay_points, laser_points).

laser_axis() → Tuple[numpy.ndarray, str]

Return the laser-axis sample values and their units string.

laser_slice(d_index: int, fill=numpy.nan, **proc) → Tuple[numpy.ndarray, numpy.ndarray]

Integrate every present trace at one delay index.

Parameters:

  • d_index – Delay-axis index to slice.

  • fill – Value substituted at laser indices that have no acquired trace.

  • **proc – Optional processing overrides, forwarded to BCLifTrace.integrate().

Returns:

Tuple (laser_axis, integrals). Length of both is laser_points.