The Pyloric Network Model Simulator

This pyloric network model simulator is a C/C++ program that saves 384 different calcium sensor values that are candidates for activity sensors (Gunay and Prinz, 2010). The simulator was used to scan all of the 20 million pyloric network models that were previously collected in a database (Prinz et al, 2004). See the Prinz Lab research page to learn more about the context of this research.

Description of parameter space and files

The simulation will start from one of the previously saved snapshots (snaps) of network state variables. The 20 million network models (Prinz et al, 2004) have been divided into sections of 50,000 models for naming files. This section number is prefixed to file names. For instance, the snapshots of network number 4950000 will be loaded from the file "100snaps.dat".

The snapshots provide state variables after the network reaches equilibrium. They are contain the network number at the beginning, followed by the dynamic variables of all the three neurons AB/PD, LP, and PY (in this format), and finally their synaptic weights:

netnum1 netnum2 netcode1 netcode2 ABPD_vars LP_vars PY_vars \
ABLP_syn PDLP_syn ABPY_syn PDPYsyn LPPMsyn LPPYsyn PYLPsyn

The complete network index number is obtained by multiplying netnum1 with 10,000 and adding to netnum2. The netcode1/2 variables describe the network architecture as a string where each character represents indices for model neurons and synapse strengths with the same order as in the snaps file.

The simulation will run for a few network periods, or a fixed duration if the activity is not periodic. The length of the run for a specific network can be controlled by the --period-mult option.

The resulting calcium sensor values will be saved in text formatted files named like *sensors_?.dat. If the --analyze-bursts option is given, activity characteristics will also be saved into *bursts.dat and *stats.dat files. Please see the source code, or contact us, to learn the order of elements in these files.

Activity traces for sensor, calcium concentration, and membrane voltage of all the three neurons will be saved in an HDF5 format binary file if requested with the --save-sensor-traces option and a file name is given with the -o option. HDF5 is a versatile and efficient file format that will let you visually browse and visualize its contents using the HDFView program. It can also be programmatically read from environments like C/C++, Matlab and LabVIEW. This simulator will not save individual ionic current traces.

The simulator can run in batch to simulate a number of network architectures based on the previous numbering of the network database. The requested networks should be listed in a TODO file using the --todo-num option. See below section on Running for more details and examples.

Download

The simulator source code can be downloaded from here.

Prerequisites

Install HDF5 libraries and utilities. For example, on an Ubuntu system, you can get them with the following command:

$ sudo apt-get install hdf5-tools libhdf5-serial-1.8.4 libhdf5-serial-dev

A Makefile utility like GNU Make and a C/C++ compiler like the GNU CC.

Compiling

Use the Makefile by running:

$ make

which should create the main simulator program "simulate-sensors-from-snaps".

To make a distribution ZIP file, use the "distzip" makefile target.

Usage

Usage can be requested by running the executable like this:

./simulate-sensors-from-snaps --help

Usage:
./simulate-sensors-from-snaps [-o filename.hdf5] [--work-dir directory] [--temp-dir directory ]
       [--sensors-dir directory] [--shots-dir directory] [--snaps-dir directory ]
       [-c|--compress=value] [--save-sensor-traces=value] [--period-mult=value]
       [--analyze-bursts=value] [--debug-level number] [--todo-num number]
       [--sensors-file filename] [--save-ca-avgs]

General options:
--debug-level: If 1, gives information about stages of processing;
               if 2, gives gory details of processing. If 0, silent operation (default=1).
-h|--help:     Prints this help.

Environment options:
--sensors-dir: Directory as final destination of sensor files (default=./).
--shots-dir:   Directory as final destination of shots files (default=./).
--snaps-dir:   Directory to find snaps files (default=./).
--temp-dir:    Directory to create sensor and shot files before copying back (default=./).
--work-dir:    Directory to find master.dat, XXXtodo and XXXlast files (default=./).

HDF5 options for outputting raw data:
-c|--compress: If 1, turns on compression in HDF5 datasets (default=1).
-o|--output:   Use filename as HDF5 output file to save membrane voltages. Existing network data is updated.
--save-sensor-traces:  If 1, saves all calcium sensor traces into the HDF5 file (default=0).

Simulation options:
--analyze-bursts: If 1, perform online analysis of the membrane voltage and
               produce bursts and network stats files (default=0).
--period-mult: Run the simulation this many times the default saved network period. (default=1).
--todo-num:    Process <number>todo.dat file instead of reading from master.dat.
--save-ca-avgs:        Append average values for [Ca], ICaS and ICaT in the sensor files. (default=0).
--sensors-file:        Read sensor parameters to simulate from this file in the above
               snaps directory (default=sensors.dat).

Running

I included a file, 100todo.dat, that contains a list of network numbers to simulate. You can pass this file to the simulator using the --todo-num command line option. The simulator will only simulate network numbers greater than what's found in the corresponding last.dat file (e.g., 100last.dat). You can initialize it with "0 0 0". For example, you can process the entries listed in the file 100todo.dat with the following command:

$ echo '0 0 0' > 100last.dat
$  ./simulate-sensors-from-snaps --todo-num 100
Simulation parameters:
----------------------------------------
Debug level=1
HDF5 file:<none>
Sensors dir:./
Snaps dir:./
Shots dir:./
Working dir:./
Temp dir:./
Compression=1
Save sensors=0
Period mult=1
Analyze bursts=0
Selected TODO file number=100
----------------------------------------

Found 354 sensors in sensor file sensors.dat.
Running shell command: mkdir -p ./
Found network 4959071 in todo file, checking last and snaps now.
Found a network newer than last and initialized variables.
...found network in snaps file.
savedperiod: 0.514483
Initializing sensor buffers..
Starting simulation for 0.514483 seconds..
Finished simulation..
and pretty much done

The simulator need the previously-saved network snapshots to initialize the simulations. It will abort if the snapshot corresponding to the selected network is not found in the *snaps.dat files. The total size for these files is about 30 GB and therefore cannot be part of this distribution package. I included 100snaps.dat that contain a limited number of networks starting from number 4950000.

To save the activity traces, you can run it like this:

$ ./simulate-sensors-from-snaps --todo-num 100 --save-sensor-traces -o test.hdf5

which will create the HDF5 file, test.hdf5. Please ignore HDF5 warnings as it creates new entries in the file. You can then use the HDFView program to browse the hierarchical structure inside the file and export or visualize its contents.

The network sensor database

The database resulting from 20 million runs of this simulator is available upon request. It exists as a MySQL database (http://www.mysql.com/). However, because its size is roughly 400GB, it cannot be directly downloaded. The MySQL server can be setup to be accessed externally. Please contact CG or Astrid Prinz <astrid.prinz AT emory.edu> to make arrangements to have access to this database.

References

Cengiz Gunay and Astrid A. Prinz (2010). Model calcium sensors for network homeostasis: Sensor and readout parameter analysis from a database of model neuronal networks. J Neurosci, 30:1686-1698, Feb 2010. doi:10.1523/jneurosci.3098-09.2010. NIHMS176368, PMC2851246.

Prinz A.A., Bucher D., Marder E. (2004). Similar network activity from disparate circuit parameters. Nat Neurosci 7:1345-1352.

-- Cengiz Gunay <cgunay AT emory.edu>, <cengique AT users.sf.net> (updated 2012/03/16)