radiens_core.models.provenance

Provenance domain models: the ordered account of how a dataset came to be.

CLASS	DESCRIPTION
`Provenance`	Everything known about how a dataset came to be.
`ProvenanceAcquire`	Where a dataset's samples came from.
`ProvenanceDecimate`	A change of sample rate by resampling.
`ProvenanceFilter`	One filter that shaped the samples.
`ProvenanceFilterStructure`	How a recorded filter's coefficients are laid out.
`ProvenanceOp`	One operation applied to a dataset's samples.
`ProvenanceOpKind`	What an operation did.
`ProvenanceOrigin`	What produced an operation.
`ProvenanceRecord`	The ordered account of what shaped a dataset's samples.
`ProvenanceRemapSensor`	A change of which probe and headstage each port carries.
`ProvenanceSelectChannels`	A selection of channels.
`ProvenanceSliceTime`	A trim in time.
`ProvenanceSort`	The spike sort that labeled a fileset.
`ProvenanceWrite`	Where the stream was persisted as a dataset.
`SensorAssignment`	One port's probe and headstage.
`TimestampRange`	A half-open range of hardware timestamps.

Classes

Provenance

Bases: BaseModel

Everything known about how a dataset came to be.

Every operation in record altered the stored samples. stage2_dsp did not: it is applied when the data is read.

ATTRIBUTE	DESCRIPTION
`record`	What shaped the samples. For a dataset written before records existed, it is reconstructed from older metadata and marked `reconstructed`. TYPE: `ProvenanceRecord \| None`
`stage2_dsp`	The stage-2 chain in force when recording started. Empty for anything that is not a recording, and for a recording written before the chain was recorded. TYPE: `list[ProvenanceFilter]`

ProvenanceAcquire

Bases: BaseModel

Where a dataset's samples came from.

A recording may set the first two fields and an import the last two, never both.

ATTRIBUTE	DESCRIPTION
`backbone_mode`	Acquisition system that digitized a recording (`"XDAQ_GEN2_CORE_REC"`). `None` for an import. TYPE: `str \| None`
`allego_version`	Version of the Allego app that drove the recording. `None` for an import, or when it was not recorded. TYPE: `str \| None`
`source_type`	Format an imported dataset was read out of (`"SPIKEGLX"`). `None` for a recording. TYPE: `str \| None`
`source_name`	The foreign dataset's name on disk, never a path. `None` for a recording. TYPE: `str \| None`

ProvenanceDecimate

Bases: BaseModel

A change of sample rate by resampling.

A lowpass applied before it is a separate FILTER operation with the same node_id.

ATTRIBUTE	DESCRIPTION
`factor`	Integer decimation factor. TYPE: `int \| None`
`output_fs`	Resulting sample rate, in Hz. TYPE: `float \| None`

ProvenanceFilter

Bases: BaseModel

One filter that shaped the samples.

ATTRIBUTE	DESCRIPTION
`type`	Filter type. TYPE: `DSPType \| None`
`fs`	Sample rate the filter was designed at, in Hz. A cutoff recorded before a decimate cannot be read against the dataset's current rate without it. TYPE: `float \| None`
`freq_spec`	Realized cutoffs in Hz — one for lowpass, highpass and notch, two for bandpass and bandstop. Each is the family's own reference level: the half-power point for Butterworth, the ripple band edge for Chebyshev-I. Never a requested passband edge. TYPE: `list[float]`
`notch_bandwidth`	Notch width in Hz. `None` for every other type. TYPE: `float \| None`
`filter_order`	Filter order. TYPE: `int \| None`
`family`	IIR design family. TYPE: `FilterFamily \| None`
`ripple_db`	Chebyshev-I passband ripple in dB. `None` for Butterworth, which has none. TYPE: `float \| None`
`zero_phase`	Whether the filter ran forward and backward. TYPE: `bool \| None`
`port`	Port the filter ran on. `None` for a filter applied by a transform (origin `CURATE`), which runs on every channel. TYPE: `Port \| None`
`ref_ntv_chan_idx`	Reference channel, for a referencing filter. TYPE: `int \| None`
`target_ntv_chan_idx`	Target channel, for a paired reference. TYPE: `int \| None`
`structure`	How `b` and `a` are laid out. `None` when the built filter was not available to read. TYPE: `ProvenanceFilterStructure \| None`
`b`	Numerator coefficients; three per section when `structure` is `SOS`. TYPE: `list[float]`
`a`	Denominator coefficients; three per section when `structure` is `SOS`. TYPE: `list[float]`

ProvenanceFilterStructure

Bases: IntEnum

How a recorded filter's coefficients are laid out.

ATTRIBUTE	DESCRIPTION
`UNSPECIFIED`	Unknown: the built filter was not available to read. Does not mean direct form.
`DIRECT`	Direct-form transfer function coefficients.
`SOS`	Second-order sections.

ProvenanceOp

Bases: BaseModel

One operation applied to a dataset's samples.

kind says which detail field is set; the rest are None.

