olfactory-bulb
==============

A detailed network model of the dual-layer dendrodendritic inhibitory microcircuits in the rat olfactory bulb comprising compartmental mitral, granule and PG cells developed by Aditya Gilra and Upinder S. Bhalla.
All cell morphologies and network connections are in NeuroML v1.8.0. PG and granule cell channels and synapses are also in NeuroML v1.8.0. Mitral cell channels and synapses are in native python.

#########################################################

The commit on 13th April, 2014 is the code for the paper:
"Bulbar microcircuit model predicts connectivity and roles of interneurons in odor coding"
 by Aditya Gilra and Upinder Bhalla, National Centre for Biological Sciences, Bangalore, India,
 which has been accepted subject to minor revisions by PLOS ONE on Mar 4, 2014.
Any queries may be addressed to Aditya Gilra: aditya_gilra at yahoo period com .

##########################################################

This code runs with MOOSE 1.4 beta downloadable at (see installation below):
http://sourceforge.net/p/moose/code/HEAD/tree/moose/branches/moose_Beta_1.4/
It has been used with svn commit 3207, but later commits on this branch should work too.

It has been used on Ubuntu linux 12.04 Desktop version,
 and on a cluster gulabjamun at NCBS, running CentOS release 5.2 (Final).

A simplified model to work with other simulators is under development.

##########################################################

Installation:

0. This code works on Ubuntu linux 12.04, CentOS 5.2, and hopefully other versions of linux. Windows and MacOS are unsupported.
    You will require a reasonable comfort in working with linux, python, make, etc. 
1. Get this model's code as per instructions (github, modeldb, etc).
2. You also need to install python 2.6 or 2.7 -dev packages and python modules numpy, scipy, matplotlib, mpi4py (via synaptic / manually).
3. Download MOOSE branch beta 1.4 from:
    http://sourceforge.net/p/moose/code/HEAD/tree/moose/branches/moose_Beta_1.4/
    The model code has been run with svn commit 3207, but later versions of this branch should run fine too.
    You can use the following command to download from svn:
    svn checkout svn://svn.code.sf.net/p/moose/code/moose/branches/moose_Beta_1.4 moose-code
    
    Then compile the pymoose version (not standalone version) and install as per instructions in the INSTALL file for this branch only.
    You will require packages libgsl0-dev, flex, bison, and possibly others mentioned in the INSTALL file. No need for libSBML, can set USE_SBML=0 as below.
    Typically this set of commands should work on Ubuntu 12.04 if you have all the required libraries:
    `cd moose-code`
    In Makefile and pymoose/Makefile, replace all occurences of 2.6 with 2.7 or whatever version of python your system has (with development files i.e. python-dev package).
    In older versions (<12.04) of Ubuntu, which use gcc 4.4 or 4.5, just `make pymoose USE_SBML=0` should work fine.
    But in Ubuntu 12.04 and above, which use gcc 4.6 and above, you need to make further changes as below:
    In Makefile, append -fpermissive to the CXX_FLAGS lines 127 and 131. Similarly in pymoose/Makefile, to line 27.
    `make pymoose USE_SBML=0`
    (In case you face some error and need to recompile after modifying say a Makefile, run `make clean` and `rm pymoose/moose_wrap.cxx` first.
    Also, after running `make pymoose USE_SBML=0`, if you face errors at linking stage, look at the full output above, some files in directories like GSL, or genesis_parser, etc. may not have compiled.
    You need to download the relevant libraries/packages and install them in that case, like libGSL0-dev, flex, bison, etc.)
    
    Finally tell python to look for the moose module in moose-code/python/
    export PYTHONPATH=<path-to-moose-code>/moose-code/python:$PYTHONPATH
    Confirm in a python terminal that `import moose` works fine.
    If not, check MOOSE compilation and ensure that your PYTHONPATH contains the python/ directory in the MOOSE code.
