arista.preprocess.io

File I/O for raw inputs and preprocessed outputs.

This module replaces the I/O sprinkled across _legacy/pytci/tempFileIO.py and _legacy/aristaSingleCellData.py with pure functions that return typed dataclasses instead of mutating self.

Three input formats are accepted for Fiji ΔF/F exports:

  • X,Y header (Alex Busch’s older fixtures)

  • Frame,Mean header (Alex Busch’s later fixtures)

  • frame,df/f header (legacy aristaSingleCellData.py output)

All three collapse to the same FijiRecording dataclass.

Functions

read_fiji_csv(path)

Read a Fiji ΔF/F₀ ROI export into a FijiRecording.

read_recording_csv(path)

Re-read a canonical write_recording_csv() output.

read_sensor_mat(path)

Read a MATLAB temperature_data_*.mat sensor record.

write_recording_csv(recording, path)

Persist a Recording to disk as a canonical CSV.

Classes

FijiRecording(frame, dfbf)

Raw Fiji ROI export — one ΔF/F₀ value per imaging frame.

Recording(frame, time_s, sensor_t_c, ...[, ...])

Frame-aligned, optionally drift-corrected Ca²⁺ recording.

SensorRecord(epoch_time, frame, sensor_t_c, ...)

Raw MATLAB sensor record — continuously logged 5-column array.
class arista.preprocess.io.FijiRecording(frame, dfbf)[source]

Bases: object

Raw Fiji ROI export — one ΔF/F₀ value per imaging frame.

Parameters:
dfbf: numpy.ndarray
frame: numpy.ndarray
property n_frames: int
class arista.preprocess.io.Recording(frame, time_s, sensor_t_c, target_t_c, drive_t_c, dfbf, dfbf_drift_corrected=None, drift_method='none', recording_date=None)[source]

Bases: object

Frame-aligned, optionally drift-corrected Ca²⁺ recording.

One row per imaging frame. Matches the column layout of the samples table in [[Database Schema]] so the ingester can bulk-insert directly.

dfbf_drift_corrected is None whenever drift_method == "none".

recording_date is the calendar date the recording started, extracted from the first sensor MAT epoch during alignment. The ingester uses it to populate animals.recording_date.

Parameters:

  • frame (np.ndarray)

  • time_s (np.ndarray)

  • sensor_t_c (np.ndarray)

  • target_t_c (np.ndarray)

  • drive_t_c (np.ndarray | None)

  • dfbf (np.ndarray)

  • dfbf_drift_corrected (np.ndarray | None)

  • drift_method (str)

  • recording_date (str | None)

dfbf: np.ndarray
dfbf_drift_corrected: np.ndarray | None = None
drift_method: str = 'none'
drive_t_c: np.ndarray | None
frame: np.ndarray
property n_frames: int
recording_date: str | None = None
sensor_t_c: np.ndarray
target_t_c: np.ndarray
time_s: np.ndarray
to_dataframe()[source]

Return the recording as a pandas DataFrame with DB-schema columns.

Return type:

pandas.DataFrame

class arista.preprocess.io.SensorRecord(epoch_time, frame, sensor_t_c, target_t_c, drive_t_c)[source]

Bases: object

Raw MATLAB sensor record — continuously logged 5-column array.

Each MAT file holds a data matrix whose columns are, in order: epoch_time (MATLAB serial datenum), frame index (1-based!), sensor_T (°C, actually measured), target_T (°C, set-point) and drive_T (°C, applied to the Peltier element). The log rate is higher than the imaging rate so multiple sensor rows share the same frame number; arista.preprocess.align() collapses them.

Parameters:
drive_t_c: numpy.ndarray
epoch_time: numpy.ndarray
frame: numpy.ndarray
property n_samples: int
sensor_t_c: numpy.ndarray
target_t_c: numpy.ndarray
arista.preprocess.io.read_fiji_csv(path)[source]

Read a Fiji ΔF/F₀ ROI export into a FijiRecording.

Accepts any of the three header conventions documented in the module docstring. Header is required (no headerless CSV support; that would silently re-interpret the first frame as a column name and corrupt downstream alignment).

Parameters:

path (Path | str) – Path to the CSV file.

Returns:

Frozen FijiRecording with frame and dfbf as numpy arrays.

Raises:

ValueError – If neither a frame-like nor a value-like column is present, or if frame indices are not monotonically increasing.

Return type:

FijiRecording

arista.preprocess.io.read_recording_csv(path)[source]

Re-read a canonical write_recording_csv() output.

Parameters:

path (Path | str)

Return type:

Recording

arista.preprocess.io.read_sensor_mat(path)[source]

Read a MATLAB temperature_data_*.mat sensor record.

The MAT file must contain a top-level variable data shaped (n_samples, 5): [epoch_time, frame, sensor_T, target_T, drive_T].

Parameters:

path (Path | str) – Path to the .mat file.

Returns:

Frozen SensorRecord with the five columns as separate arrays.

Raises:

  • KeyError – If the MAT file lacks a data variable.

  • ValueError – If the data matrix is not 5 columns wide.

Return type:

SensorRecord

arista.preprocess.io.write_recording_csv(recording, path)[source]

Persist a Recording to disk as a canonical CSV.

Column order matches the samples table in [[Database Schema]] so arista-ingest can COPY-style load without remapping. Two #-prefixed header lines carry recording-level provenance:

  • # drift_method: <method> — which drift correction was applied

  • # recording_date: <YYYY-MM-DD> — calendar date of frame 0, omitted when the recording carries no date

Parameters:

  • recording (Recording) – The recording to write.

  • path (Path | str) – Destination CSV path.

Returns:

The resolved path the file was written to.

Return type:

Path