tessl/pypi-neo

A comprehensive Python library for representing electrophysiology data with support for reading and writing a wide range of neurophysiology file formats.

—

Pending

Overview

Eval results

Files

File I/O Support

Name: tessl/pypi-neo
Author: tessl

Comprehensive support for reading and writing electrophysiology data across 50+ file formats from major hardware manufacturers, analysis software, and standard data formats. Neo's I/O system automatically handles format detection, metadata preservation, and dimensional consistency across diverse neurophysiology ecosystems.

Capabilities

Automatic Format Detection

High-level functions that automatically detect file formats and return appropriate I/O instances.

def get_io(file_or_folder, *args, **kwargs):
    """
    Return a Neo IO instance, guessing the type based on the filename suffix.
    
    Parameters:
    - file_or_folder (str, pathlib.Path): Path to file or folder
    - *args, **kwargs: Additional arguments passed to IO constructor
    
    Returns:
    Neo IO instance for the detected format
    
    Raises:
    IOError: If format cannot be determined or no compatible IO found
    """

def list_candidate_ios(file_or_folder, ignore_patterns=["*.ini", "README.txt"]):
    """
    Identify Neo IO classes that can potentially load data from file or folder.
    
    Parameters:
    - file_or_folder (str, pathlib.Path): Path to analyze
    - ignore_patterns (list): Patterns to ignore when scanning
    
    Returns:
    list: Neo IO classes associated with detected file extensions
    """

Hardware Manufacturer Formats

I/O classes for proprietary formats from major electrophysiology hardware manufacturers.

class AxonIO:
    """
    Molecular Devices Axon file format (.abf, .atf).
    
    Supports pCLAMP and AxoScope files with protocol reconstruction
    and stimulus waveform information for ABF2 format.
    """
    extensions = ['.abf', '.atf']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block, **kwargs): ...
    def read_protocol(self): ...  # ABF2 protocol waveforms

class BlackrockIO:
    """Blackrock Microsystems file format (.nev, .ns1, .ns2, .ns3, .ns4, .ns5, .ns6)."""
    extensions = ['.nev', '.ns1', '.ns2', '.ns3', '.ns4', '.ns5', '.ns6']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class PlexonIO:
    """Plexon file format (.plx).""" 
    extensions = ['.plx']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class Plexon2IO:
    """Plexon2 file format (.pl2)."""
    extensions = ['.pl2']  
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class IntanIO:
    """Intan Technologies file format (.rhd, .rhs)."""
    extensions = ['.rhd', '.rhs']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class AlphaOmegaIO:
    """AlphaOmega file format (.map, .mpx)."""
    extensions = ['.map', '.mpx']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class NeuralynxIO:
    """Neuralynx file format (.ncs, .nev, .nse, .ntt, .nst)."""
    extensions = ['.ncs', '.nev', '.nse', '.ntt', '.nst']
    
    def __init__(self, dirname): ...
    def read_block(self, **kwargs): ...

class TdtIO:
    """Tucker-Davis Technologies file format (.tev, .tsq, .tnt)."""
    extensions = ['.tev', '.tsq', '.tnt']
    
    def __init__(self, dirname): ...  
    def read_block(self, **kwargs): ...

class Spike2IO:
    """Cambridge Electronic Design Spike2 format (.smr, .son)."""
    extensions = ['.smr', '.son']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class MaxwellIO:
    """Maxwell Biosystems file format (.raw.h5)."""
    extensions = ['.raw.h5']
    
    def __init__(self, filename): ...  
    def read_block(self, **kwargs): ...

Multi-Electrode Array Formats

Specialized formats for multi-electrode array (MEA) and high-density probe recordings.

class BiocamIO:
    """3Brain Biocam file format (.brw, .bxr)."""
    extensions = ['.brw', '.bxr']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class MEArecIO:
    """MEArec simulated multi-electrode array format (.h5)."""
    extensions = ['.h5']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class NeuroNexusIO:
    """NeuroNexus probe file format (.xdaq)."""
    extensions = ['.xdaq']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class SpikeGadgetsIO:
    """SpikeGadgets file format (.rec, .mda)."""
    extensions = ['.rec', '.mda']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class RawMCSIO:
    """Multi Channel Systems raw file format (.raw)."""
    extensions = ['.raw']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

Open Source and Analysis Software Formats

Formats from open source tools and commercial analysis software.

class OpenEphysIO:
    """Open Ephys GUI file format (.continuous, .events, .spikes).""" 
    extensions = ['.continuous', '.events', '.spikes']
    
    def __init__(self, dirname): ...
    def read_block(self, **kwargs): ...

class OpenEphysBinaryIO:
    """Open Ephys binary file format (.dat)."""
    extensions = ['.dat']
    
    def __init__(self, dirname): ...
    def read_block(self, **kwargs): ...