4. A lot of the simulation scripts use mpi for parallel farming of jobs and collation of the output.
    So you need some mpi library say openmpi on your cluster / desktop.

##########################################################

Running simulations:

In the top part of all runnable python scripts in various folders,
 you will find a number of suggested usage commands.
 they typically have `python2.6` in the command,
 but you can use just `python` as long as you have python 2.6 or 2.7 installed.

1. Simulating experimental electro-physiology on a PG cell model:
In a terminal (linux shell), cd to cells/ folder and run:
 python PGTest_mcquiston_katz.py PG2010
 After simulation, this should pop up figure 2H of the paper,
 showing electrophysiology of a plateauing PG cell.
 To get Figure 2G, for the low-threshold spiking PG cell, run:
 python PGTest_mcquiston_katz.py PG2013

2. Testing the synapses on a cell model
In a terminal (linux shell), cd to cells/ folder and run:
 python CellTest_synapses.py granule mitral_granule Iclamp 100 6e-3 staggered
 This will activate 100 randomly-chosen 'mitral-granule' synapses on a granule cell staggered 6ms apart,
 and will plot the resulting Vm trace showing the EPSPs, and resultant spiking.
 This is Figure 2F of the paper, showing summation of EPSPs in a granule cell.
 You can try other cells and synapses, Vclamp vs Iclamp, staggered vs simultaneous,
 and can specify a compartment name also for simultaneous (see top of script for usage examples).

3. Network simulations
For the network model simulation scripts in the simulations/ folder,
 you have to first generate the network model file,
 then generate 'firefiles' that contain Poisson spike trains as:
 (a) background for granule cells, and (b) as proxy for ORNs.
 Then you can run scripts from the simulations folder,
 but many of these still require a cluster.

An example not needing a cluster is provided below.
This shows backpropagation of action potentials along lateral dendrites despite strong local inhibition, as shown in Figure 2E of the paper.
15 Hz constant Poisson inputs as ORNs is provided to glomerular tufts of mitral cells A and B whose somas are 400 micrometers apart.
Simulated voltage recordings are shown on mitral cell B at the soma, near A and further away.

(a) In generators/stimuliConstantsMinimal.py,
    ensure below settings for generating the network file.
stim_net_seed = 100.0
mit_distance = 400.0 # microns ## irrelevant for odor responses

(b) In networks/networkConstantsMinimal.py
    ensure below settings for generating the network file.
NUM_GLOMS = 2

(c) In simulations/simset_activinhibition_minimal.py
    set the same seed and mitdistance as above in these lines:
netseedstr = "100.0"
mitdistance = 400.0 # microns
mitdistancestr = "_mitdist400.0" # microns
    Also ensure these parameters:
ASYM_TEST = False
REVERSED_ADI = True
IN_VIVO = True
ODORINH = True
oninject_ext = 15.0 # Hz 
    You can also set which cell populations should be simulated or not in the same file:
NO_SINGLES = False
## spine inhibition and singles are self-inh
## toggle them on/off together
NO_SPINE_INH = NO_SINGLES
NO_JOINTS = False
NO_MULTIS = NO_JOINTS
NO_PGS = False

(d) Below directories are not tracked on github and not part of the online modeldb code,
    but needed for the odor morph simulations.
    Please create them (using mkdir or in a file browser), if running for the first time:
    netfiles/, firefiles/firefiles_baseline/, firefiles/firefiles_constrate/, figures/connectivity/cells/
    (e.g. first firefiles/, then firefiles/firefiles_baseline as nested above.)

(e) in generators/ folder run the following commands in a terminal
    (i) generate network file:
    python generate_neuroML.py 2GLOMS
    (ii) generate the background input spike trains to granule cells
    python generate_firefiles_gran_baseline.py noresp
    (iii) generate the receptor (ORN) spike trains at various constant rates for different glomeruli
    python generate_firefiles_constantrate.py

