0
# File I/O Support
1

2
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.
3

4
## Capabilities
5

6
### Automatic Format Detection
7

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

10
```python { .api }
11
def get_io(file_or_folder, *args, **kwargs):
12
    """
13
    Return a Neo IO instance, guessing the type based on the filename suffix.
14
    
15
    Parameters:
16
    - file_or_folder (str, pathlib.Path): Path to file or folder
17
    - *args, **kwargs: Additional arguments passed to IO constructor
18
    
19
    Returns:
20
    Neo IO instance for the detected format
21
    
22
    Raises:
23
    IOError: If format cannot be determined or no compatible IO found
24
    """
25

26
def list_candidate_ios(file_or_folder, ignore_patterns=["*.ini", "README.txt"]):
27
    """
28
    Identify Neo IO classes that can potentially load data from file or folder.
29
    
30
    Parameters:
31
    - file_or_folder (str, pathlib.Path): Path to analyze
32
    - ignore_patterns (list): Patterns to ignore when scanning
33
    
34
    Returns:
35
    list: Neo IO classes associated with detected file extensions
36
    """
37
```
38

39
### Hardware Manufacturer Formats
40

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

43
```python { .api }
44
class AxonIO:
45
    """
46
    Molecular Devices Axon file format (.abf, .atf).
47
    
48
    Supports pCLAMP and AxoScope files with protocol reconstruction
49
    and stimulus waveform information for ABF2 format.
50
    """
51
    extensions = ['.abf', '.atf']
52
    
53
    def __init__(self, filename): ...
54
    def read_block(self, **kwargs): ...
55
    def write_block(self, block, **kwargs): ...
56
    def read_protocol(self): ...  # ABF2 protocol waveforms
57

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

65
class PlexonIO:
66
    """Plexon file format (.plx).""" 
67
    extensions = ['.plx']
68
    
69
    def __init__(self, filename): ...
70
    def read_block(self, **kwargs): ...
71

72
class Plexon2IO:
73
    """Plexon2 file format (.pl2)."""
74
    extensions = ['.pl2']  
75
    
76
    def __init__(self, filename): ...
77
    def read_block(self, **kwargs): ...
78

79
class IntanIO:
80
    """Intan Technologies file format (.rhd, .rhs)."""
81
    extensions = ['.rhd', '.rhs']
82
    
83
    def __init__(self, filename): ...
84
    def read_block(self, **kwargs): ...
85

86
class AlphaOmegaIO:
87
    """AlphaOmega file format (.map, .mpx)."""
88
    extensions = ['.map', '.mpx']
89
    
90
    def __init__(self, filename): ...
91
    def read_block(self, **kwargs): ...
92

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

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

107
class Spike2IO:
108
    """Cambridge Electronic Design Spike2 format (.smr, .son)."""
109
    extensions = ['.smr', '.son']
110
    
111
    def __init__(self, filename): ...
112
    def read_block(self, **kwargs): ...
113
    def write_block(self, block): ...
114

115
class MaxwellIO:
116
    """Maxwell Biosystems file format (.raw.h5)."""
117
    extensions = ['.raw.h5']
118
    
119
    def __init__(self, filename): ...  
120
    def read_block(self, **kwargs): ...
121
```
122

123
### Multi-Electrode Array Formats
124

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

127
```python { .api }
128
class BiocamIO:
129
    """3Brain Biocam file format (.brw, .bxr)."""
130
    extensions = ['.brw', '.bxr']
131
    
132
    def __init__(self, filename): ...
133
    def read_block(self, **kwargs): ...
134

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

142
class NeuroNexusIO:
143
    """NeuroNexus probe file format (.xdaq)."""
144
    extensions = ['.xdaq']
145
    
146
    def __init__(self, filename): ...
147
    def read_block(self, **kwargs): ...
148

149
class SpikeGadgetsIO:
150
    """SpikeGadgets file format (.rec, .mda)."""
151
    extensions = ['.rec', '.mda']
152
    
153
    def __init__(self, filename): ...
154
    def read_block(self, **kwargs): ...
155

156
class RawMCSIO:
157
    """Multi Channel Systems raw file format (.raw)."""
158
    extensions = ['.raw']
159
    
160
    def __init__(self, filename): ...
161
    def read_block(self, **kwargs): ...
162
```
163

164
### Open Source and Analysis Software Formats
165

166
Formats from open source tools and commercial analysis software.
167

