Type annotation of NEURON objects

[jared]

I may have a misunderstanding, but I'm trying to type annotate for functions I have created that accept NEURON objects as arguments (SectionList, Section, etc.).

I'd assume it'd look something like:

Code: Select all

from neuron.h import SectionList, Section

def parentlist(section: Section) -> SectionList:
...

but that doesn't compute.

I'm sure the answer is simple, but it isn't obvious to me.Guess it's an opportunity to learn a little more about NEURON/python.
Any help is appreciated.
Thanks!

[urid]

If you type the following:

Code: Select all

from neuron import nrn
dir(nrn)

you can see which objects have their own classes. From this we can see that you can annotate the following types: sections, segments, and density mechanisms. All of the other types will show up as

Code: Select all

hoc.HocObject

because Python is just a wrapper for hoc code. So for your code, you can say

Code: Select all

from neuron import nrn
from typing import List
def parentlist(section: nrn.Section) -> List[nrn.Section]:
...

and you could have the function return a Python list of neuron sections. Otherwise, you would just have to leave the function type annotation as

Code: Select all

any

if I'm not mistaken.

[ramcdougal]

@urid's advice is good.

The development version (on linux: pip install neuron-nightly) provides types (and thus allows type annotation) for the different types of NEURON objects; e.g.:

Code: Select all

>>> import neuron
>>> neuron.__version__
'9.0a-336-g8e3de3305+'
>>> from neuron import h, hoc
>>> vec = h.Vector()
>>> type(vec)
<class 'hoc.Vector'>

but these are subclasses of hoc.HocObject so you can still use the less specific NEURON object class for your annotations if you need to support 8.x and 9.x:

Code: Select all

>>> isinstance(vec, hoc.HocObject)
True

[hines]

Types for built in hoc classes (eg. Vector, File, etc.) have been augmented with a HocClass metaclass in order to recover the HOC internal indexing for object indexing of classes that had been broken by the change to the development version mentioned by ramcdougal above . The original (up through version 8) behavior was

Code: Select all

$ nrniv -python
NEURON -- VERSION 8.2.5....
...
>>> from neuron import h
>>> v = h.Vector(range(3))
>>> v
Vector[0]
>>> type(v)
<class 'hoc.HocObject'>
>>> h.Vector[0]
Vector[0]
>>> h.Vector[0][2]
2.0
>>> 

The broken development version 9 version behavior was

Code: Select all

$ nrniv -python
NEURON -- VERSION 9.0a-335-g1d812c87a master (1d812c87a) 2024-09-04
...
>>> from neuron import h
>>> v = h.Vector(range(3))
>>> v
Vector[0]
>>> type(v)
<class 'hoc.Vector'>
>>> type(type(v))
<class 'type'>
>>> h.Vector[0]
Traceback (most recent call last):
  File "stdin", line 1, in <module>
TypeError: type 'hoc.Vector' is not subscriptable
>>> 

The latest master fixes this issue and now the behavior is

Code: Select all

$ nrniv -python
NEURON -- VERSION 9.0a-341-ge67effdd7 master (e67effdd7) 2024-09-16
...
>>> from neuron import h
>>> v = h.Vector(range(3))
>>> v
Vector[0]
>>> type(v)
<class 'hoc.Vector'>
>>> type(type(v))
<class 'hoc.HocClass'>
>>> type(type(type(v)))
<class 'type'>
>>> h.Vector[0]
Vector[0]
>>> h.Vector[0][2]
2.0
>>> 

There is definitely a possibility that we will extend the HocClass metaclass behavior to user defined hoc templates. Presently those exhibit the old version 8 behavior.