LFPackReader

LFPackReader(h5_file, recording=None, scale=0, bin_channels=1)

Drop-in spikeglx.Reader for HDF5-packed LFP-compressed files.

Chunks are decompressed on demand. No sync trace is available; read() with sync=True returns None as the second element. Data is returned in volts (float32) in the same (n_samples, n_channels) convention as spikeglx.Reader.

The HDF5 layout is ///meta and ///chunks/. A file may contain multiple recordings and/or multiple scale levels. When a file contains exactly one recording the key is auto-detected; otherwise pass recording=.

Parameters

Name	Type	Description	Default
h5_file	path - like	HDF5 archive produced by compress_to_h5.	required
recording	str or None	Recording key (top-level group name). Auto-detected when the file contains exactly one recording; raises ValueError for multi-recording files.	None
scale	int	Resolution level to open. 0 = base (full LFP rate). Default 0.	0
bin_channels	int	Number of adjacent channels to sum together on every read. 1 (default) means no binning. When set, nc, shape, and geometry all reflect the binned dimension, and slicing (sr[0:2500, :]) returns (n_samples, nc // bin_channels) without any extra arguments.	1

Examples

>>> sr = LFPackReader('lf_compressed.h5')
>>> sr[0:2500, :]                              # (2500, nc)
>>> sr4 = LFPackReader('lf_compressed.h5', bin_channels=4)
>>> sr4[0:2500, :]                             # (2500, nc // 4)
>>> sr4.nc                                     # nc // 4
>>> sr4.shape                                  # (ns, nc // 4)
>>> sr4.geometry['y'].shape                    # (nc // 4,)

Attributes

Name	Description
bin_channels	Number of adjacent channels summed on every read (1 = no binning).
channels	Per-channel info aggregated over bin groups when bin_channels > 1.
channels_full	Full per-electrode channel info, independent of bin_channels.
fs	LFP sample rate in Hz, sync-corrected when sync data is present.
geometry	Probe geometry averaged over each bin group.
geometry_full	Full per-electrode probe geometry, independent of bin_channels.
nc	Number of output channels (raw nc // bin_channels).
saturation	Insertion-level table of ADC-saturated intervals.
saturation_mask	Boolean saturation mask for the full recording, at this reader’s sampling rate.
saturation_summary	Summary of saturation over the whole recording, read from dataset attrs.
t0	Session-clock time in seconds at LFP sample 0. NaN when no sync data.
times	Session-clock timestamps in seconds for every LFP sample.

Methods

Name	Description
read	Decompress and return a sample range.
read_samples	Read and decompress a sample range with optional spatial binning.
recordings	List recording keys at the root of an H5 file written by compress_to_h5.
saturation_times	Saturation interval table with session-clock start/stop times.
scales	List scale indices available for a recording.

read

LFPackReader.read(
    nsel=slice(0, 10000),
    csel=slice(None),
    sync=True,
    bin_channels=None,
)

Decompress and return a sample range.

Parameters

Name	Type	Description	Default
nsel	slice or int	Sample selection (Python slice convention).	slice(0, 10000)
csel	slice or array - like	Channel selection applied after spatial binning.	slice(None)
sync	bool	If True returns (data, None); no sync trace in compressed files.	True
bin_channels	int or None	Number of adjacent channels to sum together. None uses self.bin_channels. csel indexes into the binned channels.	None

Returns

Name	Type	Description
data	(ndarray(n_samples, nc // bin_channels), float32, volts)
sync	None (only when sync=True)

read_samples

LFPackReader.read_samples(
    first_sample=0,
    last_sample=10000,
    channels=None,
    bin_channels=None,
)

Read and decompress a sample range with optional spatial binning.

Parameters

Name	Type	Description	Default
first_sample	int		0
last_sample	int		10000
channels	slice or array - like or None	Channel selection applied after binning. None selects all.	None
bin_channels	int or None	Number of adjacent channels to sum together. None uses self.bin_channels. Valid values: 1, 2, 4, 6, 8, 12.	None

Returns

Name	Type	Description
	(ndarray(n_samples, nc // bin_channels), float32, volts)

recordings

LFPackReader.recordings(h5_file)

List recording keys at the root of an H5 file written by compress_to_h5.

Parameters

Name	Type	Description	Default
h5_file	path - like		required

Returns

Name	Type	Description
	list of str

saturation_times

LFPackReader.saturation_times()

Saturation interval table with session-clock start/stop times.

Converts start_sample/stop_sample (raw-rate, recording-aligned) to start_time/stop_time (session-clock seconds, matching times) via the same sample-rate ratio and _sample_to_time used by times — never divide the raw samples by a raw sample rate by hand, and never re-derive the affine formula independently of .times (it would silently diverge on any scale with real non-linear sync structure).

Returns

Name	Type	Description
	pandas.DataFrame with columns start_sample, stop_sample, start_time,
	stop_time.

scales

LFPackReader.scales(h5_file, recording)

List scale indices available for a recording.

Parameters

Name	Type	Description	Default
h5_file	path - like		required
recording	str		required

Returns

Name	Type	Description
	list of int