radiens_core.models

Domain models — pure Pydantic v2, zero proto dependency.

All enums and models are importable from their domain-grouped submodules:

from radiens_core.models.stim import StimParams, StimShape
from radiens_core.models.signals import SignalType, SigSelect
from radiens_core.models.status import RecordMode, StreamMode

Classes

AnalogOutChannel

Bases: BaseModel

Configuration for a single analog output channel.

Attributes:

Name	Type	Description
pri_ntv_chan_idx	int	Primary native channel index.
analog_out_ntv_chan_idx	int	Analog output native channel index.
stream	int	Stream identifier.
stream_offset_idx	int	Index offset within the stream.

AnalogOutRegister

Bases: BaseModel

Complete DAC (Analog Output) register state.

Attributes:

Name	Type	Description
gain	int	DAC gain setting.
highpass_reg	DACHighPass	High-pass filter configuration. References DACHighPass.
channels	list[AnalogOutChannel]	List of individual analog output channel configurations. References AnalogOutChannel.

AreaUnits

Bases: IntEnum

Area measurement units for electrode sites.

BackboneMode

Bases: IntEnum

Hardware backbone mode. Values match proto allego.BackboneMode.

BackboneStatus

Bases: BaseModel

Complete system backbone status.

Attributes:

Name	Type	Description
streaming	StreamingStatus	Current streaming status.
recording	RecordingStatus	Current recording status.
ports	list[PortChannelCount]	List of port channel counts.
is_connected	bool	Whether the backbone is connected.
gpio_channel_count	GPIOChannelCount	GPIO channel count information.

BandParams

Bases: BaseModel

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

Attributes

high_frequency instance-attribute

high_frequency

Upper cutoff frequency in Hz.

low_frequency instance-attribute

low_frequency

Lower cutoff frequency in Hz.

order class-attribute instance-attribute

order = None

Filter order; None uses the server default.

BulkSinkParams

Bases: BaseModel

Parameters for BULK_SINK transform nodes.

Attributes

file_type instance-attribute

file_type

Output recording file format.

path instance-attribute

path

Output directory path.

suffix instance-attribute

suffix

Suffix appended to each output file's base name.

BulkSourceParams

Bases: BaseModel

Parameters for BULK_SOURCE transform nodes.

Attributes

sources instance-attribute

sources

One entry per input dataset.

CARParams

Bases: BaseModel

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

CableDelay

Bases: BaseModel

Cable delay configuration for a specific port.

Attributes:

Name	Type	Description
port	Port	The hardware port for which the cable delay is configured. References Port.
cable_delay	int	The cable delay value in units specific to the hardware.
is_auto	bool	Whether the cable delay is automatically determined by the system.

ChannelInfo

Bases: BaseModel

Complete channel information for a specific channel.

Identity and index fields are always present. Position fields (probe_x, probe_y, etc.) are None for non-amplifier channels; use has_position to guard access. site_position provides a structured SitePosition view built from the inline fields when position data is available.

Attributes:

Name	Type	Description
ntv_idx	int	Native channel index.
dset_idx	int	Dataset channel index.
sys_idx	int	System channel index.
signal_type	SignalType	Signal type of this channel.
name	str	User-facing display name (from chanName in the proto).
ntv_name	str	Hardware-native channel name (from ntvChanName in the proto).
is_selected	bool	Whether this channel is currently selected.
probe_id	str	Probe identifier for the sensor this channel belongs to.
headstage_id	str	Headstage identifier for this channel.
sensor_id	str	Sensor identifier for this channel.
probe_x	float | None	X-coordinate in probe coordinate system (µm). None for non-AMP.
probe_y	float | None	Y-coordinate in probe coordinate system (µm). None for non-AMP.
probe_z	float | None	Z-coordinate in probe coordinate system (µm). None for non-AMP.
tissue_x	float | None	X-coordinate in tissue coordinate system (µm). None for non-AMP.
tissue_y	float | None	Y-coordinate in tissue coordinate system (µm). None for non-AMP.
tissue_z	float | None	Z-coordinate in tissue coordinate system (µm). None for non-AMP.
site_shape	str	Geometric shape of the electrode site. Empty for non-AMP.
site_area_um2	float | None	Surface area in square micrometers. None for non-AMP.
site_lim_x_min	float | None	Bounding box min X (µm). None for non-AMP.
site_lim_x_max	float | None	Bounding box max X (µm). None for non-AMP.
site_lim_y_min	float | None	Bounding box min Y (µm). None for non-AMP.
site_lim_y_max	float | None	Bounding box max Y (µm). None for non-AMP.
site_lim_z_min	float | None	Bounding box min Z (µm). None for non-AMP.
site_lim_z_max	float | None	Bounding box max Z (µm). None for non-AMP.
scs_to_tcs_x	float | None	X-offset for probe-to-tissue transform. None for non-AMP.
scs_to_tcs_y	float | None	Y-offset for probe-to-tissue transform. None for non-AMP.
scs_to_tcs_z	float | None	Z-offset for probe-to-tissue transform. None for non-AMP.

Attributes

bounding_box_center property

bounding_box_center

Bounding box center in probe coordinate system (µm), or None for non-AMP.

bounding_box_size property

bounding_box_size

Site bounding box size (width, height, depth) in µm, or None for non-AMP.

has_position property

has_position

True if site position data is available (AMP channels only).

site_position property

site_position

Structured view of the inline position fields.

Returns a SitePosition built from this channel's inline fields, or None for non-AMP channels.

Functions

get_area

get_area(unit)

Get electrode site area in the requested units, or None for non-AMP channels.

Parameters:

Name	Type	Description	Default
unit	AreaUnits	Target area unit for conversion.	required

Returns:

Type	Description
float | None	Site area in the requested unit, or None if position data is unavailable.

ChannelMetadata

Bases: BaseModel

Channel metadata for a dataset.

