compress_bin_to_h5

compress_bin_to_h5(
    bin_file,
    out_h5,
    recording=None,
    q=10,
    h=None,
    cadzow_checkpoint_file=None,
    cadzow=True,
    cadzow_kwargs=None,
    channel_labels=None,
    epsilon=100.0,
    alpha=7.0,
    n_jobs=4,
    chunk=_COMPRESS_CHUNK,
    overlap=_COMPRESS_OVERLAP,
    highpass_cutoff=0.5,
    car=True,
    fig_dir=None,
    t0_sync=None,
    fs_sync=None,
    detect_saturation=True,
    saturation_kwargs=None,
    basis_size=_container.BASIS_SIZE,
)

Full pipeline: raw LFP binary → decimate → Cadzow denoise → SVD+WP compress → HDF5.

Decimation uses ibldsp.voltage.resample_denoise_lfp_cbin (FIR anti-aliasing). Cadzow denoising is performed inside each decimation worker unless cadzow is False. An intermediate float32 checkpoint (.npy) is always written — either to the path given by cadzow_checkpoint_file or to a sibling temp file that is deleted after the HDF5 is finalised. If the checkpoint file already exists its contents are used directly, skipping the expensive decimate+denoise step.

Bad channels are detected automatically (via ibldsp.voltage.detect_bad_channels_cbin) before decimation unless channel_labels is supplied or the checkpoint already exists. Dead and noisy channels are interpolated before the common-average reference, which prevents incoherent channels from inflating the SVD noise floor and rank.

Parameters

Name	Type	Description	Default
bin_file	path - like	SpikeGLX LFP binary (.cbin or .bin). The .meta file must be in the same directory.	required
out_h5	path - like	Output HDF5 file (created or overwritten).	required
recording	str or None	Unique key for this recording (e.g. a probe-insertion UUID). Stored as the top-level HDF5 group; multiple recordings can coexist in one file. Defaults to the stem of bin_file when None.	`None`
q	int	Decimation factor. Default 10 (2500 → 250 Hz).	`10`
h	dict or None	Probe header with keys ‘x’ and ‘y’. Defaults to NP1 geometry for nc channels.	`None`
cadzow_checkpoint_file	path - like or None	Path for the intermediate Cadzow .npy checkpoint (ns_lf, nc) float32. If None a temporary file is written next to out_h5 and deleted afterwards. If the file already exists the decimate+Cadzow step is skipped entirely.	`None`
cadzow	bool	Cadzow denoising with the latest ibl-neuropixel settings for the probe geometry (NP1 or NP2, see `cadzow_lfp_kwargs`). Default True; False is pure decimation.	`True`
cadzow_kwargs	dict or None	Overrides of those settings (`ibldsp.cadzow.cadzow_denoiser` parameters); None keeps them. The dead and noisy channels are estimated by Cadzow (`bad_channels_as_missing=True` of `resample_denoise_lfp_cbin`) instead of being interpolated after it; pass `bad_channels_as_missing=False` to interpolate. Ignored when cadzow is False.	`None`
channel_labels	np.ndarray or None	Per-channel quality labels (0=good, 1=dead, 2=noisy, 3=outside brain). If None and the checkpoint does not exist, labels are auto-detected via ibldsp.voltage.detect_bad_channels_cbin. Pass an array of zeros to skip detection explicitly.	`None`
epsilon	float	SVD threshold multiplier. Default 100.	`100.0`
alpha	float	WP threshold multiplier. Default 7.	`7.0`
n_jobs	int	Parallel workers for the decimate+Cadzow stage. Default 4.	`4`
chunk	int	Compress chunk size in decimated samples. Default 2048.	`_COMPRESS_CHUNK`
overlap	int	SVD guard-band samples each side. Default 128.	`_COMPRESS_OVERLAP`
highpass_cutoff	float or None	3rd-order Butterworth zero-phase highpass corner [Hz] applied before decimation. Default 0.5 Hz — keeps delta/infra-slow content; benchmarking (0.5/1/2 Hz) showed faithful reconstruction with negligible compression-ratio impact and no chunk-seam artefact (ibldsp warmup padding scales with the corner). None disables the filter.	`0.5`
car	bool	Apply median common-average reference before decimation. Default True.	`True`
fig_dir	path - like or None	If set, a bad-channel diagnostic figure is saved to this directory after detection. Uses ibldsp.plots.show_channels_labels on a single mid-recording batch. Filename: `bad_channels_{bin_file.stem}.png`. Default None (no figure).	`None`
detect_saturation	bool	If True (default), detect ADC-saturated samples on the raw LFP band before any pre-processing (which would otherwise obscure the clipping), store the saturated intervals as an insertion-level table in the HDF5 file, and — unless the decimation is skipped because the checkpoint exists — mute the saturated stretches on the decimated output after Cadzow, so no pre-processing stage can leak energy back into the muted span. See `ibldsp.voltage.saturation`.	`True`
saturation_kwargs	dict or None	Forwarded to `ibldsp.voltage.saturation_cbin` (keys: `max_voltage`, `v_per_sec`, `proportion`, `mute_window_samples`). Default None uses the ibldsp defaults with `max_voltage` taken from the SpikeGLX metadata.	`None`
basis_size	int	Shared spatial basis size, forwarded to `compress_to_h5`. Default 32.	`_container.BASIS_SIZE`

Returns

Name	Type	Description
	Path	Path to the output HDF5 file.