(f) in simulations/ folder run the main simulation command in a terminal
    python inhibition_tuftinput.py
    This can take 5-10 min to run.
    Various plots will come up: firing rates of a few of the interneurons in different colours, Vm-s of the mitral cells A and B. 
    Figure 2E of the paper will be saved as ../figures/connectivity/cells/mitral_spikeprop.png.

##########################################################

Here is a list of directories and what they contain:

channels/
contains various channels as NeuroML 1.8.0 files,
however channels for the mitral cell are individual python class files.
There is a helper utility that loads all these channels into MOOSE path '/library',
 from where they may be deep copied under each compartment of each cell and connected via messages.
 For just running the scripts or loading models, you don't need to bother about this.

synapses/
contains various synapses as NeuroML 1.8.0 files,
however synapses for the mitral cell are individual python class files.
There is a helper utility that loads all these synapses into MOOSE path '/library',
 from where they may be deep copied under each compartment of each cell and connected via messages.
 For just running the scripts or loading models, you don't need to bother about this.

cells/
contains the three cell models i.e. morphology, channel distribution and potential synaptic locations as
single Level 1, 2 and 3 NeuroML 1.8.0 files.
The relevant files are:
mitral_bbmit1993davison_neuroML_L1_L2_L3_mod_withspikeinit.xml  --  mitral cell 286 compartments
PG_aditya2013unified_neuroML_L1_L2_L3.xml  --  low-threshold firing PG cell 3 compartments
PG_aditya2010unified_neuroML_L1_L2_L3.xml  --  plateauing PG cell 3 compartments
granule_granadityaMS2007_neuroML_L1_L2_L3.xml  --  granule cell 2 compartments
There is a helper utility load_cells.py that loads all the cells into MOOSE path '/library'.
 from where they may be deep copied when generating the network.
 For just running the scripts or loading models, you don't need to bother about this.

generators/
contains scripts for generating the NeuroML 1.8.0 full network in netfiles/ folder
 based on various connectivity parameters specified in networkConstants.py in networks/ folder.
contains scripts for generating the firing rate files in generators/firerates/ folder
 that contain the firing rates needed for (a) background granule input, (b) proxy for ORNs.
contains scripts for generating 'firefiles' in firefiles/ folder
 that contain Poisson spike trains required for (a) background granule input, (b) as proxy for ORNs.
stimuliConstants.py contains various 'constants' / stimulus parameters for the model,
 the ones that need to be changed for different runs in the paper are usually in stimuliConstantsMinimal.py .

netfiles/
contains the NeuroML 1.8.0 files generated by generate_neuroML.py in the generators/ folder.
 Currently empty as it's too huge to be distibuted.

networks/
contains a script OBModel.py that loads the NeuroML model generated above
 and connects the various stimuli generated above to the requisite cells.
networkConstants.py contains various 'constants' / model parameters,
 the ones that need to be changed for different runs in the paper are usually in networkConstantsMinimal.py .

simulations/
contains the scripts to run the various simulations:
 activity dependent inhibition: in vitro and in vivo
 odor morphs for decorrelation between sister cells and linearity in respiring responses
 odor pulses for linearity in odor pulse train responses.

results/
 has subfolders ADI, tuftADI, odor_morphs, odor_pulses to save results
 from the various simulations run by scripts in the simulations folder.
 For different simulation parameters, you may want to rename/copy the results folders to avoid overwriting.
 This is empty because it is too large to distribute.

analysis/
These require extensive sets of simulation results (running over a day to a month) in the results\ folder
 to be analysed and made into various figures in particular Figs 4-8 and S2-S7.
 I have these results, but being huge (~3 GB), I have not uploaded them on modeldb/github.

neuroml/
Some *.xsl to use xslt to transform neuroml files to .x3d files for viewing using standard 3d viewers.
First use neuroml_merge_cells.py on a 'netfile' to get netfile that has the cell morphology built-in
 and then run xslt to convert to x3d.

nml2/
a passive model of the mitral cell converted to NeuroML 2.

other folders are odds and ends -- not needed directly for the model.