Contains channel configuration, probe geometry, signal types, and indices for all channels.

Attributes:

Name	Type	Description
dataset_uid	str	Unique identifier for the dataset.
fs	float	Sampling frequency in Hertz.
source_label	str	Label for the data source.
neighbor_max_radius_um	float	Maximum radius for neighbor search in micrometers.
signal_units	dict[SignalType, SignalUnits]	Mapping of signal types to their units.
has_discrete	bool	Whether the dataset contains discrete signals.
has_continuous_amp	bool	Whether the dataset contains continuous amplifier signals.
sig_map	dict[SignalType, KeyIdxs]	Mapping of signal types to their indices.
selected_sig_map	dict[SignalType, KeyIdxs]	Mapping of signal types to their selected indices.
num_channels	dict[SignalType, int]	Total number of channels per signal type.
selected_num_channels	dict[SignalType, int]	Number of selected channels per signal type.
site_positions	list[SitePosition]	Site positions for amplifier channels (parallel to sig_map[AMP].ntv).
chan_names	dict[SignalType, list[str]]	Display names per channel, parallel to sig_map[st].ntv for each signal type.
ntv_chan_names	dict[SignalType, list[str]]	Hardware-native names per channel, parallel to sig_map[st].ntv.
probe_ids	dict[SignalType, list[str]]	Probe IDs per channel, parallel to sig_map[st].ntv.
headstage_ids	dict[SignalType, list[str]]	Headstage IDs per channel, parallel to sig_map[st].ntv.
sensor_ids	dict[SignalType, list[str]]	Sensor IDs per channel, parallel to sig_map[st].ntv.

Attributes

amp_site_count property

amp_site_count

Number of amplifier channel sites.

total_selected_channels property

total_selected_channels

Total number of selected channels across all signal types.

Functions

all_amp_indices

all_amp_indices()

Get all amplifier channel native indices.

get_channel_info

get_channel_info(ntv_idx, sig_type)

Get complete channel information from native index.

Parameters:

Name	Type	Description	Default
ntv_idx	int	Native channel index.	required
sig_type	SignalType	Signal type to look up.	required

Returns:

Type	Description
ChannelInfo	Complete channel information including indices, names, hardware IDs,
ChannelInfo	and site position (AMP channels only).

Raises:

Type	Description
DatasetError	If ntv_idx not found for the signal type.

get_num_channels

get_num_channels(sig_type)

Get total number of channels for a signal type.

index

index(sig_type)

Get channel indices for a signal type.

ntv_from_dset

ntv_from_dset(dset_idx, sig_type)

Convert dataset index to native index.

Parameters:

Name	Type	Description	Default
dset_idx	int	Dataset index.	required
sig_type	SignalType	Signal type.	required

Returns:

Type	Description
int	Native index for the channel.

Raises:

Type	Description
DatasetError	If dset_idx not found for the signal type.

ntv_from_sys

ntv_from_sys(sys_idx, sig_type)

Convert system index to native index.

Parameters:

Name	Type	Description	Default
sys_idx	int	System index.	required
sig_type	SignalType	Signal type.	required

Returns:

Type	Description
int	Native index for the channel.

Raises:

Type	Description
DatasetError	If sys_idx not found for the signal type.

selected_index

selected_index(sig_type)

Get selected channel indices for a signal type.

ChannelSpikeData

Bases: BaseModel

Spike timestamps and neuron labels for a single recording channel.

Attributes:

Name	Type	Description
ntv_chan_idx	int	Native channel index.
timestamps	NDArray[float64]	Spike timestamps in seconds, shape (N,).
labels	NDArray[int32]	Integer neuron label per spike, shape (N,). Matches the neuron label reported by get_neurons().
waveforms	NDArray[float32] | None	Spike waveforms in raw units, shape (N, waveform_n_points), or None if waveforms were not requested.

ClientType

Bases: StrEnum

Client type identifier.

CoreConfig

Bases: BaseModel

Core hardware configuration retrieved from the server.

Attributes:

Name	Type	Description
allego_core_server_port	str	The network port used by the Allego Core server.
base_samp_freq	float	Base sampling frequency in Hertz.
stream_loop_dur_ms	int	Stream loop duration in milliseconds.
backbone_mode	BackboneMode	Current hardware backbone mode. References BackboneMode.
has_xdaq_gpio_expander	bool	Whether the system is equipped with an XDAQ GPIO expander.
cable_delays	dict[int, CableDelay]	Mapping of port indices to their respective CableDelay configurations.

DACHighPass

Bases: BaseModel

DAC high-pass filter configuration.

Attributes:

Name	Type	Description
enable	bool	Whether the high-pass filter is enabled.
cutoff_freq	float	High-pass filter cutoff frequency in Hertz.

DIOMode

Bases: IntEnum

Digital Output mode. Values match proto allego.DIOMode.

DSPGroup

Bases: BaseModel

Group of DSP filter stages, organized by hardware/software layers.

Attributes:

Name	Type	Description
hardware	list[DSPParams]	List of hardware filter stages.
software_stage1	list[DSPParams]	List of software stage 1 filters.
software_stage2	list[DSPParams]	List of software stage 2 filters.
spike_sorter	list[DSPParams]	List of spike sorter filters.

DSPParams

Bases: BaseModel

Configuration parameters for a single DSP filter stage.

Attributes:

Name	Type	Description
type	DSPType	DSP filter type. References DSPType.
stage	FilterStage	DSP filter stage. References FilterStage.
freq	float | None	Filter frequency. Defaults to None.
freq_spec_band	FreqSpecBand | None	Frequency band specification. Defaults to None.
ref_ntv_chan_idx	int | None	Reference native channel index. Defaults to None.
notch_bandwidth	float | None	Notch filter bandwidth. Defaults to None.
user_label	str	User-defined label for the filter. Defaults to "".
port	Port | None	Port configuration. References Port. Defaults to None.
target_ntv_chan_idx	float | None	Target native channel index. Defaults to None.
is_aux	bool	Whether this is an auxiliary filter. Defaults to False.
aux_chan_idx	int | None	Auxiliary channel index. Defaults to None.
filter_order	int | None	Filter order. Defaults to None.
zero_phase	bool	Whether to use zero-phase filtering. Defaults to False.
force_sos	bool	Whether to force Second-Order Sections. Defaults to False.

