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.

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 step that produced it. Operations from one protocol node share it. 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.

DETECT and MEASURE carry no detail of their own: a spikes fileset's own spec holds the detector's thresholds, and a kpi fileset's own records hold the parameters it measured with.

ACQUIRE, when present, is the first operation and says where the samples came from: the system that digitized a recording, or the foreign file an imported dataset was read out of.

UNKNOWN marks an operation 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.

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

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