Update/examples

bmtk/simulator/bionet/__init__.py

@@ -26,3 +26,33 @@
 from bmtk.simulator.bionet.bionetwork import BioNetwork
 from bmtk.simulator.bionet.biosimulator import BioSimulator
 from bmtk.simulator.bionet.nrn import reset
+
+import sys
+import argparse
+import copy
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    """A Helper class for using argparse when calling script through nrniv, eg
+      $ nrniv -python run_bionet.py
+
+    or
+      $ mpirun -np 2 nrniv -mpi -python run_bionet.py
+
+
+    """
+    def parse_known_args(self, args=None, namespace=None):
+        if args is None:
+            args = copy.copy(sys.argv)
+        args = ArgumentParser.parse_nrniv_arg(args)[1:]
+
+        return super().parse_known_args(args, namespace)
+
+    @staticmethod
+    def parse_nrniv_arg(sys_argv):
+        if sys_argv[0].endswith('nrniv') or sys_argv[0].endswith('nrniv.exe'):
+            for i, cmd_opt in enumerate(sys_argv):
+                if cmd_opt == '-python':
+                    return sys_argv[i+1:]
+        else:
+            return sys_argv

examples/README.md

@@ -1,59 +1,115 @@
 # Examples
 
-This is the examples directory for the Brain Modeling Toolkit (bmtk) software package. Here you will find examples of
-how to build, simulate, and plot simple brain network models of a variety of different levels-of-resolution using 
-bmtk. These examples are toy models for demonstration of how to use bmtk capable of running on a laptop/desktop 
-machine (for some examples of scientifically developed models that run on bmtk please see the following link: 
-https://alleninstitute.github.io/bmtk/examples.html).
+The following directory contains examples of running various parts of the Brain Modeling Toolkit (BMTK), including all the necessacary files to build a network, simulate it with one or more types of stimulation, and record and plot results. Each directory highlights a different type of model or a different features available in BMTK. 
 
+The majority of the examples are small toy examples that can be readily ran on most laptops or desktops. The minimum they requires BMTK, but depending on the module may have additional requirements.
 
-### BioNet (biophysically detailed) models
 
-Each ```bio_*/``` directory uses the BioNet simulator to run morphologically detailed network simulations using the NEURON
-simulation tool. 
+## Directory Structure
+
+Most of the examples have a prefix based on which simulation engine is being used to run the model.
+
+- **bio_\*/** - Examples of biophysically detailed network models that run using [BioNet](https://alleninstitute.github.io/bmtk/bionet.html). 
+- **point_\*/** - Examples of point-neuron network models that run using [PointNet](https://alleninstitute.github.io/bmtk/pointnet.html)
+- **pop_\*/** - Examples of populations based rates models that run using [PopNet](https://alleninstitute.github.io/bmtk/popnet.html)
+- **pop_\*/** - Examples that uses [FilterNet](https://alleninstitute.github.io/bmtk/filternet.html) to convert visual or auditory stimuli into spike-models based on spatio-temporal statistics.
+
+Other important directories
+
+- **bio_components/** - External files shared by BioNet models and simulations (Morphologies, parameters, etc.).
+- **point_components/** - External files shared by PointNet models and simulations
+- **pop_components/** - External files shared by PopNet models and simulations
+
+## Running Simulations
+
+### BioNet
+
+**(Prerequisite) Compiling NEURON mechanisms**
+
+The components for the BioNet examples are located in ../examples/bio_components. If the NEURON mechanisms have not already been compiled, the following should compile the NEURON mechanisms and place them in another folder in /mechanisms.
+
+```bash
+$ cd ../bio_components/mechanisms
+$ nrnivmodl modfiles 
+$ cd -
+```
+Failure to compile the mechanisms results in an error such as:
+```
+**Warning**:  NEURON mechanisms not found in ./../bio_components/mechanisms.
+              [...]
+              ValueError: argument not a density mechanism name
+```
+---
+
+
+To run a full simulation of the network on a single using the default simulation configuration, run the following on a command line:
+
+```bash
+$ python run_bionet.py
+```
+
+or to use a different SONATA configuration file (eg `<SONATA_CONFIG>.json`)
+
+```bash
+$ python run_bionet.py <SONATA_CONFIG>.json
+```
+
+If using a machine or cluster with mutiple cores you may use `mpirun` (if available on machine) to run the simulation in `N` cores with the following command:
+
+```bash
+$ mpirun -np <N> nrniv -mpi -python run_bionet.py <SONATA_CONFIG>.json
+```
+
+When simulation has completed it will create an *output* folder with logs, simulated spike trains, and any other recorded variables as set in the `<SONATA_CONFIG>`
+
+
+### PointNet
+
+Executing a simulation inside the model directory can be done in the command line using either
 
-```bio_components/``` contains external parameter and model files which are shared by most of the BioNet
-examples (note: this location can be changed in the each example's ```config.circuit.json``` file). This also includes
-a ```bio_components/mechanism/``` directory which require extra compilation for the Allen Institute models. To run 
-the BioNet examples one will have to run the following commands to compile the extra neuronal mechanisms:
 ```bash
-$ cd examples/bio_components/mechanisms
-$ nrnivmodl modfiles
+$ python run_pointnet.py 
 ```
 
-For more information on using BioNet see the following: https://alleninstitute.github.io/bmtk/bionet.html
+Which will run the default simulation configurations. Or to run a different simulation setup you can specify a specific `<SONATA_CONFIG>.json` file path:
 
-### PointNet (point-neuron) models
+```bash
+$ python run_pointnet.py <SONATA_CONFIG>.json
+```
 
-```point_*/``` directories contain examples that use the PointNet simulator to run point-neuron type models, including 
-Allen Institute's Generalized Integrate-and-Fire (GLIF) models. Using these examples will require installing the 
-NEST simulator. 
+If using a machine or cluster with mutiple cores you may use `mpirun` (if available on machine) to run the simulation in `N` cores with the following command:
 
-```point_components/``` directory contains model files that are shared by many of the different PointNet examples. This
-can be changed in each examples' ```config.circuit.json``` files.
+```bash
+$ mpirun -np <N> python run_pointnet.py <SONATA_CONFIG>.json
+```
 
-For more information on using PointNet see the following: https://alleninstitute.github.io/bmtk/pointnet.html
+When simulation has completed it will create an *output* folder with logs, simulated spike trains, and any other recorded variables as set in the `<SONATA_CONFIG>`
 
+### PopNet
 
-### PopNet (population firing rates) models
+Executing a simulation inside the model directory can be done in the command line using either
 
-```pop_*/```directories contain examples that use the PopNet simulator to run population level firing-rate model
-simulations. This requires installing the DiPDE simulator. 
+```bash
+$ python run_popnet.py 
+```
 
-```pop_components/``` directory contains model files that are shared by many of the different PopNet examples. This
-can be changed in each examples' ```config.circuit.json``` files.
+Which will run the default simulation configurations. Or to run a different simulation setup you can specify a specific `<SONATA_CONFIG>.json` file path:
 
-For more information on using PopNet see the following: https://alleninstitute.github.io/bmtk/popnet.html
+```bash
+$ python run_popnet.py <SONATA_CONFIG>.json
+```
 
+If using a machine or cluster with mutiple cores you may use `mpirun` (if available on machine) to run the simulation in `N` cores with the following command:
 
-### FilterNet (LNP) models
+```bash
+$ mpirun -np <N> python run_popnet.py <SONATA_CONFIG>.json
+```
 
-```filter_*/``` directories contain examples that use the PopNet simulator to run filter models simulations to convert
-visual stimuli into spike-trains.
+When simulation has completed it will create an *output* folder with logs, simulated spike trains, and any other recorded variables as set in the `<SONATA_CONFIG>`
 
-```filter_components/``` directory contains model files that are shared by many of the different FilterNet examples. This
-can be changed in each examples' ```config.circuit.json``` files.
 
-For more information on using PopNet see the following: https://alleninstitute.github.io/bmtk/filternet.html
+## Updating Simulation Parameters
 
+BMTK uses the *config.simulation_\*.json* files to determine simulation parameters like run-time, time delta, stimulus, recorded varaibles, and a number of other important factors. These are simple json files that can be edited with most text editors. 
 
+Please see our [BMTK User Guide](https://alleninstitute.github.io/bmtk/user_guide.html) or the [SONATA Developers Guide](https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md) for a description of the configuration format and a list of features and attributes available in BMTK.

examples/bio_14cells/README.md

@@ -1,50 +1,13 @@
-# 14 Cell network
+# 14 Cell Biophysical Network Model
 
-A small network of 14 cells - 10 multi-compartment biophysically detailed cells and 4 point integrate-and-fire cells -
-called V1. Recieves input from two networks of virtual cells (spike-trains) - LGN and TW.
+A small network of 14 cells; 10 multi-compartment biophysically detailed cells and 4 point integrate-and-fire cells, called V1. Recieves input from two networks of virtual cells (spike-trains) - LGN and TW.
 
-Uses the BioNet simulator (requires NEURON)
+**Requirements**
+- BMTK
+- NEURON 8.0+
 
-## Compiling NEURON mechanisms
-The components for the BioNet examples are located in /examples/bio_components. If the NEURON mechanisms have not already been compiled, the following should compile the NEURON mechanisms and place them in another folder in /mechanisms.
 
-```bash
-$ cd ../bio_components/mechanisms
-$ nrnivmodl modfiles 
-$ cd -
-```
-Failure to compile the mechanisms results in an error such as:
-```
-**Warning**:  NEURON mechanisms not found in ./../bio_components/mechanisms.
-              [...]
-              ValueError: argument not a density mechanism name
-```
-
-
-## Running:
-To run a simulation, install bmtk and run the following:
-```
-$ python run_bionet.py config.simulation.json
-```
-If successful, will create a *output* directory containing log, V1 spike trains and recorded cell variables.
-
-## The Network:
-The network files have already been built and stored as SONATA files in the *network/* directory. The bmtk Builder
-script used to create the network files is *build_network.py*. To adjust the parameters and/or topology of the network
-change this file and run:
-```
-$ python build_network.py
-```
-This will overwrite the existing files in the network directory. Note that there is some randomness in how the network
-is built, so expect (slightly) different simulation results everytime the network is rebuilt.
-
-## Simulation Parameters
-Parameters to run the simulation, including run-time, inputs, recorded variables, and networks are stored in config.json
-and can modified with a text editor.
-
-## Plotting results
-```
-$ python plot_output.py
-```
+## Running the Simulation
 
+[See Instructions for running BioNet Simulation](../README.md#bionet)
 

examples/bio_14cells/run_bionet.py

@@ -1,6 +1,3 @@
-"""Simulates an example network of 450 cell receiving two kinds of exernal input as defined in the configuration file"""
-import os
-import sys
 from bmtk.simulator import bionet
 
 
@@ -15,18 +12,9 @@ def run(config_path):
 
 
 if __name__ == '__main__':
-    # Find the appropriate config.json file
-    config_path = None
-    if __file__ != sys.argv[-1]:
-        config_path = sys.argv[-1]
-        if not os.path.exists(config_path):
-            raise AttributeError('configuration file {} does not exist.'.format(config_path))
-    else:
-        for cfg_path in ['config.json', 'config.simulation.json']:
-            if os.path.exists(cfg_path):
-                config_path = cfg_path
-                break
-        else:
-            raise AttributeError('Could not find configuration json file.')
+    parser = bionet.ArgumentParser(description='Run BioNet network simulation.')
+    parser.add_argument('config_path', type=str, nargs='?', default='config.simulation.json', help='Path to the SONATA configuration file')
+
+    args, _ = parser.parse_known_args()
+    run(args.config_path)
 
-    run(config_path)

examples/bio_1cell/README.md

@@ -1,56 +1,24 @@
-# 1 Cell network
-
-A single excitatory cell that is stimulated by current clamps or virtual synapses
-
-Uses the BioNet simulator (requires NEURON)
-
-## Compiling NEURON mechanisms
-The components for the BioNet examples are located in /examples/bio_components. If the NEURON mechanisms have not already been compiled, the following should compile the NEURON mechanisms and place them in another folder in /mechanisms.
-
-```bash
-$ cd ../bio_components/mechanisms
-$ nrnivmodl modfiles 
-$ cd -
-```
-Failure to compile the mechanisms results in an error such as:
-```
-**Warning**:  NEURON mechanisms not found in ./../bio_components/mechanisms.
-              [...]
-              ValueError: argument not a density mechanism name
-```
-
-
-## Running:
-To run a simulation using a current clamp, install bmtk and run the following:
-```bash
-$ python run_bionet.py config.simulation_iclamp.json
-```
-If successful, will create a *output_iclamp* directory containing log, V1 spike trains and recorded cell variables.
-
-You can also use the "virt" network which will use a virtual cell to stimulate the biophysical cell with synaptic
-stimulation.
-
-```bash
-$ python run_bionet.py config.simulation_syns.json
-```
-
-## The Network:
-The network files have already been built and stored as SONATA files in the *network/* directory. The bmtk Builder
-script used to create the network files is *build_network.py*. To adjust the parameters and/or topology of the network
-change this file and run:
-```
-$ python build_network.py
-```
-This will overwrite the existing files in the network directory. Note that there is some randomness in how the network
-is built, so expect (slightly) different simulation results everytime the network is rebuilt.
-
-## Simulation Parameters
-Parameters to run the simulation, including run-time, inputs, recorded variables, and networks are stored in config.json
-and can modified with a text editor.
-
-## Plotting results
-```
-$ python plot_output.py
-```
+# 1 Cell Biophysical Network Model
 
+An Example of a biophysical network containing a single biophysical morphologically detailed cell. The cell recieves stimuli either from a current clamp at the soma (using *config.simulation_iclamp.json*) or with synaptic stimuli using virtual cells with predefined spike-trains (*config.simulation_syns.json*).
+
+
+## Requirements
+- BMTK
+- NEURON 8.0+
+
+
+## Important Files
+
+- **inputs/** - folder contains pre-generated spike-train files use as stimuli for *config.simulation_iclamp.json*
+- **network/** - Folder containing network model.
+- **config.simulation_iclamp.json** - Configuration file with instructions for running network driven by current clamp stimuli attached at the soma.
+- **config.simulation_syns.json** - Configuration file with instructions for running network driven by virtual cells that synaptical stimulate our network.
+- **build_network.py** - script to rebuild the "network". WARNING: By default will override the **network/** folder.
+- **run_bionet.py** - Main script for running BioNet simulation of the network.
+
+
+## Running the Simulation
+
+[See Instructions for running BioNet Simulation](../README.md#bionet)
 

examples/bio_1cell/output_iclamp/spikes.csv

@@ -1,21 +1,21 @@
 timestamps population node_ids
 579.9000000001204 biocell 0
-2230.499999999449 biocell 0
-2119.499999999045 biocell 0
-2008.2999999988208 biocell 0
-1896.9999999989225 biocell 0
-1785.5999999990238 biocell 0
-1674.0999999991252 biocell 0
-1562.5999999992266 biocell 0
-1451.2999999993278 biocell 0
-1340.4999999994286 biocell 0
-1230.6999999995285 biocell 0
-1123.0999999996263 biocell 0
-1019.3999999997206 biocell 0
-922.0999999998093 biocell 0
-833.9999999998893 biocell 0
+2229.8999999994467 biocell 0
+2118.899999999043 biocell 0
+2007.7999999988217 biocell 0
+1896.6999999989227 biocell 0
+1785.299999999024 biocell 0
+1673.8999999991254 biocell 0
+1562.3999999992268 biocell 0
+1451.099999999328 biocell 0
+1340.2999999994288 biocell 0
+1230.5999999995286 biocell 0
+1122.9999999996264 biocell 0
+1019.2999999997209 biocell 0
+921.9999999998092 biocell 0
+833.8999999998894 biocell 0
 757.1999999999591 biocell 0
 691.400000000019 biocell 0
 633.7000000000714 biocell 0
-2341.4999999998527 biocell 0
-2452.300000000256 biocell 0
+2340.79999999985 biocell 0
+2451.7000000002536 biocell 0