radiens_core.models.dataset

Dataset metadata, time-range selection, and curation protocol graph models.

TYPE ALIAS	DESCRIPTION
TransformParams	Union of all transform parameter types (or None for parameter-free nodes).

CLASS	DESCRIPTION
BandParams	Parameters for band-pass or band-stop filter transform nodes.
BulkSinkParams	Parameters for BULK_SINK transform nodes.
BulkSourceParams	Parameters for BULK_SOURCE transform nodes.
CARParams	Parameters for Common Average Reference transform nodes (no fields).
DatasetMetadata	Metadata for a linked dataset.
DownsampleParams	Parameters for downsample transform nodes.
FileInfo	Filesystem entry metadata returned by list_directory.
HighLowPassParams	Parameters for high-pass or low-pass filter transform nodes.
NotchParams	Parameters for notch filter transform nodes.
PairedRefParams	Parameters for paired reference transform nodes.
ProtocolSpec	Minimal summary of a saved protocol.
RadiensFileType	Recording file type.
SinkParams	Parameters for SINK transform nodes.
SliceChannelsParams	Parameters for channel-slice transform nodes.
SliceTimeParams	Parameters for time-slice transform nodes.
SourceParams	Parameters for SOURCE transform nodes.
TimeRangeSpec	Semantic time range specification with embedded mode.
TransformEdge	A directed edge connecting two nodes in a protocol graph.
TransformNode	A node in a curation protocol transform graph.
TransformNodeType	Transform node type for curation protocol graphs.
TrsMode	Time range selection mode.
VirtualRefParams	Parameters for virtual reference transform nodes.

ATTRIBUTE	DESCRIPTION
FlexDataset	DatasetMetadata, a dataset ID, or a file path.
FlexTimeRange	TimeRangeSpec, or a [start, end] list or tuple in seconds of stream time.

Attributes

FlexDataset module-attribute

FlexDataset = DatasetMetadata | str | Path

DatasetMetadata, a dataset ID, or a file path.

A string is treated as a path when it contains a path separator (e.g. ./rec.xdat), otherwise as a dataset ID. Pass a Path for a file in the working directory.

FlexTimeRange module-attribute

FlexTimeRange = TimeRangeSpec | Sequence[float]

TimeRangeSpec, or a [start, end] list or tuple in seconds of stream time.

[start, end] reads that span, and an infinite edge is open: [t, inf] reads from t to the end of the data, and [-inf, inf] reads all of it, as None does where a method accepts it. [duration, nan] reads the most recent duration seconds; only get_signals() accepts it.

The server clips the range to the data it holds when the call runs, so a recording still being written reads up to its current end, and the result reports the range served. With an older Radiens server, ranges are resolved against DatasetMetadata.time_range instead, which for a growing recording is its extent when the server first loaded it.

Type Aliases

TransformParams

TransformParams = (
    HighLowPassParams
    | BandParams
    | NotchParams
    | CARParams
    | VirtualRefParams
    | PairedRefParams
    | SliceTimeParams
    | SliceChannelsParams
    | DownsampleParams
    | SourceParams
    | SinkParams
    | BulkSourceParams
    | BulkSinkParams
    | None
)

Union of all transform parameter types (or None for parameter-free nodes).

Classes

BandParams

Bases: BaseModel

Parameters for band-pass or band-stop filter transform nodes.

ATTRIBUTE	DESCRIPTION
high_frequency	Upper cutoff frequency in Hz. TYPE: float
low_frequency	Lower cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None

Attributes

high_frequency instance-attribute

high_frequency: float

Upper cutoff frequency in Hz.

low_frequency instance-attribute

low_frequency: float

Lower cutoff frequency in Hz.

order class-attribute instance-attribute

order: int | None = None

Filter order; None uses the server default.

BulkSinkParams

Bases: BaseModel

Parameters for BULK_SINK transform nodes.

ATTRIBUTE	DESCRIPTION
file_type	Output recording file format. TYPE: RadiensFileType
path	Output directory path. TYPE: str
suffix	Appended to each input's base name after an underscore to name its output. TYPE: str

Attributes

file_type instance-attribute

file_type: RadiensFileType

Output recording file format.

path instance-attribute

path: str

Output directory path.

suffix instance-attribute

suffix: str