DSPType

Bases: IntEnum

Digital Signal Processing filter type. Values match proto common.DSPType.

DashElement

Bases: IntEnum

Elements available for the spike sorter dashboard.

DataRecordingType

Bases: IntEnum

Data recording type. Values match proto allego.DataRecordingType.

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.

Attributes:

Name	Type	Description
id	str	Unique identifier for the dataset.
base_name	str	Base name of the dataset.
path	str	Full filesystem path to the dataset.
file_type	RadiensFileType	Type of the recording file. References RadiensFileType.
time_range	TimeRange	Valid time range for this dataset. References TimeRange.
channel_metadata	ChannelMetadata	Channel configuration and metadata. References ChannelMetadata.
parent_dsource_id	str	Identifier for the parent data source. Defaults to "".
probe_uid	str	Unique identifier for the probe used. Defaults to "".
associated_spikes_ids	list[str]	Registered spikes datasource IDs discovered when the recording file was linked (populated by link_data_file()). Empty if no .spikes file was found alongside the recording.

Attributes

base_path property

base_path

Full path to the dataset file (directory + base name).

duration property

duration

Dataset duration in seconds.

sampling_rate property

sampling_rate

Sampling rate in Hz.

DigitalOutChannelRegister

Bases: BaseModel

Register state for a single digital output channel.

Attributes:

Name	Type	Description
manual_state	bool	Manual state of the digital output channel.
event_threshold	float	Event threshold in microvolts.
event_polarity	bool	Event polarity of the channel.
ntv_chan_idx	int	Native channel index.
pulse_interval_sec	float	Pulse interval in seconds.
pulse_duration_sec	float	Pulse duration in seconds.

DigitalOutRegister

Bases: BaseModel

Complete DIO (Digital Output) register state.

Attributes:

Name	Type	Description
mode	DIOMode	Digital output mode. References DIOMode.
dout_chan_registers	list[DigitalOutChannelRegister]	List of digital output channel registers.
gated_polarity	bool	Gated polarity of the register.
req_pulse_interval_sec	float	Requested pulse interval in seconds.
req_pulse_duration_sec	float	Requested pulse duration in seconds.
req_pulse_ntv_chan_idx	int	Requested pulse native channel index.

DownsampleParams

Bases: BaseModel

Parameters for downsample transform nodes.

Attributes

factor instance-attribute

factor

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

FilterStage

Bases: IntEnum

Digital Signal Processing filter stage. Values match proto common.FilterStage.

GPIOChannelCount

Bases: BaseModel

GPIO channel count information.

Attributes:

Name	Type	Description
n_aux	int	Number of auxiliary channels.
n_din	int	Number of digital input channels.
n_dout	int	Number of digital output channels.

HighLowPassParams

Bases: BaseModel

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

Attributes

frequency instance-attribute

frequency

Cutoff frequency in Hz.

order class-attribute instance-attribute

order = None

Filter order; None uses the server default.

InputFeatureType

Bases: IntEnum

Feature types used for spike sorting.

KeyIdxs

Bases: BaseModel

Channel indices in all three key index spaces.

Attributes:

Name	Type	Description
ntv	list[int]	Native channel indices.
dset	list[int]	Dataset channel indices.
sys	list[int]	System channel indices.

KeyIndex

Bases: IntEnum

Channel key index type.

NTV: native position in DAQ stream per signal type (starts at 0). DATA: position in backing dataset per signal type. SYS: global position across all signal types.

KpiMetric

Bases: IntEnum

KPI metric identifier. Values match proto common.KpiMetricsEnum.

KpiMetricId

Bases: BaseModel

Identifies a single KPI metric (mode + name pair).

mode The computation mode (BASE, AVG, or STREAM). name The metric to compute.

KpiMetricsResult

Bases: BaseModel

Result of a KPI metrics query.

values is a 2-D numpy array of shape (n_channels, n_metrics) where rows correspond to channel_indices and columns to metrics.

channel_indices Native channel indices (ntvIdxs) in row order. metrics KPI metric IDs in column order. signal_type Signal type for all channels in this result. values Metric values: shape (n_channels, n_metrics). time_range Time range over which these metrics were computed.

KpiMode

Bases: IntEnum

KPI computation mode. Values match proto common.KpiMetricsMode.

KpiStatus

Bases: BaseModel

Status of the KPI computation cache.

stream_group_id Stream group or datasource ID this status belongs to. num_packets_memory Number of KPI packets held in memory. packet_dur Duration of each KPI packet in seconds. update_period How often the KPI cache is updated, in seconds. persistence Exponential averaging persistence factor. beta Beta parameter for the averaging filter. is_tracking_signal_cache Whether the KPI cache is currently tracking the live signal cache. num_packets Total number of packets processed. memory_bytes Approximate memory used by the KPI cache in bytes. num_sigs Number of signals being tracked (None if not yet active). time_range Time range covered by the current KPI cache (None if not yet active).

ManualStimTriggerRequest

Bases: BaseModel

Request for manual stimulation trigger.

Attributes:

Name	Type	Description
trigger	StimKeypressIndex	Keypress trigger (1-8). References StimKeypressIndex.
trigger_on	bool	Whether to turn the trigger on or off.

ManualStimTriggerToggleRequest

Bases: BaseModel

Request to toggle manual stimulation trigger.

Attributes:

