opensourcebrain/miglioreetal14_olfactorybulb3d

3D model of the olfactory bulb (Migliore et al. 2014)

Migliore et al. (2014) 3D Model of the Olfactory Bulb

This repository hosts the NeuroML conversion of the Migliore et. al. (2014) model of the olfactory bulb. The original NEURON model has 125 glomeruli, 625 Mitral cells (MCs), and ~125,000 Granule cells (GCs). This project converted the original model channels, cells, synapses, network connectivity, and odor input into NeuroML format. Each converted component has been individually validated by comparing their responses to the original versions. The conversion error of the channels and synapses is <1%, while cell and network conversion error is <5% (see Validation below). Scaled down network model (5 MCs) is hosted in this repository, while larger versions can be obtained via the export scripts (see Exporting below). Click here to view an interactive visualization of a 5 Mitral and 10 Granule Cell Network

Original Model: Migliore M, Cavarretta F, Hines ML, Shepherd GM (2014) Distributed organization of a brain microcircuit analysed by three-dimensional modeling: the olfactory bulb Front. Comput. Neurosci. 8:50, obtained from ModelDB.

3D rendering of the converted network consisting of 30 Mitral cells

Overview

Stimulation of a single Mitral cell and the response of its Granule cells

Model Structure

Network

The original model depicts a small patch of the mammalian olfactory bulb, consisting of 125 glomeruli with 5 MCs each. Each MC is connected to several hundred GCs via dendro-dendritic synapses. Each GC connects to one MC. MCs are not connected to each other. Scaled down, NeuroML versions of the original model can be found in the NeuroML2/Networks folder.

Cells and Channels

Each Mitral cell has realistic morphology generated from statistical morphology distributions of reconstructed mammalian MCs. Each MC has a set of tufted dendrites originating in a glomerulus. The tufted dendrites are connected to a primary dendrite which descends down to a soma. From the soma, a set of branching secondary dendrites extend laterally and follow the ellipsoid surface of the olfactory bulb. MC axons are not included in the model. Mitral cells use Each MC has a set of Granule cells attached to its lateral, secondary dendrites. Granule cells have simple morphology consisting of a soma, a long primary dendrite, and a small spine which synapses with the parent MC secondary dendrite. GC morphology differs only by the length of the primary dendrite and the location of the spine. Both cell types use Hodgkin-Huxley-like nax, kdrmt, kamt, and passive current ion channels.

The converted MCs can be found in the NeuroML2/MitralCells folder while converted GCs can be found in the NeuroML2/GranuleCells folder. NeuroML versions of the channels can be found in the NeuroML2/Channels folder.

Synapses

Mitral and Granule cells are connected via dendro-dendritic synapses. Segments of the MC secondary dendrites connect to spines located on GC primary dendrites via the AMPA-NMDA excitatory synapses. A connection in the reverse direction from GC spines onto the MC secondary dendrites is formed by the Fast Inhibitory synapses. Both synapses implement spike-timing dependent plasticity, which strengthens the synaptic weights when incoming spikes have short inter-spike intervals, and weakens the weights when the intervals are long. The converted synapses can be found in the NeuroML2/Synapses folder. Networks that implement the above connectivity can be found under NeuroML2/Networks. The connectivity can be visualized via the OSB Explorer.

Input

Network input is provided by stimulation of MC glomerular tufted dendrites via double exponential synapses with peak current values taken from optical imaging odor maps of a mammalian olfactory bulb. The synapses have relatively long rise and fall time constants (50 and 200 ms respectively). Networks that implement the "Mint" odor of the original model can be found in the NeuroML2/Networks folder. Files in the folder that end with "OdorIn.net.nml" implement odor stimulation, while other network files implement un-stimulated networks.

Conversion Validation

Automated Comparison Suite

The NeuroML model was validated by comparing the output of the converted model to the output of the original model in response to identical stimulation protocols. Original and NeuroML channels were subjected to a voltage clamp protocol, cells were subjected to a current clamp protocol, synapses were subjected to a series of synapse-triggering network events, and networks were subjected to current injections into MC tufts. Networks that included odor input did not include any additional inputs. The results of the comparison tests are in the /tests/report.html file.

Code implementing these protocols can be found under the /test folder. Specifically, see protocols for: Channels, Cells, Synapses, Networks

A script that will perform the comparison tests for all model sub-components and networks can be found in /tests folder, and can be executed with the following command: python runsuite.py