168
```python { .api }
169
class OpenEphysIO:
170
    """Open Ephys GUI file format (.continuous, .events, .spikes).""" 
171
    extensions = ['.continuous', '.events', '.spikes']
172
    
173
    def __init__(self, dirname): ...
174
    def read_block(self, **kwargs): ...
175

176
class OpenEphysBinaryIO:
177
    """Open Ephys binary file format (.dat)."""
178
    extensions = ['.dat']
179
    
180
    def __init__(self, dirname): ...
181
    def read_block(self, **kwargs): ...
182

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

190
class SpikeGLXIO:
191
    """SpikeGLX acquisition file format (.bin, .meta)."""
192
    extensions = ['.bin', '.meta']
193
    
194
    def __init__(self, dirname): ...
195
    def read_block(self, **kwargs): ...
196

197
class NeuroExplorerIO:
198
    """NeuroExplorer analysis software format (.nex, .nex5)."""
199
    extensions = ['.nex', '.nex5']
200
    
201
    def __init__(self, filename): ...
202
    def read_block(self, **kwargs): ...
203

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

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

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

225
class NeuroScopeIO:
226
    """NeuroScope/Klusters file format (.dat, .xml, .clu, .res, .fet, .spk)."""
227
    extensions = ['.dat', '.xml', '.clu', '.res', '.fet', '.spk']
228
    
229
    def __init__(self, filename): ...
230
    def read_block(self, **kwargs): ...
231
```
232

233
### Standard and Open Data Formats
234

235
Industry-standard and open data format support.
236

237
```python { .api }
238
class NWBIO:
239
    """
240
    Neurodata Without Borders format (.nwb).
241
    
242
    Standardized format for neurophysiology data sharing
243
    with rich metadata and hierarchical organization.
244
    """
245
    extensions = ['.nwb']
246
    
247
    def __init__(self, filename): ...
248
    def read_block(self, **kwargs): ...
249
    def write_block(self, block): ...
250

251
class NixIO:
252
    """
253
    NIX (Neuroscience Information Exchange) format (.nix).
254
    
255
    Self-describing data format with built-in metadata
256
    and annotation capabilities.
257
    """
258
    extensions = ['.nix']
259
    
260
    def __init__(self, filename): ...
261
    def read_block(self, **kwargs): ...
262
    def write_block(self, block): ...
263

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

271
class PickleIO:
272
    """Python pickle serialization format (.pkl, .pickle)."""
273
    extensions = ['.pkl', '.pickle']
274
    
275
    def __init__(self, filename): ...
276
    def read_block(self, **kwargs): ...
277
    def write_block(self, block): ...
278

279
class NeoMatlabIO:
280
    """Neo-specific MATLAB file format (.mat)."""
281
    extensions = ['.mat']
282
    
283
    def __init__(self, filename): ...
284
    def read_block(self, **kwargs): ...
285
    def write_block(self, block): ...
286
```
287

288
### Text and ASCII Formats
289

290
Simple text-based formats for interoperability.
291

292
```python { .api }
293
class AsciiSignalIO:
294
    """ASCII text signal file format (.txt, .asc)."""
295
    extensions = ['.txt', '.asc']
296
    
297
    def __init__(self, filename): ...
298
    def read_block(self, **kwargs): ...
299
    def write_block(self, block): ...
300

301
class AsciiSpikeTrainIO:
302
    """ASCII text spike train format (.txt)."""
303
    extensions = ['.txt']
304
    
305
    def __init__(self, filename): ...
306
    def read_block(self, **kwargs): ...
307
    def write_block(self, block): ...
308

309
class AsciiImageIO:
310
    """ASCII text image file format (.txt)."""
311
    extensions = ['.txt']
312
    
313
    def __init__(self, filename): ...
314
    def read_block(self, **kwargs): ...
315
```
316

317
### Raw Binary Formats
318

319
Direct binary data access for custom formats.
320

321
```python { .api }
322
class RawBinarySignalIO:
323
    """
324
    Raw binary signal file format (.raw, .bin).
325
    
326
    Flexible reader for custom binary formats with
327
    user-specified parameters for data layout.
328
    """
329
    extensions = ['.raw', '.bin']
330
    
331
    def __init__(self, filename): ...
332
    def read_block(self, **kwargs): ...
333
```
334

335
## Usage Examples
336

337
### Auto-Detection and Reading
338

339
```python
340
import neo
341

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

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

350
# Handle multiple file types in directory
351
for io_class in candidates:
352
    try:
353
        io = io_class('data_folder/')
354
        block = io.read_block()
355
        print(f"Successfully loaded with {io_class.__name__}")
356
        break
357
    except Exception as e:
358
        print(f"Failed with {io_class.__name__}: {e}")
359
        continue
360
```
361

362
### Specific Format Usage
363

364
```python
365
from neo.io import AxonIO, BlackrockIO, PlexonIO
366

367
# Axon ABF files
368
axon_io = AxonIO('patch_clamp.abf')
369
block = axon_io.read_block()
370

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

375
# Blackrock files
376
blackrock_io = BlackrockIO('array_recording.ns5')
377
block = blackrock_io.read_block(
378
    lazy=False,                    # Load all data into memory
379
    cascade=True,                  # Load all hierarchical data
380
    load_waveforms=True           # Include spike waveforms
381
)
382

383
# Plexon files  
384
plexon_io = PlexonIO('sorted_units.plx')
385
block = plexon_io.read_block(
386
    lazy=False,
387
    cascade=True,
388
    load_waveforms=True
389
)
390
```
391