Appended to each input's base name after an underscore to name its output.

BulkSourceParams

Bases: BaseModel

Parameters for BULK_SOURCE transform nodes.

ATTRIBUTE	DESCRIPTION
sources	One entry per input dataset. TYPE: list[SourceParams]

Attributes

sources instance-attribute

sources: list[SourceParams]

One entry per input dataset.

CARParams

Bases: BaseModel

Parameters for Common Average Reference transform nodes (no fields).

DatasetMetadata

Bases: BaseModel

Metadata for a linked dataset.

Returned by link_data_file() and similar operations. Contains everything needed to query signals from this dataset.

ATTRIBUTE	DESCRIPTION
id	Dataset ID assigned when the file was linked; accepted wherever a dataset argument is. TYPE: str
base_name	Recording file name without directory or extension. TYPE: str
path	Directory containing the recording. TYPE: str
file_type	Type of the recording file. TYPE: RadiensFileType
time_range	Extent of the dataset in stream time; see TimeRange.sec. For a recording still being written this is the extent when the server first loaded it; get_tailing_state().available_time_range is the current extent. TYPE: TimeRange
channel_metadata	Channel configuration and metadata. TYPE: ChannelMetadata
associated_spikes_ids	Every spikes fileset the server has registered for this recording, sorted. Includes sorts launched by other clients, such as the desktop apps. Empty if the recording has none. TYPE: list[str]

Attributes

base_path property

base_path: Path

Directory joined with the base name, without a file extension.

duration property

duration: float

Dataset duration in seconds.

sampling_rate property

sampling_rate: float

Sampling rate in Hz.

DownsampleParams

Bases: BaseModel

Parameters for downsample transform nodes.

ATTRIBUTE	DESCRIPTION
factor	Downsampling factor (e.g., 2, 4, 10). TYPE: int

Attributes

factor instance-attribute

factor: int

Downsampling factor (e.g., 2, 4, 10).

FileInfo

Bases: BaseModel

Filesystem entry metadata returned by list_directory.

ATTRIBUTE	DESCRIPTION
path	Directory containing the file. TYPE: str
base_name	File name without directory or extension. TYPE: str
file_type	Type of the recording file. TYPE: RadiensFileType
dataset_uid	Identifier stored in the recording's own metadata; not the same as DatasetMetadata.id. TYPE: str
num_channels	Number of channels in the file. TYPE: int
duration_sec	Total duration of the recording in seconds. TYPE: float
sample_rate	Sampling rate in Hertz. TYPE: int
num_bytes	Size of the file in bytes. TYPE: int

HighLowPassParams

Bases: BaseModel

Parameters for high-pass or low-pass filter transform nodes.

ATTRIBUTE	DESCRIPTION
frequency	Cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None

Attributes

frequency instance-attribute

frequency: float

Cutoff frequency in Hz.

order class-attribute instance-attribute

order: int | None = None

Filter order; None uses the server default.

NotchParams

Bases: BaseModel

Parameters for notch filter transform nodes.

Note

The notch filter is always second-order, so it takes no order.

ATTRIBUTE	DESCRIPTION
bandwidth	Width of the rejection band in Hz. Must be positive. TYPE: float
frequency	Center frequency to reject in Hz. TYPE: float
notch_frequency	Deprecated alias of frequency, removed in 0.1.0. TYPE: float

Attributes

bandwidth instance-attribute

bandwidth: float

Width of the rejection band in Hz. Must be positive.

frequency instance-attribute

frequency: float

Center frequency to reject in Hz.

notch_frequency property

notch_frequency: float

Deprecated alias of frequency, removed in 0.1.0.

PairedRefParams

Bases: BaseModel

Parameters for paired reference transform nodes.

ATTRIBUTE	DESCRIPTION
ref_channel	Native channel index of the reference electrode. TYPE: int
target_channel	Native channel index of the channel to re-reference. TYPE: int

Attributes

ref_channel instance-attribute

ref_channel: int

Native channel index of the reference electrode.

target_channel instance-attribute

target_channel: int

Native channel index of the channel to re-reference.

ProtocolSpec

Bases: BaseModel

Minimal summary of a saved protocol.

Returned by get_protocol and get_all_protocols.