Conversion error is a percent difference between the original and NeuroML output waveforms. Computed by sub-sampling the output waveforms to 1/ms and computing a point-by-point mean absolute difference between the original and converted waveforms. Percentage is the absolute mean divided by the min-max range of the output of the original model times 100. This measure is 0% when the output waveforms are point-by-point identical. The mean of the percentages for each stimulus in a protocol is the conversion error of the model. Because the measure is undefined if the original output values are all the same, stimulation protocols were chosen to show changing model output. The code implementing the error measure is defined in the compareTraces() method.

In general, the smaller scale components (channels, synapses) have the smallest error. Meanwhile, the errors propagate and become larger in components that utilize the smaller scale components (e.g. cells and networks). No fitting has been performed to reduce the propagated error. Additional reductions in error can be obtained by resolving identified issues (see Issues below).

Automated Unit Tests

This model also implements automated tests that ensure no breaking changes have been inadvertently introduced. They validate NeuroML models against NeuroML schema and verify that the spike times for the sub-models match the expected values. These tests run every time code is checked into this repository.

The following image, if shows "passing", indicates that these automated tests did not detect any issues with the NeuroML models.

How to Download and Use the Converted Model

Folder Organization

• NEURON_FULL: This is the original, unmodified NEURON version of the model, obtained from ModelDB and from personal correspondence with the model authors.
• NEURON: This is the original model modified to allow exporting arbitrarily scaled-down version of the model (e.g. fewer MCs and GCs), and to allow switching of synaptic and odor inputs. No other modifications have been made to the model.
• NeuroML2: The subfolders store the NeuroML versions of the model.
• Python: Scripts used for exporting original model components to NeuroML.
• tests: Contains the automated comparison test suite that generates a report indicating the percent error differences between the original and converted models.

Running a simple model

Requirements

• git
• NEURON simulator
• jNeuroML

Steps

1. Clone this repository in a path that does not contain spaces: git clone https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D.git
2. Change into the cloned folder: cd MiglioreEtAl14_OlfactoryBulb3D/
3. Change into one of the sub-folders of NeuroML2 e.g. cd NeuroML2/Networks
4. Tell jNeuroML to run one of the LEMS files that define the simulation to run: e.g. jnml LEMS_1MC_1GC_Odor.test.xml -neuron -run
5. This will run a simple 1MC-1GC model stimulated by odor input. You should see NEURON simulator and plots showing the result

Use the steps above to run other models defined in other LEMS*.xml files.

Network Visualization

Scaled down networks in this repository can be visualized via the web using the OSB Explorer by clicking on one of the Networks listed under the OSB Project Models tab.

The models can be visualized offline by converting the model to NEURON (see steps above) and using the built in ModelView tool.

Running full comparison suite

Requirements

• The steps below have only been tested on Ubuntu Linux. They may work on Mac OS. Unlikely to work on Windows due to path issues.
• A simple model from above is able to run
• NEURON compiled with Python 2.7 (e.g. the following command works python -c 'from neuron import h, gui')

Steps

1. Change into tests directory cd tests
2. Run the following python command python runsuite.py
3. The tests listed in runsuite.py should run and a report showing the original and converted model output should open.

Exporting models

NeuroML versions of network models with arbitrary numbers of Mitral and Granule cells (up to the counts in the original model) can be created via the use of the export script.

Requirements

• All the above, plus:
• pyNeuroML

Steps

1. Change to the Python/Export folder: cd Python/Export
2. Run the following command python -c 'import export_network; export_network.export(MCs = 5, GCsPerMC = 2)'
3. This will create a network that includes 5 MCs and 10 GCs (5x2) and uses odor input. The network will be created in /NeuroML2/Networks/ folder.
4. You can use the other parameters in the table below to customize the export.
5. To use the network in a simulation, copy and modify one of the LEMS*.xml files in the NeuroML2/Network folder to utilize the newly exported network. Then use the steps to run a simple model above to run the simulation.

Parameter	Default	Description
MCs	30	The number of Mitral cells to include in the network
GCsPerMC	3	The number of Granule cells to include for each Mitral cell
useOdorInput	True	Whether to use odor input into Mitral cell tufts. False generates a network without inputs.
odorInputMaxTime	200	The maximum time of odor network events that trigger the odor synapses. This should be <= your intended simulation time.
export_cells	True	False will only export the network, but will not export the cells. Saves time if the cells have already been exported.