Name	Type	Description
trigger	StimKeypressIndex	Keypress trigger (1-8). References StimKeypressIndex.

NeuronInfo

Bases: BaseModel

Descriptive statistics for a single sorted neuron.

Attributes:

Name	Type	Description
neuron_id	str	Unique neuron identifier string.
site_ntv_chan_idx	int	Native channel index of the primary recording site.
spike_label	str	Neuron label as a string (e.g. "1", "2").
spike_count	int	Total number of spikes detected.
spike_rate	float	Mean spike rate in Hz.
mean_abs_peak_wfm	float	Mean absolute peak waveform amplitude.
snr	float	Signal-to-noise ratio.
pos_probe	list[float]	Probe coordinate [x, y, z] in microns.
pos_tissue	list[float]	Tissue coordinate [x, y, z] in microns.

NeuronSpikeData

Bases: BaseModel

Spike timestamps for a single sorted neuron.

Attributes:

Name	Type	Description
label	int	Integer neuron label. Correlates with NeuronInfo.spike_label (string) from get_neurons().
ntv_chan_idx	int	Native channel index of the primary recording site for this neuron. -1 if the channel could not be determined from the spike spec.
timestamps	NDArray[float64]	Spike timestamps in seconds, shape (N,).
waveforms	NDArray[float32] | None	Spike waveforms in raw units, shape (N, waveform_n_points), or None if waveforms were not requested.

NeuronsResult

Bases: BaseModel

Neuron descriptors organized by recording channel.

Attributes:

Name	Type	Description
neurons_by_channel	dict[int, list[NeuronInfo]]	Map from native channel index to a list of neuron descriptors detected on that channel.

NotchParams

Bases: BaseModel

Parameters for notch filter transform nodes.

Note

The notch filter is always second-order (scipy.signal.iirnotch). Unlike other IIR filters, it does not accept a custom order.

Attributes

bandwidth instance-attribute

bandwidth

Width of the rejection band in Hz.

notch_frequency instance-attribute

notch_frequency

Center frequency to reject in Hz.

PairedRefParams

Bases: BaseModel

Parameters for paired reference transform nodes.

Attributes

ref_channel instance-attribute

ref_channel

Native channel index of the reference electrode.

target_channel instance-attribute

target_channel

Native channel index of the channel to re-reference.

Port

Bases: IntEnum

Hardware port identifier. Values match proto common.Port.

PortChannelCount

Bases: BaseModel

Port channel count information.

Attributes:

Name	Type	Description
port	Port	Hardware port identifier. References Port.
channel_count	int	Number of channels on the port.

RadiensFileType

Bases: IntEnum

Recording file type. Values match proto common.RadixFileTypes.

RecordMode

Bases: IntEnum

Data recording mode. Values match proto allego.RecordMode.

RecordStateRequest

Bases: BaseModel

Request to change recording state.

Attributes:

Name	Type	Description
mode	RecordMode	Target recording mode. References RecordMode.
port	Port | None	Optional port to control. References Port. Defaults to None.

RecordingConfig

Bases: BaseModel

Recording configuration settings.

Configures output file paths, naming, and recording behavior. Used as both request (for set_recording_config) and response (for get_recording_config).

Attributes:

Name	Type	Description
base_file_name	str	Base filename for recording output (without extension or timestamp).
base_file_path	str	Base directory path for recording files.
datasource_idx	int	Index number for the composed file name. Defaults to 0.
time_stamp	bool	True to include timestamp in the composed file name. Defaults to True.
split_files_by_port	bool	True to create separate files for each port. Defaults to False.
force_start_at_tstamp_0	bool	True to force recording to start at timestamp 0. Defaults to False.
recording_type	DataRecordingType	Type of data to record. References DataRecordingType. Defaults to DataRecordingType.CONTINUOUS.

RecordingStatus

Bases: BaseModel

Current recording status.

Attributes:

Name	Type	Description
record_mode	RecordMode	System-level recording mode. References RecordMode.
active_filename	str	Name of the file currently being recorded.
duration	float	Current recording duration in seconds.
error	str	Current recording error message, if any.
record_mode_port_a	RecordMode | None	Recording mode for Port A. References RecordMode. Defaults to None.
record_mode_port_b	RecordMode | None	Recording mode for Port B. References RecordMode. Defaults to None.
record_mode_port_c	RecordMode | None	Recording mode for Port C. References RecordMode. Defaults to None.
record_mode_port_d	RecordMode | None	Recording mode for Port D. References RecordMode. Defaults to None.
record_mode_port_e	RecordMode | None	Recording mode for Port E. References RecordMode. Defaults to None.
record_mode_port_f	RecordMode | None	Recording mode for Port F. References RecordMode. Defaults to None.
record_mode_port_g	RecordMode | None	Recording mode for Port G. References RecordMode. Defaults to None.
record_mode_port_h	RecordMode | None	Recording mode for Port H. References RecordMode. Defaults to None.

RestartRequest

Bases: BaseModel

Request to restart the system with a specific backbone mode.

Attributes:

Name	Type	Description
mode	BackboneMode	Target hardware backbone mode. References BackboneMode.

ServiceEndpoint

Bases: StrEnum

gRPC service endpoint identifier.

Mirrors the proto GrpcServiceType enum values used as keys in the ServerSpec.service map returned by GetRadiensServers.

SetCoreConfigRequest

Bases: BaseModel

Request to update core hardware configuration.

Attributes:

Name	Type	Description
samp_freq	float | None	Target sampling frequency in Hertz. Defaults to None.
loop_dur	float | None	Target loop duration in milliseconds. Defaults to None.
pcache_persistence	float | None	PCache persistence duration. Defaults to None.
cable_delay	CableDelay | None	Specific cable delay configuration to set. References CableDelay. Defaults to None.

SetTriggerStateRequest

Bases: BaseModel

Request to set trigger channel state.

Attributes:

