RadiensPy Python API

Overview#

RadiensPy is the official Python API for the Radiens Clarity platform, providing programmatic access to all platform functionality. Designed for researchers who prefer code-driven workflows, RadiensPy enables automation of repetitive tasks, custom pipeline development, integration with external tools, and reproducible analysis through executable scripts. The dual-mode design ensures identical outputs whether using GUI or API.

Core Philosophy#

GUI ↔ API Parity#

Every operation available in Allego, Videre, and Curate has an equivalent Python API call that produces identical results.

Parity Benefits:

• GUI exploration transitions seamlessly to scripted workflows
• Visual results can be reproduced programmatically
• Parameters from GUI can be exported as Python code
• API results can be visualized in GUI tools
• No feature compromise between interaction modes

Pythonic Design#

Idiomatic Python patterns for intuitive API usage by the scientific Python community.

Design Principles:

• Clean, readable syntax following PEP 8 guidelines
• Comprehensive type hints for IDE autocomplete and validation
• Chainable methods for workflow fluency
• Context managers for resource management
• Generator patterns for memory-efficient data streaming
• Descriptive exceptions with actionable error messages

Key Advantages#

1. Instant Installation#

Available through standard Python package managers—install in seconds with pip install radienspy or conda install -c neuronexus radienspy. No complex dependencies, no compilation required, no system-level configuration. Compatible with Python 3.8-3.14 across Windows, macOS, and Linux. Start writing analysis code within minutes of deciding to use Radiens.

2. Seamless Jupyter Integration#

Optimized for interactive notebook workflows with automatic notebook mode detection, inline plotting, interactive widgets for data exploration, and progress bars designed for cell output. Export GUI workflows as executable notebook cells, or prototype in Jupyter and deploy to production pipelines—identical results in both environments.

3. Complete API Coverage#

Every feature in Allego, Videre, and Curate has an equivalent Python API call. GUI ↔ API parity ensures no functionality is GUI-exclusive or requires manual intervention. Fully automated pipelines are possible for all workflows—from acquisition triggering to final FAIR-compliant dataset publication.

4. Pythonic Design and Type Safety#

Idiomatic Python following PEP 8 guidelines with comprehensive type hints for IDE autocomplete and static analysis. Descriptive docstrings with examples for every function. Chainable methods for readable workflow fluency. Designed by Python developers for Python developers—not a wrapper around a non-Python tool.

5. Memory-Efficient Processing#

Lazy loading and streaming patterns handle multi-gigabyte neural datasets without exhausting RAM. Memory-mapped file access, chunked processing iterators, and out-of-core computation with Dask support. Process datasets larger than available memory without specialized infrastructure—laptop or HPC cluster, same code.

6. Rich Ecosystem Integration#

Seamless interoperability with SpikeInterface, Neo, Elephant, and the broader scientific Python stack (NumPy, SciPy, scikit-learn, PyTorch). Convert between data formats without loss. Use any community tool alongside RadiensPy—not a walled garden. Contribute to and benefit from the open neuroscience ecosystem.

Installation and Setup#

Package Management#

Available through standard Python package managers.

Installation Methods:

# Via pip
pip install radienspy

# Via conda
conda install -c neuronexus radienspy

# From source (development)
git clone https://github.com/neuronexus/radienspy.git
cd radienspy
pip install -e .

Dependencies:

• numpy >= 1.20.0
• scipy >= 1.7.0
• pandas >= 1.3.0
• h5py >= 3.0.0
• pynwb >= 2.0.0
• matplotlib >= 3.4.0
• scikit-learn >= 1.0.0 (optional, for ML features)

Environment Configuration#

API Credentials:

import radienspy as rp

# Connect to Radiens platform
rp.connect(
    host='localhost',  # or remote server
    port=8080,
    api_key='your_api_key'
)

# Verify connection
print(rp.status())

Core Modules#

Acquisition Module (Allego API)#

Programmatic control of data acquisition and real-time monitoring.

Capabilities:

import radienspy.allego as allego

# Configure recording session
session = allego.Session(
    name='experiment_001',
    sample_rate=30000,
    channels=list(range(128)),
    duration=3600  # seconds
)