Issues

The conversion error of the model can be further reduced by resolving identified issues. If you find additional problems or issues, please create a Github issue at the issues page.

Reusing this model

The code in this repository is provided under the terms of the software license included with it. If you use this model in your research, we respectfully ask you to cite the references outlined in the CITATION file.

miglioreetal14_olfactorybulb3d's Issues

GCs do not appear to have position information

From #6

@JustasB it could well be the case that the GCs are not given explicit positions, though it does look like it from the movie here

They may be just randomly positioned inside the main ellipsoid, but this code suggests otherwise...

Note though that there is a dendrite on the GCs which isn't shown above.

Does the connectivity depend on the location of the GC?

Would be good to get Francesco to comment on this.

Synapse conditional NET RECEIVE logic introduces delays

Currently, LEMS does not appear to support conditional logic within the tag. However, both the FI and NMDA synapses in the original NEURON code use conditional logic to set synaptic plasticity.

Currently, the logic is implemented by the use of "isSpiking" state variables and conditional logic is handled with "OnCondition" blocks.

However, this logic is executed on the next time step, resulting in a slight delay (and subsequent error propagation) when the synapse is used in a network.

Ideally, LEMS would be modified to support conditional logic in the OnEvent blocks.

Visualise/verify network connectivity as exported in NML2

Issue OpenSourceBrain/redmine#245 should be resolved now...

First requirement with all of this is making sure the network is valid... Could you commit an example of the exported network if you're still having problems @JustasB?

Add channel density specifications in export_mitral.py

As opposed to using chan densities etc. exported from Neuron directly, manually create the chan density elements in export_mitral.py. Will lead to neater cells once #2 is complete.

Info on biophys in https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NEURON/mkmitral.py etc.

See using libNeuroML to specify channel densities etc. here: https://github.com/OpenSourceBrain/AllenInstituteNeuroML/blob/master/CellTypesDatabase/models/ParseAll.py#L128

See example of cell in nml2 here: https://github.com/OpenSourceBrain/ACnet2/blob/master/neuroConstruct/generatedNeuroML2/pyr_4_sym.cell.nml

Resolve issue of disconnected axon hillock

Each mitral cell has an axon hillock/initial segment which is not located near the cell soma:

3D view

These could potentially be relocated/rotated to the correct location when the cells are converted to NML2.

Create smaller scale version of network that can run on single processor

Reuse existing scripts to create a smaller scale version of the network (e.g. with a single glomerulus and reduced numbers of granule cells) that can be run (~100ms) on a single processor.

Will greatly facilitate testing & export of network structure to NML2 (#6)

Adding license info

@JustasB I'm adding license info to a few of the OSB repos. Hope you don't mind if this is released under MIT license. Note the added point there (and in CITATION.md) that the code in the NEURON folders has the added requirement that the original ModelDB entry should be cited too if someone uses that code.

Implement helper method for converting fraction along segmentGroup to fraction along segment (with id))

As mentioned in #6 (comment), NEURON represents connection locations as fractions along named segmentGroups (NEURON sections), whereas NML requires these to be represented as fractions along segments. The other way is not possible in NML2, since segmentgroups are not necessarily continuous or unbranched, so fraction along doesn't make sense in general.

In this case the best way to do the conversion is probably with a helper method in Python that takes as arguments the cell (Cell class in libNeuroML), the segmentgroup id, the fraction along this, and returns the segment id & fraction along this. To speed things up it would be good to calculate the dict for (segmentgroup name) vs (ordered list of floats of the lengths of the contained segments), and return this too. There could be an optional argument for this dict in the helper method & this value could be cached per cell & given at the next call so it doesn't have to be recalculated.

If this is implemented in this repo it can be moved eventually to libNeuroML (or pyNeuroML).

Export network structure to NML2

Create scripts to export a smaller scale version of the complete network to NML2.

Ensure valid & can be loaded in OSB 3D Explorer,

Test with progressively larger versions of the network.

Channel initialization contributes to conversion error

Channels can be further improved by addressing differences in initialization. See the first few ms of the following comparison plots:

OMV: Test Mitral cell across multiple inputs & compare to NEURON

There used to be tests for the Mitral cell across 3 iclamp input values running in the OMV test, but these have been removed:
850cc45#diff-a6024a827832eb142c4c1dfc7fa749d4

