Recording sessions ​
livn.data.rsf saves a run as a session in the recording session format (RSF) and reads sessions back, simulated or recorded, through the same calls.
It needs zarr 3 or later, which livn does not install for you (pip install 'zarr>=3').
Writing a session ​
from livn.data.rsf import load, store
env = env.record_spikes()
env = env.record_membrane_current()
env = env.record_voltage()
run = env.run(1000)
store(run, "sessions/spontaneous-1", env, voltage=True, currents=True)Under MPI, make sure to gather first store(run.gather(env.comm), path, env) so it writes on the root rank only.
Optional keywords:
label=,author=anddescription=: the session's name, who made it and a description.notes=[{"text", "frame", "author"}]: notes about the session or about a frame of it.withhold=[{"mask": {"fields": [...]}}]: what the session must not reveal (electrode_positions,source_positions,channel:<id>).gain_uV=anddtype=: how the traces are quantised.zone=: an IANA time zone, orTruefor the host's.ext={"<producer>": {"<name>.json": document}}: documents of another program, read back withrecording.ext(producer, name).
The traces are projected through the env's recording composition (env.io.recording, or store(..., recording=Chain(...))). To project a stored run again, use:
session = load("sessions/spontaneous-1")
env.potential_recording(session.io.recording, session.conditions())Reading a session ​
session = load("sessions/spontaneous-1")
session.run.potential # the channel signal in uV, one row per electrode
session.run.spike_times # on the frame grid of the signal
session.io # the MEA it was recorded through
session.simulation["seed"] # metadata
session.record # the provenance recordTo read windows without loading the whole session, open it with livn.data.open. The same calls work for an RSF session and for an Arrow dataset, local or on the Hugging Face hub:
from livn.data import open as open_recording
recording = open_recording("sessions/spontaneous-1")
recording = open_recording("./systems/datasets/spe1/c16")
recording = open_recording("hf://frthjf/spe1-zhao2026-benchmark/c16", split="test")
window = recording.read(0, start=30_000, length=15_000) # float32 [frames, channels], uV
units = recording.spikes(0) # Events, ids = unit idsspikes, inputs, ground_truth and to_run(segment, start, length) read windows the same way. A recording can be read from several threads and pickled.
livn.data.arrow.store(run, path, env=env, ground_truth=("spikes", "voltage")) writes a run as an Arrow dataset instead, one row per call.
Stimulated sessions ​
To keep what drove the run, pass either stimulus=policy or inputs=array, inputs_dt=ms in the stimulating IO's input units. Reading the delivered stimulus works the same on a recorded session:
recording = load("sessions/stimulated-1").recording
recording.stimulus_channels() # the channels, the columns of inputs()
recording.inputs(0, 0, 1000) # fractions of full scale, [frames, channels]
recording.inputs(0, 0, 1000, physical=True) # mW/mm2 and uA (cathodic negative)
recording.stimulus_full_scales() # {id: {"units", "value", ...}}
recording.stim_events() # the delivered edges
recording.stimulus_io() # PatternedLight / MEA / InputDevices of the channelsWhen a channel's calibration (recording.stimulus_calibrations()) states a latency_ms from the delivered edge to the sample, inputs(..., latency=True) applies it, and so do windows read with inputs=True.
Several programs ​
A stimulus made of several programs, such as the blocks of a protocol or light and electrodes driven together, is stored with programs= in place of stimulus= and inputs=. Each program gives a policy, or inputs with inputs_dt, and optionally:
start(ms) orstart_frame;stop: ms after its start, for a program stopped early;device: an index among the stimulating devices;channels: the channels it drives (by default those it sets non-zero);origin: where the program came from (by default the policy's);members: other programs' fields for its record.
A channel is driven by one program at a time.
store(run, "sessions/day-14", env, programs=[
{"policy": mapping_policy},
{"inputs": block, "inputs_dt": 0.1, "start": 500.0, "stop": 120.0},
])
recording = load("sessions/day-14").recording
recording.stimulation_records()[1]["channels"][0]["name"] # a channel's site name, e.g. a spot label
recording.planned(1) # what program 1 was to deliver
recording.check_delivered(1) # missing, extra and mistimed edges; an early stop is reported as a stopMatch a program's channels by their name, the stimulus site, which stays the same across sessions.
Preparations and epochs ​
prep={"id", "label", "kind", "species", "age", "expression", "models"} states the simulated preparation: age is its age at the start of the session, models the physical preparation it stands for, and id is generated when not given. Give the same id to every session of one preparation, for example its days in vitro:
from livn.data import rsf
rsf.same_preparation(a, b) # are two sessions of one preparation?
rsf.preparations(recordings) # sessions grouped by preparation, ordered by age
recording.prep # the preparation of one sessionepochs=[...] names spans of the session. Each epoch is {"key" or "item", "frame" or "start", "end_frame" or "end", "kind", "text", "parent", "programs", "origin"}, with kind one of protocol, block, baseline, spontaneous or spot_mapping, parent the key or item of the epoch it lies within, and programs indices into programs=. To write one run into several sessions, pass the same item in each; rsf.join_epochs(recordings) reads it back as one. recording.epochs() and recording.epoch_of(index) read a single session.
Ground truth ​
- Spikes, voltages and currents per cell
voltage=Trueandcurrents=True - Populations and opsin expression per cell via
populations=Trueandexpression=True(orexpression={construct: {"units", "values", "reference"}}) - Connections at the start of the run via
connections=True. Weights are multiples of the synapse's unitary conductance and presynaptic inputs that are not cells are listed separately - Stimulus coupling via
stimulus_coupling=True(not written whensource_positionsare withheld)
Read them back with recording.ground_truth(name), recording.sources(), recording.connections() and recording.stimulus_coupling().
Sorting stores ​
A session's sorting stores hold spikes or crossings found via spike sorting or a threshold detector, etc. Each is has the same layout as ground_truth/spikes.zarr, stored under sortings/.
recording = load("sessions/spontaneous-1").recording
for sorting in recording.sortings():
sorting.path, sorting.original, sorting.space, sorting.role, sorting.method_hash
events = recording.spikes(sorting="live") # by path, by name, or a Sorting
events.units # every unit, silent ones too; rows for a channel store
events.coverage # [start, stop) ms spans it covers, or None
recording.coverage("live") # the same
recording.extraction("live") # its method, method_hash, state_from_frame, ...To observe a simulated session through a threshold detector, as the instrument would, pass the method to store:
from livn.io.detection import threshold_method
method = threshold_method(k=5.0, sigma_window=1000.0) # 300-3000 Hz, 1 ms dead time
store(run, "sessions/spontaneous-1", env, sortings={"live": method})Copies without their samples ​
A copy of a session may omit its full trace (traces.zarr/traces_seg0) to save space, indicating the omission in traces.zarr/rsf/local/omitted.json and recording.samples_omitted.
Missing chunks ​
A read whose window touches trace chunks that are not in the store, because they were removed after upload or are not written yet, raises livn.data.rsf.SamplesMissing (a livn.data.Missing) naming the missing frames, rather than returning the zarr fill value as silence. Its ranges, keys and elsewhere say which frames, which chunks, and the copy a hidden .<name>-offloaded.json marker in the session folder names, if there is one. RsfRecording(path, fill_missing=True) reads them as zeros instead.
Sessions held elsewhere ​
RsfRecording(key, storage=...) reads a session through any object with three methods: read(path) -> bytes (raising FileNotFoundError), exists(path) -> bool for a file, and list(path) -> list[str] for the names directly under a folder. Paths are /-separated keys under key. livn ships only the local filesystem (LocalStorage, the default).
SpikeInterface ​
A session's traces open in SpikeInterface with spikeinterface.read_zarr("sessions/spontaneous-1/traces.zarr"), and its ground-truth spikes are a SpikeInterface sorting.