ATTRIBUTE	DESCRIPTION
id	Unique identifier for the protocol. TYPE: str
node_count	Number of nodes defined in the protocol. TYPE: int

RadiensFileType

Bases: IntEnum

Recording file type.

SinkParams

Bases: BaseModel

Parameters for SINK transform nodes.

ATTRIBUTE	DESCRIPTION
base_name	Output base filename (without extension or directory). TYPE: str
file_type	Output recording file format. TYPE: RadiensFileType
path	Output directory path. TYPE: str

Attributes

base_name instance-attribute

base_name: str

Output base filename (without extension or directory).

file_type instance-attribute

file_type: RadiensFileType

Output recording file format.

path instance-attribute

path: str

Output directory path.

SliceChannelsParams

Bases: BaseModel

Parameters for channel-slice transform nodes.

ATTRIBUTE	DESCRIPTION
channels	System channel indices (KeyIdxs.sys) to keep. TYPE: list[int]

Attributes

channels instance-attribute

channels: list[int]

System channel indices (KeyIdxs.sys) to keep.

SliceTimeParams

Bases: BaseModel

Parameters for time-slice transform nodes.

ATTRIBUTE	DESCRIPTION
end_sec	End of the window, in seconds of stream time. TYPE: float
start_sec	Start of the window, in seconds of stream time. TYPE: float

Attributes

end_sec instance-attribute

end_sec: float

End of the window, in seconds of stream time.

start_sec instance-attribute

start_sec: float

Start of the window, in seconds of stream time.

SourceParams

Bases: BaseModel

Parameters for SOURCE transform nodes.

ATTRIBUTE	DESCRIPTION
base_name	Base filename (without extension or directory). TYPE: str
dataset_id	ID of the linked dataset, for reference only: the server opens the source from TYPE: str
file_type	Recording file format. TYPE: RadiensFileType
path	Directory path containing the dataset. TYPE: str

Attributes

base_name instance-attribute

base_name: str

Base filename (without extension or directory).

dataset_id class-attribute instance-attribute

dataset_id: str = ''

ID of the linked dataset, for reference only: the server opens the source from path, base_name and file_type.

file_type instance-attribute

file_type: RadiensFileType

Recording file format.

path instance-attribute

path: str

Directory path containing the dataset.

TimeRangeSpec

Bases: BaseModel

Semantic time range specification with embedded mode.

Use factory methods to create specs with clear semantics:

t0 = meta.time_range.sec[0] spec = TimeRangeSpec.subset(t0, t0 + 10) # First 10 seconds spec = TimeRangeSpec.lookback(5.0) # Last 5 seconds spec = TimeRangeSpec.full() # Entire recording

ATTRIBUTE	DESCRIPTION
mode	Time range selection mode. TYPE: TrsMode
start	Start time or duration depending on the mode. TYPE: float
end	End time for subset mode. TYPE: float | None

METHOD	DESCRIPTION
from_list	Create from a [start, end] or [duration, nan] list; see FlexTimeRange.
full	All of the data.
is_full	Check if this is a full-range specification.
lookback	The most recent duration seconds. Only get_signals() accepts it.
resolve	Resolve to a concrete TimeRange.
subset	Time range [start, end) in seconds of stream time; see TimeRange.sec.
to_array	Convert to [start, end], [start, inf] for to_head(), or [duration, nan].
to_head	From start seconds of stream time to the end of the data.

Attributes

duration property

duration: float | None

Duration in seconds, if known.

Functions

from_list classmethod

from_list(time_range: list[float], mode: TrsMode | None = None) -> TimeRangeSpec

Create from a [start, end] or [duration, nan] list; see FlexTimeRange.

full classmethod

full() -> TimeRangeSpec

All of the data.

is_full

is_full() -> bool

Check if this is a full-range specification.

lookback classmethod

lookback(duration: float) -> TimeRangeSpec

The most recent duration seconds. Only get_signals() accepts it.

resolve

resolve(
    dataset_metadata: object | None = None, fs: float | None = None
) -> TimeRange | None

Resolve to a concrete TimeRange.

PARAMETER	DESCRIPTION
dataset_metadata	Dataset metadata used to obtain fs and dataset bounds. TYPE: object | None DEFAULT: None
fs	Sampling rate override. Defaults to the dataset's rate. TYPE: float | None DEFAULT: None

