Neo core¶
Introduction¶
Objects in Neo represent neural data and collections of data. Neo objects fall into three categories: data objects, container objects and grouping objects.
Data objects¶
These objects directly represent data as arrays of numerical values with associated metadata (units, sampling frequency, etc.).
AnalogSignal
:- A regular sampling of a continuous, analog signal.
AnalogSignalArray
:- A regular sampling of a multichannel continuous analog signal. This representation (as a 2D NumPy array) may be more efficient for subsequent analysis than the equivalent list of individual
AnalogSignal
objects. Spike
:- One action potential characterized by its time and waveform.
SpikeTrain
:- A set of action potentials (spikes) emitted by the same unit in a period of time (with optional waveforms).
Event
andEventArray
:- A time point representng an event in the data, or an array of such time points.
Epoch
andEpochArray
:- An interval of time representing a period of time in the data, or an array of such intervals.
Container objects¶
There is a simple hierarchy of containers:
Segment
:- A container for heterogeneous discrete or continous data sharing a common clock (time basis) but not necessarily the same sampling rate, start time or end time. A
Segment
can be considered as equivalent to a “trial”, “episode”, “run”, “recording”, etc., depending on the experimental context. May contain any of the data objects. Block
:- The top-level container gathering all of the data, discrete and continuous, for a given recording session. Contains
Segment
andRecordingChannelGroup
objects.
Grouping objects¶
These objects express the relationships between data items, such as which signals were recorded on which electrodes, which spike trains were obtained from which membrane potential signals, etc. They contain references to data objects that cut across the simple container hierarchy.
RecordingChannel
:- Links
AnalogSignal
,SpikeTrain
objects that come from the same logical and/or physical channel inside aBlock
, possibly across severalSegment
objects. RecordingChannelGroup
:- A group for associated
RecordingChannel
objects. This has several possible uses: - for linking several
AnalogSignalArray
objects across severalSegment
objects inside aBlock
. - for multielectrode arrays, where spikes may be recorded on more than one recording channel,
and so the
RecordingChannelGroup
can be used to associate eachUnit
with the group of recording channels from which it was calculated. - for grouping several
RecordingChannel
objects. There are many use cases for this. For instance, for intracellular recording, it is common to record both membrane potentials and currents at the same time, so eachRecordingChannelGroup
may correspond to the particular property that is being recorded. For multielectrode arrays,RecordingChannelGroup
is used to gather allRecordingChannel
objects of the same array.
- for linking several
- A group for associated
Unit
:- A Unit gathers all the
SpikeTrain
objects within a commonBlock
, possibly across several Segments, that have been emitted by the same cell. AUnit
is linked toRecordingChannelGroup
objects from which it was detected. This replaces theNeuron
class in the previous version of Neo (v0.1).
Relationships between objects¶
Container objects like Block
or Segment
are gateways to
access other objects. For example, a Block
can access a Segment
with:
>>> bl = Block()
>>> bl.segments
# gives a list of segments
A Segment
can access the AnalogSignal
objects that it contains with:
>>> seg = Segment()
>>> seg.analogsignals
# gives a list a AnalogSignals
In the Neo diagram below, these one to many relationships are represented by cyan arrows. In general, an object can access its children with an attribute childname+s in lower case, e.g.
Block.segments
Segments.analogsignals
Segments.spiketrains
Block.recordingchannelgroups
These relationships are bi-directional, i.e. a child object can access its parent:
Segment.block
AnalogSignal.segment
SpikeTrains.segment
RecordingChannelGroup.block
Here is an example showing these relationships in use:
from neo.io import AxonIO
import urllib
url = "https://portal.g-node.org/neo/axon/File_axon_3.abf"
filename = './test.abf'
urllib.urlretrieve(url, filename)
r = AxonIO(filename=filename)
bl = r.read() # read the entire file > a Block
print(bl)
print(bl.segments) # child access
for seg in bl.segments:
print(seg)
print(seg.block) # parent access
On the Neo diagram you can also see a magenta line reflecting the many-to-many relationship between RecordingChannel
and RecordingChannelGroup
. This means that each group can contain multiple channels, and each channel can belong to multiple groups.
In some cases, a one-to-many relationship is sufficient. Here is a simple example with tetrodes, in which each tetrode has its own group.:
from neo import *
bl = Block()
# creating individual channel
all_rc= [ ]
for i in range(16):
rc = RecordingChannel( index= i, name ='rc %d' %i)
all_rc.append(rc)
# the four tetrodes
for i in range(4):
rcg = RecordingChannelGroup( name = 'Tetrode %d' % i )
for rc in all_rc[i*4:(i+1)*4]:
rcg.recordingchannels.append(rc)
rc.recordingchannelgroups.append(rcg)
bl.recordingchannelgroups.append(rcg)
# now we load the data and associate it with the created channels
# ...
Now consider a more complex example: a 1x4 silicon probe, with a neuron on channels 0,1,2 and another neuron on channels 1,2,3. We create a group for each neuron to hold the Unit object associated with this spikesorting group. Each group also contains the channels on which that neuron spiked. The relationship is many-to-many because channels 1 and 2 occur in multiple groups.:
from neo import *
bl = Block(name='probe data')
# create individual channels
all_rc = []
for i in range(4):
rc = RecordingChannel(index=i, name='channel %d' % i)
all_rc.append(rc)
# one group for each neuron
rcg0 = RecordingChannelGroup(name='Group 0', index=0)
for i in [0, 1, 2]:
rcg1.recordingchannels.append(all_rc[i])
rc[i].recordingchannelgroups.append(rcg0)
bl.recordingchannelgroups.append(rcg0)
rcg1 = RecordingChannelGroup(name='Group 1', index=1)
for i in [1, 2, 3]:
rcg1.recordingchannels.append(all_rc[i])
rc[i].recordingchannelgroups.append(rcg1)
bl.recordingchannelgroups.append(rcg1)
# now we add the spiketrain from Unit 0 to rcg0
# and add the spiketrain from Unit 1 to rcg1
# ...
Note that because neurons are sorted from groups of channels in this situation, it is natural that the RecordingChannelGroup
contains the Unit
object. That unit then contains its spiketrains.
There are some shortcuts for IO writers to automatically create this structure based on ‘channel_indexes’ entries in the annotations for each spiketrain.
See Typical use cases for more examples of how the different objects may be used.
Neo diagram¶
- Object:
- With a star = inherits from
Quantity
- With a star = inherits from
- Attributes:
- In red = required
- In white = recommended
- Relationship:
- In cyan = one to many
- In magenta = many to many
- In yellow = properties (deduced from other relationships)
Click here for a better quality SVG diagram
For more details, see the API Reference.
Inheritance¶
Some Neo objects (AnalogSignal
, SpikeTrain
, AnalogSignalArray
) inherit from Quantity
, which in turn inherits from NumPy ndarray
. This means that a Neo AnalogSignal
actually is also a Quantity
and an array, giving you access to all of the methods available for those objects.
For example, you can pass a SpikeTrain
directly to the numpy.histogram()
function, or an AnalogSignal
directly to the numpy.std()
function.
Initialization¶
Neo objects are initialized with “required”, “recommended”, and “additional” arguments.
- Required arguments MUST be provided at the time of initialization. They are used in the construction of the object.
- Recommended arguments may be provided at the time of initialization. They are accessible as Python attributes. They can also be set or modified after initialization.
- Additional arguments are defined by the user and are not part of the Neo object model. A primary goal of the Neo project is extensibility. These additional arguments are entries in an attribute of the object: a Python dict called
annotations
.
Example: SpikeTrain¶
SpikeTrain
is a Quantity
, which is a NumPy array containing values with physical dimensions. The spike times are a required attribute, because the dimensionality of the spike times determines the way in which the Quantity
is constructed.
Here is how you initialize a SpikeTrain
with required arguments:
>>> import neo
>>> st = neo.SpikeTrain([3, 4, 5], units='sec', t_stop=10.0)
>>> print(st)
[ 3. 4. 5.] s
You will see the spike times printed in a nice format including the units.
Because st “is a” Quantity
array with units of seconds, it absolutely must have this information at the time of initialization. You can specify the spike times with a keyword argument too:
>>> st = neo.SpikeTrain(times=[3, 4, 5], units='sec', t_stop=10.0)
The spike times could also be in a NumPy array.
If it is not specified, t_start
is assumed to be zero, but another value can easily be specified:
>>> st = neo.SpikeTrain(times=[3, 4, 5], units='sec', t_start=1.0, t_stop=10.0)
>>> st.t_start
array(1.0) * s
Recommended attributes must be specified as keyword arguments, not positional arguments.
Finally, let’s consider “additional arguments”. These are the ones you define for your experiment:
>>> st = neo.SpikeTrain(times=[3, 4, 5], units='sec', t_stop=10.0, rat_name='Fred')
>>> print(st.annotations)
{'rat_name': 'Fred'}
Because rat_name
is not part of the Neo object model, it is placed in the dict annotations
. This dict can be modified as necessary by your code.
Annotations¶
As well as adding annotations as “additional” arguments when an object is
constructed, objects may be annotated using the annotate()
method
possessed by all Neo core objects, e.g.:
>>> seg = Segment()
>>> seg.annotate(stimulus="step pulse", amplitude=10*nA)
>>> print(seg.annotations)
{'amplitude': array(10.0) * nA, 'stimulus': 'step pulse'}
Since annotations may be written to a file or database, there are some
limitations on the data types of annotations: they must be “simple” types or
containers (lists, dicts, NumPy arrays) of simple types, where the simple types
are integer
, float
, complex
, Quantity
, string
, date
, time
and
datetime
.