# Start recording
session.start()

# Monitor in real-time
while session.is_recording():
    metrics = session.get_quality_metrics()
    print(f"SNR: {metrics['mean_snr']:.2f} dB")
    
# Stop and save
session.stop()
session.save('/data/recordings/exp001.xdat')

Features:

• Hardware detection and configuration
• Real-time signal monitoring
• Quality metric calculation
• Event marking and annotation
• Multi-probe synchronization

Analysis Module (Videre API)#

Comprehensive neural data analysis and visualization tools.

Data Loading:

import radienspy.videre as videre

# Universal file loading
data = videre.load('/data/recording.xdat')
# Also supports: .rhd, .nwb, .hdf5, .pl2, etc.

# Inspect data structure
print(data.info())
print(f"Channels: {data.n_channels}")
print(f"Duration: {data.duration_sec} seconds")
print(f"Sample rate: {data.sample_rate} Hz")

Signal Processing:

# Filter signals
lfp = data.filter(
    low_cut=1,
    high_cut=300,
    order=4,
    filter_type='butterworth'
)

# Extract spikes
spikes = data.detect_spikes(
    threshold=-4.5,  # in standard deviations
    pre_samples=20,
    post_samples=40
)

# Spectral analysis
psd = data.power_spectral_density(
    method='welch',
    window='hann',
    nperseg=2048
)

Spike Sorting:

# Run Kilosort
sorted_units = videre.spike_sort(
    data,
    method='kilosort3',
    params={'nfilt': 256, 'nt0': 61}
)

# Quality metrics
for unit_id, unit in sorted_units.items():
    print(f"Unit {unit_id}: ISI={unit.isi_viol:.2%}, SNR={unit.snr:.2f}")

# Export for manual curation
sorted_units.export_phy('/data/sorting_results/')

Visualization:

import matplotlib.pyplot as plt

# Plot waveforms
fig = videre.plot.waveforms(
    data,
    channels=[0, 16, 32, 48],
    time_range=(10, 12),  # seconds
    scale='auto'
)

# Raster plot
fig = videre.plot.raster(
    spikes,
    trials=trial_times,
    align_event='stimulus_onset',
    window=(-0.5, 2.0)
)

# 3D probe visualization
fig = videre.plot.probe_3d(
    data,
    activity_metric='firing_rate',
    colormap='viridis'
)

Curation Module (Curate API)#

Metadata management and workflow reproducibility.

Metadata Management:

import radienspy.curate as curate

# Create dataset entry
dataset = curate.Dataset(
    name='chronic_recording_day5',
    subject='mouse_042',
    session_date='2026-03-02'
)

# Add metadata
dataset.metadata.update({
    'subject_species': 'Mus musculus',
    'subject_age_days': 90,
    'probe_type': 'NeuroNexus A64',
    'brain_region': 'motor cortex',
    'recording_type': 'chronic',
    'experimenter': 'Jane Doe'
})

# Link files
dataset.add_file('/data/recording.xdat', role='raw_data')
dataset.add_file('/data/sorted.phy', role='spike_sorting')

# Save to database
dataset.save()

Workflow Definition:

# Define analysis pipeline
pipeline = curate.Pipeline('spike_analysis_v2')

# Add processing steps
pipeline.add_step(
    name='filtering',
    function=videre.filter,
    params={'low_cut': 300, 'high_cut': 6000}
)

pipeline.add_step(
    name='spike_detection',
    function=videre.detect_spikes,
    params={'threshold': -4.5}
)

pipeline.add_step(
    name='spike_sorting',
    function=videre.spike_sort,
    params={'method': 'kilosort3'}
)

# Execute pipeline
results = pipeline.run(dataset)

# Track provenance
print(pipeline.provenance())

FAIR Compliance:

# Export to NWB format
dataset.export_nwb(
    '/data/nwb/session_001.nwb',
    include_metadata=True,
    include_processing=True
)

# Prepare for DANDI repository
dandi_package = curate.prepare_dandi(
    dataset,
    dandiset_id='000123',
    contributors=['Jane Doe', 'John Smith']
)