RETURNS	DESCRIPTION
TimeRange | None	None for FROM_HEAD mode — caller must use to_array() instead. Otherwise the resolved, concrete TimeRange.

RAISES	DESCRIPTION
ValueError	If dataset_metadata is not a DatasetMetadata, or, for SUBSET mode, the range ends at or before the dataset's start. A range past the dataset's end is accepted.

subset classmethod

subset(start: float, end: float) -> TimeRangeSpec

Time range [start, end) in seconds of stream time; see TimeRange.sec.

An infinite end reads to the end of the data. A range past the dataset's end is accepted, because a recording still being written grows past its linked extent.

RAISES	DESCRIPTION
ValueError	If end <= start.

to_array

to_array() -> NDArray[float64]

Convert to [start, end], [start, inf] for to_head(), or [duration, nan].

to_head classmethod

to_head(start: float) -> TimeRangeSpec

From start seconds of stream time to the end of the data.

TransformEdge

Bases: BaseModel

A directed edge connecting two nodes in a protocol graph.

Use the source and target fields to specify connectivity by node ID.

ATTRIBUTE	DESCRIPTION
id	Edge ID (auto-generated UUID if not provided). TYPE: str
source	ID of the source transform node. TYPE: str
target	ID of the target transform node. TYPE: str

Attributes

id class-attribute instance-attribute

id: str = Field(default_factory=lambda: str(uuid4()))

Edge ID (auto-generated UUID if not provided).

source instance-attribute

source: str

ID of the source transform node.

target instance-attribute

target: str

ID of the target transform node.

TransformNode

Bases: BaseModel

A node in a curation protocol transform graph.

Construct nodes using the factory class methods for convenience:

src = TransformNode.source(dataset_meta)
hp = TransformNode.highpass(frequency=300.0)
snk = TransformNode.sink("filtered", "/output", RadiensFileType.XDAT)

edges = [
    TransformEdge(source=src.id, target=hp.id),
    TransformEdge(source=hp.id, target=snk.id),
]

Then pass [src, hp, snk] and edges to VidereClient.set_protocol().

Note

Each factory method sets the correct type and params for its transform. When constructing manually, the params object must match the type (e.g., CAR_REF requires params=CARParams()).

METHOD	DESCRIPTION
bandpass	Create a BANDPASS_FILTER node.
bandstop	Create a BANDSTOP_FILTER node.
bulk_sink	Create a BULK_SINK node.
bulk_source	Create a BULK_SOURCE node from multiple linked datasets.
car	Create a CAR_REF (Common Average Reference) node.
downsample	Create a DOWNSAMPLE node.
highpass	Create a HIGHPASS_FILTER node.
lowpass	Create a LOWPASS_FILTER node.
notch	Create a NOTCH_FILTER node.
paired_ref	Create a PAIRED_REF node.
sink	Create a SINK node.
slice_channels	Create a SLICE_CHANNELS node.
slice_time	Create a SLICE_TIME node.
source	Create a SOURCE node from a linked dataset.
virtual_ref	Create a VIRTUAL_REF node.

ATTRIBUTE	DESCRIPTION
id	Node ID (auto-generated UUID if not provided). TYPE: str
params	Operation parameters; see each factory method for the expected type. TYPE: TransformParams
type	Transform operation this node performs. TYPE: TransformNodeType

Attributes

id class-attribute instance-attribute

id: str = Field(default_factory=lambda: str(uuid4()))

Node ID (auto-generated UUID if not provided).

params class-attribute instance-attribute

params: TransformParams = None

Operation parameters; see each factory method for the expected type.

type instance-attribute

type: TransformNodeType

Transform operation this node performs.

Functions

bandpass classmethod

bandpass(
    low_frequency: float, high_frequency: float, order: int | None = None
) -> TransformNode

Create a BANDPASS_FILTER node.

PARAMETER	DESCRIPTION
low_frequency	Lower cutoff frequency in Hz. TYPE: float
high_frequency	Upper cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None DEFAULT: None

bandstop classmethod

bandstop(
    low_frequency: float, high_frequency: float, order: int | None = None
) -> TransformNode

Create a BANDSTOP_FILTER node.

PARAMETER	DESCRIPTION
low_frequency	Lower cutoff frequency in Hz. TYPE: float
high_frequency	Upper cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None DEFAULT: None