class PhyIO:
    """Phy spike sorting file format (params.py, cluster_info.tsv)."""
    extensions = []  # Directory-based format
    
    def __init__(self, dirname): ...
    def read_block(self, **kwargs): ...

class SpikeGLXIO:
    """SpikeGLX acquisition file format (.bin, .meta)."""
    extensions = ['.bin', '.meta']
    
    def __init__(self, dirname): ...
    def read_block(self, **kwargs): ...

class NeuroExplorerIO:
    """NeuroExplorer analysis software format (.nex, .nex5)."""
    extensions = ['.nex', '.nex5']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class KlustaKwikIO:
    """KlustaKwik spike sorting format (.fet, .clu, .res, .spk)."""
    extensions = ['.fet', '.clu', '.res', '.spk']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class KwikIO:
    """Kwik spike sorting file format (.kwik, .kwx, .kwd)."""
    extensions = ['.kwik', '.kwx', '.kwd'] 
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class BrainVisionIO:
    """Brain Products BrainVision file format (.vhdr, .vmrk, .eeg)."""
    extensions = ['.vhdr', '.vmrk', '.eeg']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class NeuroScopeIO:
    """NeuroScope/Klusters file format (.dat, .xml, .clu, .res, .fet, .spk)."""
    extensions = ['.dat', '.xml', '.clu', '.res', '.fet', '.spk']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

Standard and Open Data Formats

Industry-standard and open data format support.

class NWBIO:
    """
    Neurodata Without Borders format (.nwb).
    
    Standardized format for neurophysiology data sharing
    with rich metadata and hierarchical organization.
    """
    extensions = ['.nwb']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class NixIO:
    """
    NIX (Neuroscience Information Exchange) format (.nix).
    
    Self-describing data format with built-in metadata
    and annotation capabilities.
    """
    extensions = ['.nix']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class EDFIO:
    """European Data Format for biomedical signals (.edf, .bdf)."""
    extensions = ['.edf', '.bdf']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

class PickleIO:
    """Python pickle serialization format (.pkl, .pickle)."""
    extensions = ['.pkl', '.pickle']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class NeoMatlabIO:
    """Neo-specific MATLAB file format (.mat)."""
    extensions = ['.mat']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

Text and ASCII Formats

Simple text-based formats for interoperability.

class AsciiSignalIO:
    """ASCII text signal file format (.txt, .asc)."""
    extensions = ['.txt', '.asc']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class AsciiSpikeTrainIO:
    """ASCII text spike train format (.txt)."""
    extensions = ['.txt']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...
    def write_block(self, block): ...

class AsciiImageIO:
    """ASCII text image file format (.txt)."""
    extensions = ['.txt']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

Raw Binary Formats

Direct binary data access for custom formats.

class RawBinarySignalIO:
    """
    Raw binary signal file format (.raw, .bin).
    
    Flexible reader for custom binary formats with
    user-specified parameters for data layout.
    """
    extensions = ['.raw', '.bin']
    
    def __init__(self, filename): ...
    def read_block(self, **kwargs): ...

Usage Examples

Auto-Detection and Reading

import neo

# Automatic format detection
io = neo.io.get_io('recording.abf')
block = io.read_block()

# List compatible formats
candidates = neo.io.list_candidate_ios('data_folder/')
print(f"Compatible formats: {[io.__name__ for io in candidates]}")

# Handle multiple file types in directory
for io_class in candidates:
    try:
        io = io_class('data_folder/')
        block = io.read_block()
        print(f"Successfully loaded with {io_class.__name__}")
        break
    except Exception as e:
        print(f"Failed with {io_class.__name__}: {e}")
        continue

Specific Format Usage

from neo.io import AxonIO, BlackrockIO, PlexonIO

# Axon ABF files
axon_io = AxonIO('patch_clamp.abf')
block = axon_io.read_block()

# Access protocol information (ABF2 only)
if hasattr(axon_io, 'read_protocol'):
    protocol = axon_io.read_protocol()

# Blackrock files
blackrock_io = BlackrockIO('array_recording.ns5')
block = blackrock_io.read_block(
    lazy=False,                    # Load all data into memory
    cascade=True,                  # Load all hierarchical data
    load_waveforms=True           # Include spike waveforms
)

# Plexon files  
plexon_io = PlexonIO('sorted_units.plx')
block = plexon_io.read_block(
    lazy=False,
    cascade=True,
    load_waveforms=True
)

Writing Data

from neo.io import NixIO, PickleIO, Spike2IO
import neo

# Create sample data
block = neo.Block(name="Test Experiment")
segment = neo.Segment(name="Trial 1")
block.segments.append(segment)