Name	Type	Description
channel	TriggerChannel	Trigger channel identifier. References TriggerChannel.
enabled	bool	Whether the channel should be enabled.
port	Port	Hardware port identifier. References Port.

SigSelect

Bases: BaseModel

Signal selection specifying channels per signal type.

Attributes:

Name	Type	Description
amp	NDArray[int64]	Array of native channel indices for amplifier signals.
gpio_ain	NDArray[int64]	Array of native channel indices for analog input signals.
gpio_din	NDArray[int64]	Array of native channel indices for digital input signals.
gpio_dout	NDArray[int64]	Array of native channel indices for digital output signals.
key_idx	KeyIndex	Channel key index type. References KeyIndex.

SignalArrays

Bases: BaseModel

Container for signal data arrays, one per signal type.

Attributes:

Name	Type	Description
amp	NDArray[float64] | None	2D array (channels, samples) for amplifier data. Defaults to None.
gpio_ain	NDArray[float64] | None	2D array (channels, samples) for analog input data. Defaults to None.
gpio_din	NDArray[float64] | None	2D array (channels, samples) for digital input data. Defaults to None.
gpio_dout	NDArray[float64] | None	2D array (channels, samples) for digital output data. Defaults to None.

SignalSpec

Bases: BaseModel

Semantic signal selection specification.

Use factory methods for clean channel selection:

spec = SignalSpec.amp([0, 1, 2, 3]) spec = SignalSpec.ain("all") spec = SignalSpec.multi(amp=[0, 1], din="all")

Attributes:

Name	Type	Description
sig_type	SignalType | None	Primary signal type. References SignalType.
channels	tuple[int, ...] | str	Tuple of channel indices or selection string ("all", "selected").
multi_select	dict[SignalType, tuple[int, ...] | str] | None	Map of signal types to channel selections. Defaults to None.

Functions

ain classmethod

ain(channels='all')

Select analog input channels.

all_amp classmethod

all_amp()

Convenience: all amplifier channels.

amp classmethod

amp(channels='all')

Select amplifier channels.

din classmethod

din(channels='all')

Select digital input channels.

dout classmethod

dout(channels='all')

Select digital output channels.

is_multi

is_multi()

Check if this is a multi-type specification.

multi classmethod

multi(amp=None, ain=None, din=None, dout=None)

Select channels from multiple signal types.

to_sig_select

to_sig_select(channel_metadata)

Convert to SigSelect for API calls.

SignalType

Bases: IntEnum

Signal type. Values match proto common.SignalType.

SignalUnits

Bases: IntEnum

Signal measurement units.

SinapsStatusRegisters

Bases: BaseModel

Status registers for a Sinaps probe.

Attributes:

Name	Type	Description
calibration_state	bool	True if the probe is currently calibrating.
calibration_progress	float	Calibration progress (0.0 to 1.0).
num_active_pixels_shank0	int	Number of active pixels on shank 0.
num_active_pixels_shank1	int	Number of active pixels on shank 1.
num_active_pixels_shank2	int	Number of active pixels on shank 2.
num_active_pixels_shank3	int	Number of active pixels on shank 3.
v_ref_ffa	float	Reference voltage FFA.
v_ref_ffb	float	Reference voltage FFB.
v_ref_ffc	float	Reference voltage FFC.
v_ref_ffd	float	Reference voltage FFD.
is_error0	bool	True if there is an error on shank 0.
is_error1	bool	True if there is an error on shank 1.
is_error2	bool	True if there is an error on shank 2.
is_error3	bool	True if there is an error on shank 3.
host_counter	int	Host-side packet counter.
fpga_counter	int	FPGA-side packet counter.
firmware_version	str	Probe firmware version string.
probe_generation	int	Probe hardware generation number.
probe_model	int	Probe model number.

SinkParams

Bases: BaseModel

Parameters for SINK transform nodes.

Attributes

base_name instance-attribute

base_name

Output base filename (without extension or directory).

file_type instance-attribute

file_type

Output recording file format.

path instance-attribute

path

Output directory path.

SitePosition

Bases: BaseModel

Electrode site position and geometry in probe and tissue coordinates.

Attributes:

Name	Type	Description
probe_x	float	X-coordinate in probe coordinate system.
probe_y	float	Y-coordinate in probe coordinate system.
probe_z	float	Z-coordinate in probe coordinate system.
tissue_x	float	X-coordinate in tissue coordinate system.
tissue_y	float	Y-coordinate in tissue coordinate system.
tissue_z	float	Z-coordinate in tissue coordinate system.
site_shape	str	Geometric shape of the electrode site.
site_area_um2	float	Surface area of the electrode site in square micrometers.
site_lim_x_min	float	Minimum X-limit of the site bounding box.
site_lim_x_max	float	Maximum X-limit of the site bounding box.
site_lim_y_min	float	Minimum Y-limit of the site bounding box.
site_lim_y_max	float	Maximum Y-limit of the site bounding box.
site_lim_z_min	float	Minimum Z-limit of the site bounding box.
site_lim_z_max	float	Maximum Z-limit of the site bounding box.
scs_to_tcs_x	float	X-offset for probe to tissue coordinate transformation.
scs_to_tcs_y	float	Y-offset for probe to tissue coordinate transformation.
scs_to_tcs_z	float	Z-offset for probe to tissue coordinate transformation.

Attributes

bounding_box_center property

bounding_box_center

Site bounding box center coordinates in probe coordinate system.

bounding_box_size property

bounding_box_size

Site bounding box size (width, height, depth) in micrometers.

Functions

get_area

get_area(unit)

Get site area in the specified units.

Parameters:

Name	Type	Description	Default
unit	AreaUnits	Target area unit for conversion	required

Returns:

Type	Description
float	Site area converted to the specified unit

SliceChannelsParams

Bases: BaseModel

Parameters for channel-slice transform nodes.