392
### Writing Data
393

394
```python
395
from neo.io import NixIO, PickleIO, Spike2IO
396
import neo
397

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

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

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

413
# Spike2 format (compatible with CED software)
414
spike2_io = Spike2IO('experiment.smr')
415
spike2_io.write_block(block)
416
```
417

418
### Advanced I/O Options
419

420
```python
421
# Lazy loading for large files
422
io = neo.io.get_io('large_recording.ns5')
423
block = io.read_block(lazy=True)  # Metadata only, data loaded on access
424

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

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

439
# Channel selection
440
segment = io.read_segment(
441
    seg_index=0,
442
    channel_indexes=[0, 2, 4]    # Load only specific channels
443
)
444
```
445

446
### Error Handling and Diagnostics
447

448
```python
449
import neo
450
from neo.core import NeoReadWriteError
451

452
try:
453
    io = neo.io.get_io('problematic_file.dat')
454
    block = io.read_block()
455
    
456
except IOError as e:
457
    print(f"File format not recognized: {e}")
458
    
459
except NeoReadWriteError as e:
460
    print(f"Neo-specific I/O error: {e}")
461
    
462
except Exception as e:
463
    print(f"General error: {e}")
464

465
# Check file integrity
466
io = neo.io.AxonIO('test.abf')
467
if hasattr(io, 'parse_header'):
468
    try:
469
        io.parse_header()
470
        print("File header parsed successfully")
471
    except Exception as e:
472
        print(f"Header parsing failed: {e}")
473
```
474

475
## File Format Coverage
476

477
### By Hardware Manufacturer
478
- **Molecular Devices**: AxonIO (.abf, .atf)
479
- **Blackrock Microsystems**: BlackrockIO (.nev, .ns1-.ns6)  
480
- **Plexon**: PlexonIO (.plx), Plexon2IO (.pl2)
481
- **Intan Technologies**: IntanIO (.rhd, .rhs)
482
- **AlphaOmega**: AlphaOmegaIO (.map, .mpx)
483
- **Neuralynx**: NeuralynxIO (.ncs, .nev, .nse, .ntt)
484
- **Tucker-Davis Technologies**: TdtIO (.tev, .tsq, .tnt)
485
- **Cambridge Electronic Design**: Spike2IO (.smr, .son), CedIO
486
- **3Brain**: BiocamIO (.brw, .bxr)
487
- **Maxwell Biosystems**: MaxwellIO (.raw.h5)
488
- **Multi Channel Systems**: RawMCSIO (.raw)
489

490
### By Analysis Software
491
- **Open Ephys**: OpenEphysIO, OpenEphysBinaryIO
492
- **Phy**: PhyIO (spike sorting)
493
- **SpikeGLX**: SpikeGLXIO (.bin, .meta)
494
- **NeuroExplorer**: NeuroExplorerIO (.nex, .nex5)
495
- **KlustaKwik**: KlustaKwikIO (.fet, .clu, .res, .spk)
496
- **Kwik**: KwikIO (.kwik, .kwx, .kwd)
497
- **Brain Products**: BrainVisionIO (.vhdr, .vmrk, .eeg)
498
- **NeuroScope/Klusters**: NeuroScopeIO
499

500
### By Standard Format
501
- **Neurodata Without Borders**: NWBIO (.nwb)
502
- **NIX**: NixIO (.nix)
503
- **European Data Format**: EDFIO (.edf, .bdf)
504
- **Python Pickle**: PickleIO (.pkl, .pickle)
505
- **MATLAB**: NeoMatlabIO (.mat)
506
- **ASCII Text**: AsciiSignalIO, AsciiSpikeTrainIO, AsciiImageIO
507
- **Raw Binary**: RawBinarySignalIO (.raw, .bin)
508

509
### Total Coverage
510
- **52 I/O classes** covering 100+ file extensions
511
- **Hardware formats**: 15+ manufacturers
512
- **Software formats**: 10+ analysis tools  
513
- **Standard formats**: 8 open/industry standards
514
- **Read support**: All formats
515
- **Write support**: 12 formats (NIX, NWB, Pickle, Spike2, ASCII, etc.)
516

517
## Types
518

519
```python { .api }
520
# I/O class types
521
IOClass = type[BaseIO]                    # Base I/O class type
522
IOList = list[IOClass]                    # List of I/O classes
523

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

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

535
# Error types
536
IOError = IOError                         # Standard I/O error
537
NeoReadWriteError = NeoReadWriteError     # Neo-specific I/O error
538
```