ATTRIBUTE	DESCRIPTION
`kind`	What the operation did. TYPE: `ProvenanceOpKind`
`origin`	What produced it. TYPE: `ProvenanceOrigin`
`node_id`	Identifies the protocol node that produced it. Operations from one node share it. `""` for every origin other than a curate protocol. TYPE: `str`
`protocol_id`	ID of the curate protocol that applied it. `""` for every other origin. TYPE: `str`
`server_version`	Version of the Radiens server that performed it. `None` if not recorded. TYPE: `str \| None`
`filter`	Set when `kind` is `FILTER`. TYPE: `ProvenanceFilter \| None`
`decimate`	Set when `kind` is `DECIMATE`. TYPE: `ProvenanceDecimate \| None`
`select_channels`	Set when `kind` is `SELECT_CHANNELS`. TYPE: `ProvenanceSelectChannels \| None`
`remap_sensor`	Set when `kind` is `REMAP_SENSOR`. TYPE: `ProvenanceRemapSensor \| None`
`slice_time`	Set when `kind` is `SLICE_TIME`. TYPE: `ProvenanceSliceTime \| None`
`write`	Set when `kind` is `WRITE`. TYPE: `ProvenanceWrite \| None`
`sort`	Set when `kind` is `SORT`. TYPE: `ProvenanceSort \| None`
`acquire`	Set when `kind` is `ACQUIRE`. TYPE: `ProvenanceAcquire \| None`

ProvenanceOpKind

Bases: StrEnum

What an operation did.

For every kind except DETECT, MEASURE and UNKNOWN, the ProvenanceOp field of the same name holds the detail.

ATTRIBUTE	DESCRIPTION
`FILTER`	Applied a filter or reference.
`DECIMATE`	Reduced the sample rate.
`SELECT_CHANNELS`	Kept a subset of channels.
`REMAP_SENSOR`	Replaced the probe map.
`SLICE_TIME`	Kept a time range.
`WRITE`	Wrote a dataset to a file.
`DETECT`	Detected spikes. A spikes fileset's own spec holds the detector's thresholds.
`MEASURE`	Measured KPI metrics. A KPI fileset's own records hold the parameters it measured with.
`SORT`	Sorted spikes.
`ACQUIRE`	Where the samples came from: the system that digitized a recording, or the foreign file an imported dataset was read out of. When present, it is the first operation.
`UNKNOWN`	Written by a newer backend than this client models. The origin and node are still readable; the detail is not.

ProvenanceOrigin

Bases: IntEnum

What produced an operation.

ATTRIBUTE	DESCRIPTION
`UNKNOWN`	Not attributable. Files from older servers record acquisition and curation filters in one list, so those filters report this.
`HARDWARE`	The acquisition system: its hardware filters, and the `ACQUIRE` operation of a recording.
`ACQUISITION_STAGE1`	Stage 1 filters applied during acquisition.
`SPIKE_SORT`	The spike sorter, including the filters spikes were detected through.
`CURATE`	A curation transform or protocol.
`KPI`	KPI measurement.
`IMPORT`	Reading a file written by other software. Marks the `ACQUIRE` operation of an imported dataset.

ProvenanceRecord

Bases: BaseModel

The ordered account of what shaped a dataset's samples.

ATTRIBUTE	DESCRIPTION
`version`	Schema version the record was written at. TYPE: `int`
`ops`	Operations in the order they were applied. TYPE: `list[ProvenanceOp]`
`reconstructed`	Whether the operations were assembled from older metadata, in which case a missing detail could not be recovered. A dataset derived from a reconstructed one is also marked reconstructed. TYPE: `bool`

ProvenanceRemapSensor

Bases: BaseModel

A change of which probe and headstage each port carries.

ATTRIBUTE	DESCRIPTION
`prior`	Assignments before the remap. TYPE: `list[SensorAssignment]`
`assigned`	Assignments after it. TYPE: `list[SensorAssignment]`

ProvenanceSelectChannels

Bases: BaseModel

A selection of channels.

ATTRIBUTE	DESCRIPTION
`prior_sys_chan_idxs`	System channel indices present before the selection. TYPE: `list[int]`
`retained_sys_chan_idxs`	System channel indices kept. TYPE: `list[int]`

ProvenanceSliceTime

Bases: BaseModel

A trim in time.

ATTRIBUTE	DESCRIPTION
`source`	Timestamp range of the dataset that was trimmed. TYPE: `TimestampRange \| None`
`retained`	Timestamp range kept. TYPE: `TimestampRange \| None`

ProvenanceSort

Bases: BaseModel

The spike sort that labeled a fileset.

ATTRIBUTE	DESCRIPTION
`seed`	Seed of the sort's random draws. Pass it as `SpikeSorterLaunchParams.seed` to reproduce the sort on the build named by the operation's `server_version`. TYPE: `int \| None`
`clusterer_params`	The launch's clusterer params as sent. `None` when the launch omitted them, or the sort was recorded by a server too old to record them. TYPE: `SpikeSorterClustererParams \| None`
`feature_params`	The launch's feature params as sent, with the same `None` cases. TYPE: `SpikeSorterFeatureParams \| None`

ProvenanceWrite

Bases: BaseModel

Where the stream was persisted as a dataset.

Names the ancestor the following operations were applied to.

ATTRIBUTE	DESCRIPTION
`dataset_uid`	UID of the dataset written. TYPE: `str`
`file_type`	File type written. `""` for a live or cache source, and for a write reconstructed from older metadata. TYPE: `str`

SensorAssignment

Bases: BaseModel

One port's probe and headstage.

ATTRIBUTE	DESCRIPTION
`port`	Port name. TYPE: `str`
`probe_id`	Probe identifier. TYPE: `str`
`headstage_id`	Headstage identifier. TYPE: `str`

TimestampRange

Bases: BaseModel

A half-open range of hardware timestamps.

ATTRIBUTE	DESCRIPTION
`start`	First timestamp in the range. TYPE: `int`
`end`	One past the last timestamp in the range. TYPE: `int`