bulk_sink classmethod

bulk_sink(suffix: str, path: str, file_type: RadiensFileType) -> TransformNode

Create a BULK_SINK node.

PARAMETER	DESCRIPTION
suffix	Appended to each input's base name after an underscore to name its output. TYPE: str
path	Output directory path. TYPE: str
file_type	Output recording file format. TYPE: RadiensFileType

bulk_source classmethod

bulk_source(datasets: list[DatasetMetadata]) -> TransformNode

Create a BULK_SOURCE node from multiple linked datasets.

PARAMETER	DESCRIPTION
datasets	Metadata for all input datasets. TYPE: list[DatasetMetadata]

car classmethod

car() -> TransformNode

Create a CAR_REF (Common Average Reference) node.

downsample classmethod

downsample(factor: int) -> TransformNode

Create a DOWNSAMPLE node.

PARAMETER	DESCRIPTION
factor	Downsampling factor (e.g., 2, 4, 10). TYPE: int

highpass classmethod

highpass(frequency: float, order: int | None = None) -> TransformNode

Create a HIGHPASS_FILTER node.

PARAMETER	DESCRIPTION
frequency	Cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None DEFAULT: None

lowpass classmethod

lowpass(frequency: float, order: int | None = None) -> TransformNode

Create a LOWPASS_FILTER node.

PARAMETER	DESCRIPTION
frequency	Cutoff frequency in Hz. TYPE: float
order	Filter order; None uses the server default. TYPE: int | None DEFAULT: None

notch classmethod

notch(frequency: float, bandwidth: float) -> TransformNode

Create a NOTCH_FILTER node.

PARAMETER	DESCRIPTION
frequency	Center frequency to reject in Hz. Also accepted as the deprecated notch_frequency=, removed in 0.1.0. TYPE: float
bandwidth	Width of the rejection band in Hz. TYPE: float

paired_ref classmethod

paired_ref(ref_channel: int, target_channel: int) -> TransformNode

Create a PAIRED_REF node.

PARAMETER	DESCRIPTION
ref_channel	Native channel index of the reference electrode. TYPE: int
target_channel	Native channel index of the channel to re-reference. TYPE: int

sink classmethod

sink(base_name: str, path: str, file_type: RadiensFileType) -> TransformNode

Create a SINK node.

PARAMETER	DESCRIPTION
base_name	Output base filename (without extension or directory). TYPE: str
path	Output directory path. TYPE: str
file_type	Output recording file format. TYPE: RadiensFileType

slice_channels classmethod

slice_channels(channels: list[int]) -> TransformNode

Create a SLICE_CHANNELS node.

PARAMETER	DESCRIPTION
channels	System channel indices (KeyIdxs.sys) to keep. TYPE: list[int]

slice_time classmethod

slice_time(start_sec: float, end_sec: float) -> TransformNode

Create a SLICE_TIME node.

PARAMETER	DESCRIPTION
start_sec	Start of the window, in seconds of stream time. TYPE: float
end_sec	End of the window, in seconds of stream time. TYPE: float

source classmethod

source(dataset: DatasetMetadata) -> TransformNode

Create a SOURCE node from a linked dataset.

PARAMETER	DESCRIPTION
dataset	Metadata for the input dataset (returned by link_data_file). TYPE: DatasetMetadata

virtual_ref classmethod

virtual_ref(ref_channel: int) -> TransformNode

Create a VIRTUAL_REF node.

PARAMETER	DESCRIPTION
ref_channel	Native channel index of the reference electrode. TYPE: int

TransformNodeType

Bases: IntEnum

Transform node type for curation protocol graphs.

TrsMode

Bases: IntEnum

Time range selection mode.

ATTRIBUTE	DESCRIPTION
SUBSET	[start, end) in seconds of stream time; an infinite edge is open.
TO_HEAD	From start to the newest data.
FROM_HEAD	The most recent start seconds.

VirtualRefParams

Bases: BaseModel

Parameters for virtual reference transform nodes.

ATTRIBUTE	DESCRIPTION
ref_channel	Native channel index of the reference electrode. TYPE: int

Attributes

ref_channel instance-attribute

ref_channel: int

Native channel index of the reference electrode.