Basic Neuron object model docs, and workspace dump?

[gwideman]

Folks: I'm new to neuron, but quite old at programming, using command line interpretersetc . And I have taken at least a tour through the docs.

1. Could someone please point me to where in the docs I might find a list of the objects that can be created (ie: via the create command), and a listing of their attributes?

2. Once created, what ui features or other methods are available for showing the current population of objects (in the workspace, or whatever neuron's equivalent is called), and their attributes and values?

(I was rather hoping for a simple tree view, in which I could get feedback on the current structure of the workspace, navigate to a particular object, browse its attributes and possibly set them, and so forth... )

3. From Neuron main menu, if I load a hoc file, play with it, close that window and attempt to open another hoc file, nothing happens. I have to quit and start from scratch -- is this expected behavior or is some setting messed up?

Thanks, Graham

[ted]

Good questions. They are answered in the following chapters of The NEURON Book:
5. Representing neurons with a digital computer
6. How to build and use models of individual cells
12. hoc, NEURON's interpreter
13. Object-oriented programming
What follows is a brief summary that I hope will be useful while you wait for your order
to arrive (you did order it, right?).

1. Could someone please point me to where in the docs I might find a list of the objects that can be created (ie: via the create command), and a listing of their attributes?

A little history and terminological clarity will be helpful here.

hoc as defined originally by Kernighan and Ritchie was a simple interpreted language
that had some syntactical similarities to C and BASIC. Michael Hines added sections,
defined as unbranched cables, as a way to make it easy to specify models of neurons
one neurite at a time. Later, as programs became more complex, he added the ability
to define objects. It is an accident of history that sections and objects are declared
and managed with different syntax (there is, however, a SectionRef class which
allows sections to be referenced as normal object variables for assignment and
passing as arguments).

"Age before beauty," as they say, so let's focus on sections first.

create is used to create sections. section attributes include topology, geometry, and
biophysical properties of membrane and cytoplasm. For more information about
sections, see
http://www.neuron.yale.edu/neuron/stati ... ml#Section
Typing
topology()
at the oc> prompt will produce a "teletype-style" printout of the branching pattern of all
existing sections. The command
forall psection()
will produce a listing of all sections and an abbreviated summary of their geometrical
and biophysical properties--however, if parameters such as diameter or ion channel
densities are inhomogeneous along the length of a section, it may be desirable to use
sectionname for (x) print x, parameter(x)
to see more detail--read about
currently accessed section
http://www.neuron.yale.edu/neuron/stati ... sedSection
for (var) stmt
http://www.neuron.yale.edu/neuron/stati ... r.html#for
The GUI also has several tools for managing or monitoring the properties of sections.
The CellBuilder is perhaps the most powerful and convenient way to create sections and
specify their properties. The ModelView tool is very useful for discovering the properties
of a model (especially a model that was constructed by someone else, who may have
a very different programming style than one's own). You will find tutorials for these tools
on NEURON's Documentation page
http://www.neuron.yale.edu/neuron/docs
Also, every Graph has a PlotWhat? tool that is really a variable name browser--see
http://www.neuron.yale.edu/neuron/docs/pwt/pwt.html

Now for objects. Read this
http://www.neuron.yale.edu/neuron/stati ... n/obj.html
http://www.neuron.yale.edu/neuron/stati ... rogramming
and you'll be well prepared to deal with objects in NEURON.

2. Once created, what ui features or other methods are available for showing the current population of objects (in the workspace, or whatever neuron's equivalent is called), and their attributes and values?

(I was rather hoping for a simple tree view, in which I could get feedback on the current structure of the workspace, navigate to a particular object, browse its attributes and possibly set them, and so forth... )

The hoc functions
allobjects
and
allobjectvars
(see http://www.neuron.yale.edu/neuron/stati ... #functions)
print lists as you might expect.

ModelView presents a browsable outline of whatever currently exists, but it doesn't
let you specify attributes.

NEURON Main Menu / Tools / Point Processes / Managers / Point Group
brings up the The PointProcessGroupManager, which has a Show All button that
will reveal all instances of point processes. Click on any item in that list to examine
and modify its parameters.

3. From Neuron main menu, if I load a hoc file, play with it, close that window and attempt to open another hoc file, nothing happens. I have to quit and start from scratch -- is this expected behavior or is some setting messed up?

Sections at the top level are not destroyed by closing the window that created or
managed them. Objects may also persist if the "close" action does not destroy all
references to them. It is safest to exit and start anew.

It is possible to write one's own programs in such a way that loading a new hoc file
destroys whatever one had created previously. However, this requires that the new
hoc file contain statements that destroy all existing sections and user-created
objects. You also have to be careful not to redefine user-defined class specifications
(i.e. not to present hoc a template with the same name as one that was previously
parsed).

--Ted

[gwideman]

Ted:
First off, thanks for your detailed reply, containing lots of good tips, and no doubt taking some time to write. Much appreciated.

FWIW, no need to sell me on OOP -- been using OO languages, object models and data models for 20 years, and am very familiar with the rationales, which is what led me to ask for the basic tools which would permit me to leverage that background -- namely the docs on the object model of the neuron environment, for example as exposed to end users via hoc.

(And further FWIW, I have access to a copy of the NEURON book).

You reply leaves me still hanging on the following basic issues:

1. The doc for "create" at:
http://www.neuron.yale.edu/neuron/stati ... tml#create

... is not adequate to determine what it does. The syntax shows no arguments, and the description says "creates a list of section names". Why would one want to create names? My current guess, from your reply, is that it actually instantiates section objects and gives them them the names you supply as args? Not cleared up is whether create does anything different based on the names -- does "create soma" and "create axon" simply create two section objects that are identical except for name? Today's guess, yes.

2. Next, pursuing "what is a section object and what are its properties?" I looked in the programmer's ref for "section"... not there, though "Section-neuron" is (same link you provided as it happens). That link takes us to some descriptive narrative about what a Section is intended to represent, but no mention that it's the thing created by the create command. More prominently, it does not document what section's properties are. It's all very well that the narrative describes the intent, but within the neron/hoc environment, an object's salience is more or less defined by its attributes and the behaviors it can participate in (methods, or fucntions that can operation upon this object). But neither of these essential pieces are there.

3. Your reply directed me to two links regard OOP and OOP relating to oc. Good stuff, but all mentions of creating objects refer to the "new" keyword, and the "create" command is not mentioned. I'm guessing the two relate somehow, or at least there's some commonality in the behavior of template-defined (template = class data definition?) objects and create-instantiated objects?

4. Neither "create" nor "section" appears on the page:
http://www.neuron.yale.edu/neuron/stati ... l#keywords.

5. The chapters you mention:
The idea of "section" is used in a general way in the tutorial in Ch 1. Then in Ch 5 it's refered to some 200 times. But nowhere that I could find where section's properties are explicitly and exhaustively listed. Tables 5.1 and 5.2 are a start, but these convey that the listed items are a subset of all the properties.

(The narrative around Table 5.2 doesn't make it clear whether these are properties *of a section* or instead an orthogonal concept, given that it's under a subhead that appears to *differentiate* "Range and Range Variables" from "Section and Section Variables", though the some.diam example maybe suggests that range variables are section properties.)

6. You commented "Sections a the top level"... which suggests there's some kind of container hierarchy that's not yet evident to me. Again, something that would be instantly conspicuous on an object model, and all the more impetus to look for one.

--------------------------------------
Bottom line: I could spend a lot of time reverse-engineering this environment (ie: reading through the tutorials and poking around with umpteen examples and forum postings) so as to construct my own object model of the environment. But given that your team is so atuned to OOP, I was hoping that in the process of applying OOP to this environment you already had published an object model that would provide an instant orientation to what the "neuron object universe" looks like.

Anyhow, again thanks for your reply, and hopefully you see what I'm looking for.

Graham

[ted]

Please excuse anything that seems too pedantic, but the readers of this forum span
a wide range of expertise. A set of questions whose answers could be of equally wide
didactic benefit tempts a reply that is too detailed in some regards, and insufficiently
detailed in others. Sorry for the mismatch between what you asked and the answers
I gave.

1. The doc for "create" at:
http://www.neuron.yale.edu/neuron/stati ... tml#create

... is not adequate to determine what it does. The syntax shows no arguments, and the description says "creates a list of section names". Why would one want to create names? My current guess, from your reply, is that it actually instantiates section objects and gives them them the names you supply as args?

Your guesses are correct. Each newly created section has the same geometry and
biophysical properties--example:

Code: Select all

oc>create soma
oc>soma psection()
soma { nseg=1  L=100  Ra=35.4
        /*location 0 attached to cell 0*/
        /* First segment only */
        insert morphology { diam=500}
        insert capacitance { cm=1}
}

So now you see the default attributes of a section.

We're always looking for ways to improve the documentation. Questions such as yours
are very useful for pointing out where changes may be needed.

3. Your reply directed me to two links regard OOP and OOP relating to oc. Good stuff, but all mentions of creating objects refer to the "new" keyword, and the "create" command is not mentioned. I'm guessing the two relate somehow, or at least there's some commonality

At a "high conceptual level" (above the level of hoc!) a section is a kind of object, but
it differs from the kind of objects that are created by "new." Sections are NEURON's
counterparts to neurites; their properties are used to set up the discretized cable
equations that NEURON solves to simulate the spread of charge and potential in a
model cell. Objects that are created by "new", which are what the links on OOP pertain
to, are more like the usual objects that one encounters in other languages. This
dichotomy is an accident of the history of NEURON's development.

template = class data definition?

Yes.

nowhere that I could find where section's properties are explicitly and exhaustively listed. Tables 5.1 and 5.2 are a start, but these convey that the listed items are a subset of all the properties.

When a section is first created, it has a default length and diameter, and a limited set of
default biophysical properties. Additional biophysical properties can be assigned which
fall into two categories: density (or "distributed") mechanisms, and point processes
(localized sources of current, e.g. current or voltage clamps, synapses).

(The narrative around Table 5.2 doesn't make it clear whether these are properties *of a section* or instead an orthogonal concept, given that it's under a subhead that appears to *differentiate* "Range and Range Variables" from "Section and Section Variables", though the some.diam example maybe suggests that range variables are section properties.)

I thought the context made it pretty clear that range variables are section attributes,
but maybe not so. However, the first paragraph after Table 5.2 begins with this
sentence:

One way to access the values of range variables and other section properties is by
dot notation, which specifies the name of the section, the name of the variable, and the
location of interest.

6. You commented "Sections a the top level"... which suggests there's some kind of container hierarchy that's not yet evident to me. Again, something that would be instantly conspicuous on an object model, and all the more impetus to look for one.

One can use a template to define a class of cells. This is particularly useful for
network modeling. Each instance of such a class will have its own sections,
which are not at the top level but instead must be referenced within the context
of the object. Destroy the object and you also destroy its sections.

I was hoping that in the process of applying OOP to this environment you already had published an object model that would provide an instant orientation to what the "neuron object universe" looks like.

For a definitive answer to this, I must defer to Michael Hines.

--Ted

[gwideman]

Ted:
Thanks once again for your detailed reply. A couple of points:

> Additional biophysical properties can be assigned which
> fall into two categories: density (or "distributed") mechanisms,
> and point processes (localized sources of current,
> e.g. current or voltage clamps, synapses).

..... and the complete list of those is listed where?

I'm getting the impression you may be unfamiliar with what I am talking about when I refer to an object model. Pretty much every product that offers an automation interface on the Windows platform, and every component that's offered for the ActiveX, .Net or Java, organizes docs around an explicit object model.

At the least that means documentation that explicitly points out all the objects (actually classes) and their properties, methods and events (and properties that are collections giving rise to subsidiary branches). Every serious database I've worked with in the last 20 years likewise has a data model (essentially a class model but no methods or events).

Many of these are of course highly technical, but the MS Office Automation models are quite informative as examples because they feature objects that are recongnizable to users, and allow quick comprehension of how to script that application.

Here's an example of what that looks like for Word:

http://msdn.microsoft.com/library/defau ... 210580.asp

... where for example you can follow the "Documents" link to dig into the most recognizable part of the model, Document (where you find all of Document's properties and methods, albeit badly formatted it seems). Similar for Excel:

http://msdn.microsoft.com/library/defau ... 210580.asp

... and you can dig in to Worksheets.

(This overlaps with developer docs accessible via Help in each product, though MS keeps moving the exact location in each product's Help TOC -- grrrr.)

Anyhow, what I'm looking for is basically that same idea. Top object "Workspace" or somesuch. Has properties "CollectionOfSections" and "CollectionOfObjectsDefinedUsingTemplate" and (apparently) CollectionOfClassesOfCellsDefinedUsingTemplate.

Then each section object apparently has several default properties (nseg, L and Ra), plus a collection of optional properties added via the insert command, plus a collection of range-oriented properties. And the list of those optional properties is.... and so on until the picture is complete.

Hope that's clear.

Graham

[ted]

Thanks for the pointers to MicroSoft's documentation of object models,
but the fact that NEURON is user-extendable means that it is not
possible to have an exact equivalent of those lists--at least, not where
the properties of sections are concerned. However, the links mentioned
below will take you to roughly parallel material.

> Additional biophysical properties can be assigned which
> fall into two categories: density (or "distributed") mechanisms,
> and point processes (localized sources of current,
> e.g. current or voltage clamps, synapses).

..... and the complete list of those is listed where?

At present the standard distribution of NEURON includes the density
mechanisms described here
http://www.neuron.yale.edu/neuron/stati ... mechanisms
and the point processes described here
http://www.neuron.yale.edu/neuron/stati ... tprocesses
(of the latter, APCount, IntFire*, and NetStim are not current sources).

However, these lists are _minimal_--there is no "complete list" because
users can, and do, add their own definitions of new kinds of density
mechanisms and point processes. Literally dozens of these have been
used in published models, and are available upon request from the
models' authors, or downloadable from ModelDB
http://senselab.med.yale.edu/senselab/modeldb/
I should also mention that different users may employ the same name
for different mechanisms, or different names for what are essentially the
same mechanisms.

When you're examining a model that somebody else created, you may
have to do a little digging to discover what sections have which attributes.
The problem can be compounded by the fact that some users write
idiosyncratic code, and the possibility of complex initialization strategies
that actually modify model properties. There is no single tool that is
"best" for unraveling such complexities; a combination of the approaches
mentioned in my first message may be necessary.

Shifting the topic from sections and their attributes, to objects in NEURON,
let me mention the hierarchical outline
http://www.neuron.yale.edu/neuron/stati ... /hier.html
and in particular
Reference / neuron.exe
i.e.

Code: Select all

   Reference
       . . .
      neuron.exe
         general
            ObjectOrientedProgramming  functions  syntax  
            button-menu-panel  keywords   
            classes        predeclared-variables  
         neuron
            CompileTimeOptions  functions  keywords      
            Section        globals        mechanisms     
            classes        ion            pointprocesses  

The idea here is that everything that pertains to general programming
issues is under
Reference / neuron.exe / general
while things that are specific to modeling neurons are listed under
Reference / neuron.exe / neuron
So
Reference / neuron.exe / general / classes
brings us to links for documentation about things that include File, Graph, Vector etc.,
and
Reference / neuron.exe / neuron / classes
shows us links to documentation about KSChan, NetCon, SectionRef etc..

Anyhow, what I'm looking for is basically that same idea. Top object "Workspace" or somesuch. Has properties "CollectionOfSections" and "CollectionOfObjectsDefinedUsingTemplate" and (apparently) CollectionOfClassesOfCellsDefinedUsingTemplate.

If this question means "how do I discover what has been spawned
during a session, and what its attributes are?" then aside from what I
mentioned in my first posting on this thread, I can only suggest writing
code in a way that makes it easy to keep track of one's own objects.
You already know what these are, but for the benefit of other readers of
this exchange here's an example: when constructing networks I find it
helpful to make sets of cells using Lists, e.g. if Pyr5 is the classname
for layer 5 pyramidal cells, I create a List called Pyr5cells, and append
every instance of a Pyr5 cell to the Pyr5cells list.

--Ted

[gwideman]

Ted: Just a quick reply to say "thanks" and I'm still digesting. More later,

Graham