Attributes

channels instance-attribute

channels

System-wide channel indices to keep.

SliceTimeParams

Bases: BaseModel

Parameters for time-slice transform nodes.

Attributes

end_sec instance-attribute

end_sec

End of the time window in seconds.

start_sec instance-attribute

start_sec

Start of the time window in seconds.

SourceParams

Bases: BaseModel

Parameters for SOURCE transform nodes.

Attributes

base_name instance-attribute

base_name

Base filename (without extension or directory).

dataset_id class-attribute instance-attribute

dataset_id = ''

ID of the linked dataset (empty for new sources).

file_type instance-attribute

file_type

Recording file format.

path instance-attribute

path

Directory path containing the dataset.

SpikeDetectParams

Bases: BaseModel

Detection parameters for a single recording channel.

All fields are optional to allow for partial updates.

Attributes:

Name	Type	Description
is_enabled	bool | None	Whether detection is enabled on this channel.
ntv_chan_idx	int | None	Native channel index (used in return structures, not set via bulk update).
thr	list[float] | None	Threshold values in microvolts [neg, pos].
thr_sd	list[float] | None	Threshold values in standard deviations [neg, pos].
thr_wdw_pts	list[int] | None	Threshold window in points [pre, post, total].
thr_wdw	list[float] | None	Threshold window in seconds [pre, post, total].
shadow	float | None	Shadow period in seconds.
shadow_pts	int | None	Shadow period in points.
is_set_thr	list[bool] | None	Whether threshold is set [neg, pos].
weak_thr	list[float] | None	Weak threshold values in microvolts [neg, pos].
weak_thr_sd	list[float] | None	Weak threshold values in standard deviations [neg, pos].

SpikeSorterClustererParams

Bases: BaseModel

Parameters for the spike clustering algorithm.

Attributes:

Name	Type	Description
pos_influence_frac	float | None	Influence of spike position on clustering.
wfm_shape_influence_frac	float | None	Influence of waveform shape on clustering.
eps	float | None	Epsilon parameter for DBSCAN-like clustering.
min_pts	int | None	Minimum points for a cluster.
disabled	bool	Whether clustering is disabled.

SpikeSorterCommand

Bases: IntEnum

Commands for controlling an active spike sorter.

SpikeSorterCriterionLevel

Bases: IntEnum

Stringency levels for AI evaluation.

SpikeSorterDashboard

Bases: BaseModel

Comprehensive spike sorter dashboard data.

Attributes:

Name	Type	Description
enabled_ports	list[Port]	List of hardware ports with active sorting.
general	SpikeSorterDashboardGeneral | None	General summary metrics.

SpikeSorterDashboardGeneral

Bases: BaseModel

General summary metrics for the spike sorter dashboard.

SpikeSorterDynamicConfig

Bases: BaseModel

Configuration for AI dynamic tracking auto-updates.

Attributes:

Name	Type	Description
is_enabled	bool | None	Whether dynamic AI tracking is enabled.
update_period_sec	SpikeSorterDynamicUpdatePeriod | None	Schedule for dynamic updates.
criteria	SpikeSorterDynamicCriteria | None	Stringency criteria for updates.

SpikeSorterDynamicCriteria

Bases: BaseModel

Criteria stringency levels for AI auto-updates.

SpikeSorterDynamicUpdatePeriod

Bases: BaseModel

Update periods in seconds for AI auto-updates.

SpikeSorterFeatureParams

Bases: BaseModel

Parameters for feature extraction during spike sorting.

Attributes:

Name	Type	Description
num_features	int	Number of features to extract.
feature_type	InputFeatureType	Type of features to extract.
latent_dim	int | None	Latent dimension for feature reduction.
resample_wfm_len	int | None	Length to resample waveforms to.

SpikeSorterLaunchParams

Bases: BaseModel

Parameters for launching a new spike sorter.

Attributes:

Name	Type	Description
dsource_id	str | None	ID of the data source to sort (required for file sorting).
discover_noise	bool	Whether to perform noise discovery.
is_auto_on	bool	Whether to automatically start sorting after launch.
nbr_pattern	int | None	Neighbor pattern for multi-channel sorting.
sink_dsrc_id	str | None	ID for the resultant .spikes file.
sub_cmd	SpikeSorterSubCommand	Sub-command for the sorting operation.
clusterer_params	SpikeSorterClustererParams | None	Optional clustering parameters.
feature_params	SpikeSorterFeatureParams | None	Optional feature extraction parameters.

SpikeSorterLaunchResult

Bases: BaseModel

Result of a spike sorter launch request.

Attributes:

Name	Type	Description
spike_sorter_id	str	Unique ID of the launched sorter.
sorter_type	SpikeSorterType	Type of the launched sorter.
msg	str	Status message from the server.

SpikeSorterParamCommand

Bases: IntEnum

Commands for updating individual spike sorter detection parameters.

SpikeSorterState

Bases: BaseModel

Current state and progress of a spike sorter.

Attributes:

Name	Type	Description
sys	SpikeSorterStateSystem	Overall system state (ON, OFF, NOT_CONFIGURED).
frac_complete	float	Fraction of the current operation completed (0.0 to 1.0).
is_on	bool	Whether the sorter is currently active.
msg	str	Status message from the server.
error_msg	str	Error message if the sorter is in an error state.
warn_msg	str	Warning message from the server.

SpikeSorterStateSystem

Bases: IntEnum

Overall system state of a spike sorter.

SpikeSorterSubCommand

Bases: IntEnum

Sub-commands for spike sorter operations.

SpikeSorterType

Bases: IntEnum

Supported spike sorter types.

SpikesSpec

Bases: BaseModel

Spike interface metadata for a linked dataset.

Attributes:

