0
# Neo
1

2
Neo is a comprehensive Python library for representing electrophysiology data with support for reading and writing a wide range of neurophysiology file formats. It provides a hierarchical data model well-adapted to intracellular and extracellular electrophysiology and EEG data with multi-electrode support, building on NumPy and the quantities package for dimensional consistency and automatic unit conversion.
3

4
## Package Information
5

6
- **Package Name**: neo
7
- **Language**: Python
8
- **Installation**: `pip install neo`
9
- **Version**: 0.14.2
10
- **Dependencies**: NumPy, quantities
11
- **License**: BSD 3-Clause License
12

13
## Core Imports
14

15
```python
16
import neo
17
```
18

19
Common imports for working with data structures:
20

21
```python
22
from neo import Block, Segment, AnalogSignal, SpikeTrain, Event, Epoch
23
```
24

25
Common imports for file I/O:
26

27
```python
28
from neo.io import AxonIO, BlackrockIO, PlexonIO, Spike2IO
29
from neo.io import get_io  # Auto-detect file format
30
```
31

32
Common imports for utilities:
33

34
```python
35
from neo.utils import get_events, get_epochs, cut_segment_by_epoch
36
```
37

38
## Basic Usage
39

40
```python
41
import neo
42
from neo import Block, Segment, AnalogSignal, SpikeTrain
43
from neo.io import AxonIO
44
import numpy as np
45
import quantities as pq
46

47
# Reading data from files
48
io = AxonIO('data.abf')
49
block = io.read_block()
50

51
# Or auto-detect format
52
io = neo.io.get_io('data.abf')
53
block = io.read_block()
54

55
# Creating data structures manually
56
block = Block(name="Experiment 1")
57
segment = Segment(name="Trial 1")
58
block.segments.append(segment)
59

60
# Create analog signal data
61
signal_data = np.random.randn(1000, 4) * pq.mV  # 1000 samples, 4 channels
62
sampling_rate = 10 * pq.kHz
63
analog_signal = AnalogSignal(
64
    signal_data, 
65
    sampling_rate=sampling_rate,
66
    name="LFP recordings"
67
)
68
segment.analogsignals.append(analog_signal)
69

70
# Create spike train data
71
spike_times = np.array([0.1, 0.3, 0.7, 1.2, 1.8]) * pq.s
72
spike_train = SpikeTrain(
73
    spike_times,
74
    t_start=0 * pq.s,
75
    t_stop=2 * pq.s,
76
    name="Neuron 1"
77
)
78
segment.spiketrains.append(spike_train)
79

80
# Access data
81
print(f"Block contains {len(block.segments)} segments")
82
print(f"First segment has {len(segment.analogsignals)} analog signals")
83
print(f"Signal shape: {analog_signal.shape}")
84
print(f"Sampling rate: {analog_signal.sampling_rate}")
85
```
86

87
## Architecture
88

89
Neo implements a hierarchical data model organized around the Artist hierarchy:
90

91
- **Block**: Top-level container for entire experiments or recording sessions
92
- **Segment**: Time-based container for temporally related data (trials, epochs)
93
- **Group**: Logical grouping container for related data objects across segments
94
- **Data Objects**: Core electrophysiology data types (signals, spikes, events)
95

96
This design enables Neo to serve as the foundational data representation layer for the Python neuroscience ecosystem, providing interoperability between analysis tools like Elephant, visualization tools like SpykeViewer, simulators like PyNN, and spike sorting tools like tridesclous.
97

98
## Capabilities
99

100
### Core Data Structures
101

102
Fundamental data containers and objects for representing all types of electrophysiology data, from continuous signals to discrete events and spike trains.
103

104
```python { .api }
105
class Block:
106
    def __init__(self, name=None, description=None, **annotations): ...
107
    segments: list  # List of Segment objects
108
    groups: list    # List of Group objects
109

110
class Segment:
111
    def __init__(self, name=None, description=None, **annotations): ...
112
    analogsignals: list      # List of AnalogSignal objects
113
    spiketrains: list        # List of SpikeTrain objects  
114
    events: list             # List of Event objects
115
    epochs: list             # List of Epoch objects
116
    imagesequences: list     # List of ImageSequence objects
117

118
class AnalogSignal:
119
    def __init__(self, signal, units=None, dtype=None, copy=None,
120
                 t_start=0*pq.s, sampling_rate=None, sampling_period=None,
121
                 name=None, file_origin=None, description=None,
122
                 array_annotations=None, **annotations): ...
123
    
124
class SpikeTrain:
125
    def __init__(self, times, t_stop, units=None, dtype=None, copy=None,
126
                 sampling_rate=1.0*pq.Hz, t_start=0.0*pq.s, waveforms=None,
127
                 left_sweep=None, name=None, file_origin=None, description=None,
128
                 array_annotations=None, **annotations): ...
129
```
130

131
[Core Data Structures](./core-data-structures.md)
132

133
### File I/O Support
134

135
Comprehensive support for reading and writing electrophysiology data across 50+ file formats from major hardware manufacturers and analysis software.
136

137
```python { .api }
138
def get_io(file_or_folder, *args, **kwargs):
139
    """Return a Neo IO instance, guessing the type based on the filename suffix."""
140

141
class AxonIO:
142
    def __init__(self, filename): ...
143
    def read_block(self, **kwargs): ...
144
    def write_block(self, block, **kwargs): ...
145

146
class BlackrockIO:
147
    def __init__(self, filename): ...
148
    def read_block(self, **kwargs): ...
149

150
class PlexonIO:
151
    def __init__(self, filename): ...  
152
    def read_block(self, **kwargs): ...
153
```
154

155
[File I/O Support](./file-io-support.md)
156

157
### Data Manipulation Utilities
158

159
Utility functions for extracting, filtering, and manipulating electrophysiology data objects within the Neo hierarchy.
160

161
```python { .api }
162
def get_events(container, **properties):
163
    """Extract events matching specified criteria."""
164

165
def get_epochs(container, **properties):
166
    """Extract epochs matching specified criteria."""
167

168
def cut_segment_by_epoch(segment, epoch):
169
    """Create new segment containing data within epoch boundaries."""
170

171
def download_dataset(name, data_home=None):
172
    """Download public electrophysiology datasets for testing and examples."""
173
```
174

175
[Data Manipulation Utilities](./data-utilities.md)
176

177
### Low-Level File Access
178

179
High-performance, memory-efficient access to file data through the RawIO interface, providing direct access to signal chunks without creating full Neo objects.
180

181
```python { .api }
182
class AxonRawIO:
183
    def __init__(self, filename): ...
184
    def parse_header(self): ...
185
    def get_signal_size(self, block_index, seg_index, channel_indexes): ...
186
    def get_analogsignal_chunk(self, block_index, seg_index, i_start, i_stop, channel_indexes): ...
187

188
def get_rawio(filename):
189
    """Auto-detect and return appropriate RawIO class for file format."""
190
```
191

192
[Low-Level File Access](./rawio-access.md)
193

194
## Types
195

196
```python { .api }
197
# Core quantity types using the quantities package
198
Signal = np.ndarray * pq.Quantity  # Array with physical units
199
Time = pq.Quantity                 # Time values with units (s, ms, etc.)
200
Rate = pq.Quantity                 # Sampling rates with units (Hz, kHz, etc.)
201

202
# Annotation types
203
Annotations = dict                 # Arbitrary metadata key-value pairs
204

205
# Container relationships
206
BlockList = list[Block]           # List of Block objects
207
SegmentList = list[Segment]       # List of Segment objects  
208
GroupList = list[Group]           # List of Group objects
209
```