# Validate compliance
validation = dataset.validate_fair()
print(f"FAIR score: {validation.score}/100")

Advanced Features#

Batch Processing#

Process multiple datasets with parallel execution.

import radienspy as rp
from pathlib import Path

# Find all recordings
data_files = Path('/data/recordings/').glob('*.xdat')

# Parallel batch processing
results = rp.batch.parallel(
    files=data_files,
    function=analyze_session,
    n_jobs=8,
    show_progress=True
)

# Aggregate results
summary = rp.batch.aggregate(results)
summary.to_csv('batch_results.csv')

Custom Extensions#

Extend RadiensPy with custom analysis modules.

import radienspy as rp

# Register custom analysis function
@rp.register_analysis('my_custom_metric')
def compute_custom_metric(data, param1=10, param2=0.5):
    """Custom analysis function."""
    # Your analysis code here
    result = ...
    return result

# Use in pipelines
pipeline.add_step(
    name='custom_analysis',
    function='my_custom_metric',
    params={'param1': 15}
)

Jupyter Integration#

Optimized for interactive notebook workflows.

# Jupyter-specific features
import radienspy as rp
rp.set_notebook_mode(True)

# Interactive widgets
data = rp.load('/data/recording.xdat')
data.explore()  # launches interactive widget

# Inline plotting
%matplotlib inline
data.plot.overview()

# Progress bars
for result in rp.batch.process(files, show_progress='notebook'):
    display(result.summary())

Machine Learning#

Integration with scikit-learn and PyTorch.

import radienspy.ml as ml
from sklearn.decomposition import PCA

# Extract features
features = ml.extract_features(
    spikes,
    feature_set=['waveform_pca', 'isi', 'amplitude']
)

# Dimensionality reduction
reduced = PCA(n_components=3).fit_transform(features)

# Neural decoders
decoder = ml.DeepDecoder(
    input_dim=features.shape[1],
    output_dim=8,  # behavioral states
    layers=[128, 64, 32]
)

# Train model
decoder.fit(
    features,
    behavior_labels,
    validation_split=0.2,
    epochs=100
)

# Evaluate
accuracy = decoder.evaluate(test_features, test_labels)

Data Structures#

Recording Object#

Core data container with lazy loading.

recording = rp.Recording('/data/file.xdat')

# Properties
recording.sample_rate  # Hz
recording.n_channels
recording.duration_sec
recording.metadata

# Data access (lazy loaded)
data_segment = recording[100:200, :]  # samples × channels
channel_data = recording[:, 0]  # entire channel 0

# Time-based indexing
time_segment = recording.time_slice(10.0, 12.0)  # seconds

Spikes Object#

Spike train representation and analysis.

spikes = rp.Spikes(times, channels, waveforms)

# Spike train statistics
spikes.firing_rates
spikes.isi_violations
spikes.burst_ratios

# Trial-based analysis
aligned = spikes.align_to_events(
    event_times,
    window=(-0.5, 2.0)
)

psth = aligned.psth(bin_size=0.01)

Pipeline Object#

Workflow management and execution.

pipeline = rp.Pipeline('standard_analysis')

# Pipeline operations
pipeline.validate()  # check for errors
pipeline.visualize()  # show dependency graph
pipeline.export_yaml('pipeline.yaml')  # save definition

# Execution control
pipeline.run(dataset, cache=True)  # cache intermediate results
pipeline.resume(from_step='spike_sorting')  # resume from checkpoint

File Format Support#

Input Formats#

Read data from all major electrophysiology formats.

Supported Formats:

• NeuroNexus: .xdat
• Intan: .rhd, .rhs, .dat
• Open Ephys: .continuous, .events, .spikes
• NWB: .nwb (Neurodata Without Borders)
• HDF5: .h5, .hdf5
• Plexon: .pl2, .plx
• Blackrock: .nsx, .nev
• TDT: .tsq, .tev, .tin
• MATLAB: .mat
• Generic: .csv, .txt, .bin

Output Formats#

Export processed data and results.

# Save processed data
data.save('/output/filtered.xdat')