Name	Type	Description
biointerface_id	str	Unique identifier for the spike interface; used as spikeSorterID in RPC calls that require it.
dataset_uid	str	Dataset UID this spike interface is associated with.
num_neurons	int	Total number of sorted neurons across all channels.
num_sites	int	Number of recording sites (channels) with spike data.
enabled_channel_indices	list[int]	Native channel indices of enabled recording sites, sorted in ascending order.
time_range	tuple[float, float]	Full time range of the recording in seconds (start, end).
spike_time_range	tuple[float, float]	Time range over which spike data is available in seconds (start, end).

StimParams

Bases: BaseModel

Stimulation parameters for a single channel.

All timing values are in microseconds (μs). Current amplitudes are in μA for amplifier channels and V for DAC channels.

Attributes:

Name	Type	Description
stim_sys_chan_idx	int	System channel index (ntvAbsKeyIdx).
stim_shape	StimShape	Stimulation waveform shape. References StimShape. Defaults to StimShape.BIPHASIC.
stim_polarity	StimPolarity	Stimulation polarity. References StimPolarity. Defaults to StimPolarity.CATHODIC_FIRST.
first_phase_duration	float	Duration of the first phase in μs. Defaults to 100.0.
second_phase_duration	float	Duration of the second phase in μs. Defaults to 100.0.
interphase_delay	float	Delay between phases in μs. Defaults to 0.0.
first_phase_amplitude	float	Amplitude of the first phase (μA for amp, V for DAC). Defaults to 0.1.
second_phase_amplitude	float	Amplitude of the second phase (μA for amp, V for DAC). Defaults to 0.0.
baseline_voltage	float	Baseline voltage in V. Defaults to 0.0.
trigger_edge_or_level	StimTriggerEdgeOrLevel	Trigger mode. References StimTriggerEdgeOrLevel. Defaults to StimTriggerEdgeOrLevel.EDGE.
trigger_high_or_low	StimTriggerHighOrLow	Trigger polarity. References StimTriggerHighOrLow. Defaults to StimTriggerHighOrLow.HIGH.
enabled	bool	Whether stimulation is enabled for this channel. Defaults to True.
post_trigger_delay	float	Delay after trigger before stimulation in μs. Defaults to 0.0.
pulse_or_train	StimPulseMode	Pulse or train mode. References StimPulseMode. Defaults to StimPulseMode.SINGLE_PULSE.
number_of_stim_pulses	int	Number of pulses in a train. Defaults to 1.
pulse_train_period	float	Period of pulses in a train in μs. Defaults to 0.0.
refractory_period	float	Refractory period in μs. Defaults to 0.0.
pre_stim_amp_settle	float	Pre-stimulation amplifier settle time in μs. Defaults to 0.0.
post_stim_amp_settle	float	Post-stimulation amplifier settle time in μs. Defaults to 0.0.
maintain_amp_settle	bool	Whether to maintain amplifier settle. Defaults to False.
enable_amp_settle	bool	Whether to enable amplifier settle. Defaults to False.
headstage_global_amp_settle	bool	Whether to enable global headstage amp settle. Defaults to False.
post_stim_charge_recov_on	float	Post-stimulation charge recovery on time in μs. Defaults to 0.0.
post_stim_charge_recov_off	float	Post-stimulation charge recovery off time in μs. Defaults to 0.0.
enable_charge_recovery	bool	Whether to enable charge recovery. Defaults to False.
trigger_source_is_keypress	bool	Whether the trigger source is a keypress. Defaults to False.
trigger_source_idx	int | StimKeypressIndex	AIN/DIN system channel index, or keypress number. References StimKeypressIndex if keypress.

Functions

biphasic classmethod

biphasic(
    *,
    amplitude,
    pulse_duration,
    polarity,
    stim_sys_chan_idx,
    enabled=True,
    **overrides,
)

Create biphasic stimulation parameters.

Parameters:

Name	Type	Description	Default
amplitude	float	First phase amplitude (μA for amp channels)	required
pulse_duration	float	Phase duration in microseconds	required
polarity	StimPolarity	Stimulation polarity (cathodic or anodic first)	required
stim_sys_chan_idx	int	System channel index	required
**overrides	object	Override any other StimParams field	{}

Returns:

Type	Description
StimParams	StimParams configured for biphasic stimulation

StimPolarity

Bases: IntEnum

Stimulation polarity. Values match proto allego.StimPolarity.

StimPulseMode

Bases: IntEnum

Stimulation pulse mode. Values match proto allego.StimPulseOrTrain.

StimShape

Bases: IntEnum

Stimulation waveform shape. Values match proto allego.StimShape.

StimStep

Bases: IntEnum

Stimulation step size. Values match proto allego.StimStep.

StimStepRequest

Bases: BaseModel

Request to set stimulation step size.

Attributes:

Name	Type	Description
stim_step	StimStep	Target stimulation step size. References StimStep.

StimStepState

Bases: BaseModel

Current stimulation step size setting.

Attributes:

Name	Type	Description
stim_step	StimStep	Current stimulation step size. References StimStep.

StimTriggerEdgeOrLevel

Bases: IntEnum

Stimulation trigger edge/level mode. Values match proto allego.StimTriggerEdgeOrLevel.

StimTriggerHighOrLow

Bases: IntEnum

Stimulation trigger high/low. Values match proto allego.StimTriggerHighOrLow.

StreamMode

Bases: IntEnum

Data stream mode. Values match proto allego.StreamMode.

StreamStateRequest

Bases: BaseModel

Request to change streaming state.

Attributes:

Name	Type	Description
mode	StreamMode	Target streaming mode. References StreamMode.

StreamingStatus

Bases: BaseModel

Current streaming status.

Attributes:

Name	Type	Description
stream_mode	StreamMode	Current streaming mode. References StreamMode.
primary_cache_t_range	list[float]	Time range of data in the primary cache.
hardware_memory_level	float	Hardware memory fill level (0.0 to 1.0).

TimeRange

Bases: BaseModel