Also, the NEURON OMV tests seem to be gone: https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/1f829a66ab4ffee303c279304f1cd9876ff030d9/NEURON/.test.mitral.omt

It's great having the graphical comparison between the 2 versions (I've managed to get it rerun locally), but would it be possible to incorporate these OMV tests too, so they get ran every time there's a commit?

Convert channels to NeuroML 2 for use in exported cell models

Conversion of a number of ion channels (including these) from olfactory bulb models under way here: https://github.com/OpenSourceBrain/OlfactoryTest

Export or create NML2 cell file(s) for granule cell

While Mitral cells are all different, it seems that the GCs are all the same (but probably positioned at different locations, see #12)

If they are all the same, a single GC.cell.nml should suffice, otherwise the export script should be updated to handle these too.

Re the question here: #6 (comment), the numberInternalDivisions is equal to nseg, which can be set to any integer value >=1 independent of the number of points in the NEURON segment (which translate to segments in the segmentgroup in the exported NML). Usually for, e.g. a neurolucida reconstruction there will be many 3d points (~20) in a section, but only ~3 points required to evaluate v along it, so nseg =3.

In the generated Mitral cells the number of 3D internal segments in the generated sections == nseg, probably just for convenience/a good approximation. This doesn't necessarily hold for the GC... Note this in the definition of GC: https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NEURON/granule.hoc#L61

Python 3

Has anyone previously converted this project to Python 3? If not, I'd like to work on it.

cell with multiple specificCapacitances OR directly connect segments of different cells together

In this model, there is one hoc definition for granule cells and one for GranuleSpine. Instances of each are later connected together directly at a specific location along a segment of the GC. The GC has cm of 4 and Spine has cm of 1.

In NeuroML, I cannot find a way to have a cell have more than one specCap value, nor can I find a way to connect segments of different cells directly either. @pgleeson What's the best route here?

Both definitions are in this file: https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NEURON/granule.hoc

The direct connection is made here:

MiglioreEtAl14_OlfactoryBulb3D/NEURON/mgrs.py

Line 110 in c15d316

self.spine.neck.connect(self.gpriden(xg))

Rename groups in exported cells

Group names generated during export from NEURON should be renamed to standard ones (soma_group, dendrite_group, axon_group), e.g. ModelViewParmSubset_4 -> dendrite_group in https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NeuroML2/Mitral_0_0.cell.nml

Can infer correct group from names of included, e.g. all XdenX => dendrite_group, hillock + initialseg => axon_group etc.

Can use libNeuroML during reload/write here: https://github.com/OpenSourceBrain/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NeuroML2/export_mitral.py

Create NML2/LEMS versions of synaptic mechanisms

Following on from question in #6, there should be 2 synaptic connections per NEURON connection in the NML2 file if there is a functioning NetConn each way between the "pre" & "post" connection points.

@JustasB which mod file(s) are used for the synapses? This? If so have a look at this LEMS file which could be adapted from this combined AMPA/NMDA file. Making a combined synapse in LEMS like this would be slightly easier than repeating each connection with one AMPA and one NMDA in pure NML2.

Mitral cells are not translated correctly when positioned via the network location tag

Described here: NeuroML/jNeuroML#55

Currently, the cell sections are positioned within the cell files and not via the network. Once the above issue is resolved, the following code can be uncommented:
https://github.com/JustasB/MiglioreEtAl14_OlfactoryBulb3D/blob/master/Python/Export/export_network.py#L73

Python scripts for exporting Mitral/Granule cells should be (re)added

Add test script for creating and running one Mitral cell in NEURON

Reuse existing scripts to load & create a single mitral cell & test with current clamp stimulation.

• Add python script
• Save trace for soma voltage
• Add OMV test
• Compare to NML2 version with current injection

running jnml -netpyne results in error related to non0-1 parentFractionAlong

Granule cells have several segments with parentFraction along being non 0 or 1.

For example: https://github.com/JustasB/MiglioreEtAl14_OlfactoryBulb3D/blob/master/NeuroML2/GranuleCells/Exported/Granule_0_110821.cell.nml

When they are included in a LEMS file, running the netpyne converted .py file results in the following error:

in: netpyne\neuromlFuncs.py, 810

fract = float(seg.parent.fraction_along)
assert(fract==1.0 or fract==0.0)

It appears to be related to these two fractionAlong issues: NeuroML/org.neuroml.export#46
NeuroML/pyNeuroML#22