# Save to different formats
# NIX format (recommended for archival)
nix_io = NixIO('experiment.nix', mode='w')
nix_io.write_block(block)
nix_io.close()

# Python pickle (fastest, Python-only)
pickle_io = PickleIO('experiment.pkl')  
pickle_io.write_block(block)

# Spike2 format (compatible with CED software)
spike2_io = Spike2IO('experiment.smr')
spike2_io.write_block(block)

Advanced I/O Options

# Lazy loading for large files
io = neo.io.get_io('large_recording.ns5')
block = io.read_block(lazy=True)  # Metadata only, data loaded on access

# Selective loading
block = io.read_block(
    cascade=False,                # Don't auto-load all hierarchical data
    load_waveforms=False,        # Skip spike waveforms to save memory
    signal_group_mode='split-all' # How to organize multi-channel data
)

# Time window loading
segment = io.read_segment(
    seg_index=0,
    time_slice=(10.0, 20.0),     # Load only 10-20 second window
    strict_slicing=False          # Allow partial overlap
)

# Channel selection
segment = io.read_segment(
    seg_index=0,
    channel_indexes=[0, 2, 4]    # Load only specific channels
)

Error Handling and Diagnostics

import neo
from neo.core import NeoReadWriteError

try:
    io = neo.io.get_io('problematic_file.dat')
    block = io.read_block()
    
except IOError as e:
    print(f"File format not recognized: {e}")
    
except NeoReadWriteError as e:
    print(f"Neo-specific I/O error: {e}")
    
except Exception as e:
    print(f"General error: {e}")

# Check file integrity
io = neo.io.AxonIO('test.abf')
if hasattr(io, 'parse_header'):
    try:
        io.parse_header()
        print("File header parsed successfully")
    except Exception as e:
        print(f"Header parsing failed: {e}")

File Format Coverage

By Hardware Manufacturer

Molecular Devices: AxonIO (.abf, .atf)
Blackrock Microsystems: BlackrockIO (.nev, .ns1-.ns6)
Plexon: PlexonIO (.plx), Plexon2IO (.pl2)
Intan Technologies: IntanIO (.rhd, .rhs)
AlphaOmega: AlphaOmegaIO (.map, .mpx)
Neuralynx: NeuralynxIO (.ncs, .nev, .nse, .ntt)
Tucker-Davis Technologies: TdtIO (.tev, .tsq, .tnt)
Cambridge Electronic Design: Spike2IO (.smr, .son), CedIO
3Brain: BiocamIO (.brw, .bxr)
Maxwell Biosystems: MaxwellIO (.raw.h5)
Multi Channel Systems: RawMCSIO (.raw)

By Analysis Software

Open Ephys: OpenEphysIO, OpenEphysBinaryIO
Phy: PhyIO (spike sorting)
SpikeGLX: SpikeGLXIO (.bin, .meta)
NeuroExplorer: NeuroExplorerIO (.nex, .nex5)
KlustaKwik: KlustaKwikIO (.fet, .clu, .res, .spk)
Kwik: KwikIO (.kwik, .kwx, .kwd)
Brain Products: BrainVisionIO (.vhdr, .vmrk, .eeg)
NeuroScope/Klusters: NeuroScopeIO

By Standard Format

Neurodata Without Borders: NWBIO (.nwb)
NIX: NixIO (.nix)
European Data Format: EDFIO (.edf, .bdf)
Python Pickle: PickleIO (.pkl, .pickle)
MATLAB: NeoMatlabIO (.mat)
ASCII Text: AsciiSignalIO, AsciiSpikeTrainIO, AsciiImageIO
Raw Binary: RawBinarySignalIO (.raw, .bin)

Total Coverage

52 I/O classes covering 100+ file extensions
Hardware formats: 15+ manufacturers
Software formats: 10+ analysis tools
Standard formats: 8 open/industry standards
Read support: All formats
Write support: 12 formats (NIX, NWB, Pickle, Spike2, ASCII, etc.)

Types

# I/O class types
IOClass = type[BaseIO]                    # Base I/O class type
IOList = list[IOClass]                    # List of I/O classes

# File and path types  
FilePath = str | pathlib.Path             # File or directory path
FileExtension = str                       # File extension string  
ExtensionMapping = dict[str, list[IOClass]]  # Extension to I/O mapping

# I/O operation types
ReadMode = Literal['lazy', 'eager']       # Data loading strategy
WriteMode = Literal['w', 'a', 'r+']      # File write mode
TimeSlice = tuple[float, float]           # Time window specification
ChannelIndexes = list[int] | slice        # Channel selection

# Error types
IOError = IOError                         # Standard I/O error
NeoReadWriteError = NeoReadWriteError     # Neo-specific I/O error

Install with Tessl CLI