A resolved, concrete time range.

All fields are populated after resolution from a TimeRangeSpec against dataset metadata or cache state.

sec : tuple[float, float] Start and end times in seconds (start, end). timestamp : tuple[int, int] Start and end times in samples (start_sample, end_sample). fs : float Sampling rate in Hz. dur_sec : float Duration in seconds. walltime_str : str Wall-clock time string (always UTC from backend). n : int Number of samples.

Attributes

walltime property

walltime

Parse walltime string to UTC-aware datetime.

The backend always provides walltime in UTC. This property returns a timezone-aware datetime with UTC timezone.

TimeRangeSpec

Bases: BaseModel

Semantic time range specification with embedded mode.

Use factory methods to create specs with clear semantics:

spec = TimeRangeSpec.subset(0, 10) # [0, 10) seconds spec = TimeRangeSpec.lookback(5.0) # Last 5 seconds spec = TimeRangeSpec.full() # Entire recording

Attributes:

Name	Type	Description
mode	TrsMode	Time range selection mode. References TrsMode.
start	float	Start time or duration depending on the mode.
end	float | None	End time for subset mode. Defaults to None.

Attributes

duration property

duration

Duration in seconds, if known.

Functions

from_list classmethod

from_list(time_range, mode=None)

Create from [start, end] or [duration, nan] list.

full classmethod

full()

Full dataset/cache range.

is_full

is_full()

Check if this is a full-range specification.

lookback classmethod

lookback(duration)

Last duration seconds from head of cache.

resolve

resolve(dataset_metadata=None, fs=None)

Resolve to a concrete TimeRange.

dataset_metadata Dataset metadata used to obtain fs and dataset bounds. fs Sampling rate override (used when dataset_metadata is not provided).

TimeRange or None None for FROM_HEAD mode — caller must use to_array() instead.

subset classmethod

subset(start, end)

Absolute time range [start, end) seconds.

to_array

to_array()

Convert to [start, end] or [duration, nan] array.

to_head classmethod

to_head(start)

From start seconds to current head.

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.

Attributes

id class-attribute instance-attribute

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

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

source instance-attribute

source

ID of the source transform node.

target instance-attribute

target

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 CurateClient.set_protocol().

Notes

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()).

Attributes

id class-attribute instance-attribute

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

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

params class-attribute instance-attribute

params = None

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

type instance-attribute

type

Transform operation this node performs.

Functions

bandpass classmethod

bandpass(low_frequency, high_frequency, order=None)

Create a BANDPASS_FILTER node.

low_frequency: Lower cutoff frequency in Hz. high_frequency: Upper cutoff frequency in Hz. order: Filter order; None uses the server default.

bandstop classmethod

bandstop(low_frequency, high_frequency, order=None)

Create a BANDSTOP_FILTER node.

low_frequency: Lower cutoff frequency in Hz. high_frequency: Upper cutoff frequency in Hz. order: Filter order; None uses the server default.

bulk_sink classmethod

bulk_sink(suffix, path, file_type)

Create a BULK_SINK node.

suffix: Suffix appended to each output file's base name. path: Output directory path. file_type: Output recording file format.

bulk_source classmethod

bulk_source(datasets)

Create a BULK_SOURCE node from multiple linked datasets.

datasets: Metadata for all input datasets.

car classmethod

car()

Create a CAR_REF (Common Average Reference) node.

downsample classmethod

downsample(factor)

Create a DOWNSAMPLE node.

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

highpass classmethod

highpass(frequency, order=None)

Create a HIGHPASS_FILTER node.

frequency: Cutoff frequency in Hz. order: Filter order; None uses the server default.

lowpass classmethod

lowpass(frequency, order=None)

Create a LOWPASS_FILTER node.

frequency: Cutoff frequency in Hz. order: Filter order; None uses the server default.

notch classmethod

notch(notch_frequency, bandwidth)

Create a NOTCH_FILTER node.

The notch filter is always second-order (scipy.signal.iirnotch). Unlike other IIR filters, it does not accept a custom order.

notch_frequency: Center frequency to reject in Hz. bandwidth: Width of the rejection band in Hz.

paired_ref classmethod

paired_ref(ref_channel, target_channel)

Create a PAIRED_REF node.

ref_channel: Native channel index of the reference electrode. target_channel: Native channel index of the channel to re-reference.

sink classmethod

sink(base_name, path, file_type)

Create a SINK node.

base_name: Output base filename (without extension or directory). path: Output directory path. file_type: Output recording file format.

slice_channels classmethod

slice_channels(channels)

Create a SLICE_CHANNELS node.

channels: System-wide channel indices to keep.

slice_time classmethod

slice_time(start_sec, end_sec)

Create a SLICE_TIME node.

start_sec: Start of the time window in seconds. end_sec: End of the time window in seconds.

source classmethod

source(dataset)

Create a SOURCE node from a linked dataset.

dataset: Metadata for the input dataset (returned by link_data_file).

virtual_ref classmethod

virtual_ref(ref_channel)

Create a VIRTUAL_REF node.

ref_channel: Native channel index of the reference electrode.

TransformNodeType

Bases: IntEnum

Transform node type for curation protocol graphs.

Values match proto common.TransformNodeType.

TriggerChannel

Bases: IntEnum

Trigger channel identifier. Values match proto allego.TriggerChannel.

TriggerState

Bases: BaseModel

Current trigger channel configuration.

Attributes:

Name	Type	Description
enabled_channels	list[TriggerChannel]	List of currently enabled trigger channels.
ports	list[Port]	List of ports with enabled triggers.

TrsMode

Bases: IntEnum

Time range selection mode. Values match proto common.TimeRangeSelMode.

VirtualRefParams

Bases: BaseModel

Parameters for virtual reference transform nodes.

Attributes

ref_channel instance-attribute

ref_channel

Native channel index of the reference electrode.