# Export to NWB
data.export_nwb('/output/session.nwb')

# Save as HDF5
data.to_hdf5('/output/data.h5')

# Export results
results.to_csv('/output/metrics.csv')
results.to_json('/output/results.json')
results.to_pickle('/output/results.pkl')

Performance Optimization#

Memory Management#

Efficient handling of large datasets.

# Memory-mapped file access
data = rp.load('/data/large_file.xdat', memory_map=True)

# Chunked processing
for chunk in data.iter_chunks(chunk_size=30000):
    process(chunk)

# Out-of-core computation
result = rp.compute(
    data,
    function=expensive_operation,
    strategy='dask'  # distributed computing
)

Parallel Processing#

Multi-core and distributed execution.

# Parallel channel processing
results = rp.parallel_map(
    function=process_channel,
    inputs=range(data.n_channels),
    n_jobs=-1  # use all cores
)

# Distributed with Dask
import dask.distributed as dd

client = dd.Client('scheduler:8786')
results = rp.compute(
    data,
    function=analysis_pipeline,
    client=client
)

Integration Ecosystem#

SpikeInterface#

Seamless integration with SpikeInterface toolkit.

import spikeinterface as si

# Convert to SpikeInterface format
recording = rp.to_spikeinterface(data)

# Use SpikeInterface sorters
sorted = si.sorters.run_sorter(
    'mountainsort4',
    recording,
    output_folder='/tmp/sorting'
)

# Convert back to RadiensPy
units = rp.from_spikeinterface(sorted)

Neo and Elephant#

Compatibility with Neo data model and Elephant analysis.

import neo
import elephant

# Export to Neo
neo_segment = data.to_neo()

# Use Elephant functions
rates = elephant.statistics.instantaneous_rate(
    neo_segment.spiketrains[0],
    sampling_period=1*pq.ms
)

Documentation and Learning#

Interactive Documentation#

# Built-in help
import radienspy as rp
help(rp.videre.filter)

# Example gallery
rp.examples.list()  # show available examples
rp.examples.run('spike_sorting_tutorial')

# API reference
rp.docs.open()  # opens browser to documentation

Example Scripts#

Comprehensive example library.

Available Examples:

• Basic data loading and exploration
• Signal processing and filtering
• Spike detection and sorting
• LFP analysis and spectrograms
• Population analysis
• Machine learning classification
• FAIR data export
• Custom pipeline creation

Testing and Validation#

Unit Testing#

Validate custom analysis code.

import radienspy.testing as rpt

# Generate synthetic data
synthetic_data = rpt.generate_recording(
    n_channels=32,
    duration=60,
    sample_rate=30000,
    noise_level=10.0,
    n_units=15
)

# Test analysis function
result = my_analysis_function(synthetic_data)
assert rpt.validate_spike_sorting(result)

Technical Specifications#

Python Version: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14

Platforms:

• Windows 10/11
• macOS 12+
• Ubuntu 20.04+
• Other Linux distributions

Performance:

• Multi-threaded operations using NumPy/SciPy BLAS
• GPU acceleration for supported operations (CUDA, Metal)
• Distributed computing via Dask
• Memory-efficient streaming for large files

Licensing and Availability#

License Tiers:

• Radiens BASE: Core RadiensPy functionality
• Radiens LIVE: Real-time API access
• Radiens ANALYZE: Full analysis module
• Radiens SUITE: Complete API with cloud integration

Distribution:

• PyPI: pip install radienspy
• Conda: conda install -c neuronexus radienspy
• GitHub: github.com/neuronexus/radienspy

Support:

• API Documentation: docs.radiens.io
• Stack Overflow: tagged 'radienspy'
• GitHub Issues: bug reports and feature requests
• Direct Support: [email protected]

Future Development#

• Real-Time API: Streaming data from active Allego sessions
• Cloud Native: Native integration with cloud storage (S3, GCS, Azure)
• Enhanced ML: Pre-trained models and AutoML capabilities
• Julia Bindings: API access for Julia language
• Web API: RESTful endpoints for language-agnostic access
• Plugin System: Community-contributed analysis modules