Note that when the "biophys" parameter in the nval.n file is set to 0, then retsim does not read the dens_xxx.n file, and takes the "vstart", "vrev", "Rm", and "Cm" parameters from nval.n instead of a density file.

You can customize the density file using variables instead of numbers in the columns, for example, in the listing below, "drm" means use the default value of Rm preset by retsim. When retsim reads the numbers from the density file, it looks up any variables in the symbol table and replaces the variable with its numeric value. This means that you can use any variable, either predefined internally in the simulator (in retsim_var.cc), or defined in your experiment file, as long as the variable's value is defined before the density file is read. You can define the variable in the "defparams()" procedure, and you can set its value in the "setparams()" procedure or in the command line. The density file is read after this.

A typical dens.n file for retsim is:

# Default membrane properties (density) file
#
# Densities of currents for the cell's different regions (S/cm2).
#
#      DEND_DIST DEND_PROX SOMA HILLOCK AXON_THIN AXON  AXON_DIST VARICOS R9  R10 
#
0       R1      R2      R3        R4    R5      R6      R7      R8     R9     R10
#
_NA     0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    50e-3   0e-3   0e-3   0e-3  # Na2
_NA5    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3   0e-3   0e-3  # Na5
_NA6    35e-3   0e-3    0e-3    4e-3    4e-3    0e-3    0e-3    0e-3   0e-3   0e-3  # Na6
_NA8    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3   0e-3   0e-3  # Na8
_KDR    15e-3   0e-3    0e-3    15e-3   15e-3   20e-3   10e-3   0e-3   0e-3   0e-3  # K1
_KA     35e-3   0e-3    0e-3    35e-3   35e-3   0e-3    0e-3    0e-3   0e-3   0e-3  # K3
_KH     0e-3    0e-3    0e-3    0.09e-3 0e-3    0.8e-3  0e-3    0e-3   0e-3   0e-3  # K4
_SKCA1  0.12e-3 0e-3    0e-3    0.12e-3 0.00e-3 0e-3    0e-3    0e-3   0e-3   0e-3  # KCA4
_SKCA2  0.01e-3 0e-3    0e-3    0.04e-3 0.02e-3 0e-3    0e-3    0e-3   0e-3   0e-3  # KCA5
_BKCA   0e-3    0e-6    0e-3    0e-3    0e-6    0e-6    0e-6    0e-6   0e-3   0e-3  # KCA3
_CA_L   0.014e-3 0e-3   0e-3 0.014e-3 0.014e-3  0e-3    0e-3    0e-3   0e-3   0e-3  # Ca1
_CA_T   0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3    0e-3   0e-3   0e-3  # Ca5
_CAP    2e-7    0e-3    0e-3    1e-7    1e-7    0e-12   0e-3    0e-3   0e-3   0e-3  # CAPUMP
_CAE    0e-7    0e-3    0e-3    0e-7    0e-7    0e-12   0e-3    0e-3   0e-3   0e-3  # Caexch
_VST    dvs     dvs     dvs     dvs     dvs     dvs     dvs     dvs    dvs    dvs   # vstart
_VRV    vk      vk      vk      vk      vk      vk      vk      vk     vk     vk    # vrev
_RM     drm     drm     drm     drm     drm     drm     drm     drm    drm    drm   # Rm
_CM     dcm     dcm     dcm     dcm     dcm     dcm     dcm     dcm    dcm    dcm   # Cm
_CPL    cplam   cplam   cplam   cplam   cplam   cplam   cplam   cplam  cplam  cplam # cplam
_COL    green   blue    red     blue    blue    magenta yellow  gray   ltred  brown # color

Channel density file format

The "density file" (retsim/runconf/dens_xxx.n) defines the biophysical properties of a cell, region by region. Each column defines the biophysical properties of one region. The first (left) column of the density file is the name of the biophysical parameter, such as NA, KDR, or RM. These labels are the names of variables that have been set by default to have a value to index into the internal list of channel types. Some of the names, for instance, NA, KDR, KA, SKCA1, are aliases for other internal variables that contain the correct index number. The alternative internal values are in the last column, the comments to the right of the "#". The other columns (2-11) of the density file define conductance density values for each membrane channel type to be inserted into the cables and spheres of the model in the appropriate region.

The rows and columns of the density file can be in any order, and unused rows or columns can be deleted, because each column and row is indexed by the label at the top or left column, respectively. Any rows or columns undefined in the density file are set to zero.

You can tell the simulator to temporarily remove a row, for example, to remove a channel type from all regions in the cell, by redefining the variable to a value outside the allowable range of values. Or you can temporarily remove a region by redefining the variable to a value outside the number of regions. For example:

retsim --expt cell_vclamp --celltype dbp1 --dbp1_densfile dens_dbp1.n --KDR 99
or,
retsim --expt cell_vclamp --celltype dbp1 --dbp1_densfile dens_dbp1.n --R4 99

Temperature dependence

The channel conductances vary with temperature, but are defined by convention in the dens_xxx.n file at 22 deg C. you must be careful to define them correctly for the temperature at which you are running the model ("tempcel"). At run-time (see "celseg.cc"), the conductance densities specified in the dens_xxx.n file are converted to number densities (n/um2) by dividing by the channel's unitary conductance (dxxxu). If channel noise is set, this number density affects the amount of noise generated by the channels. If you set the unitary conductance to 1e-8, then the conductance density specified in the dens_xxx.n file (S/cm2) directly defines the channel number density (n/um2). The unitary contuctance is modulated by temperature (controlled by a Q10 "dqxxx" value, see "Channel statement" in ncman2.html), but its value is specified at 22deg C.

Other channel types

Region labels

Adding rows and columns to the dens.n file

Setting complam for regions

Setting color for regions

Channel parameter offset file "chanparams"

An entry in "chanparams" for the Na 1.2 channel type:

columns:        gca     gcb     gcaoff  gcboff  sb      dsgc    aii

#Na 1.2 channel parameters
Na2.offm:        0.001   0.001   0.001   0.001   0.005   0.0025  0.002
Na2.offh:        0.001   0.001   0.001   0.001   0.005   0.0025  0.002
Na2.taua:        1       1       1       1       1       1       24
Na2.taub:        1       1       1       1       1       1       24
Na2.tauc:        1       1       1       1       1       1       24
Na2.taud:        1       1       1       1       1       1       24

Connecting neurons

After the presynaptic arrays of neurons are generated, they are synaptically connected with an algorithm that for each presynaptic neuron connects it to a nearby postsynaptic neuron(s), and extends the presynaptic axon or the postsynaptic dendritic tree, if appropriate, to create a realistic anatomy. Realistic numbers of connections are generated, so that a postsynaptic neuron can receive synaptic connections from several presynaptic neurons, with multiple contacts if appropriate, and a presynaptic neuron can connect to several postsynaptic neurons if appropriate. For example, a bipolar cell receives synaptic contacts from several photoreceptors, but the nearest ones are most likely to make contacts.

One connection algorithm available in retsim calculates a Gaussian probability for making connections, so that each connection is made at random, yet the closest presynaptic neurons are more likely to connect. This allows two random arrays of neurons to be connected with Gaussian weighting functions relatively smoothly. The exact number of connections between a presynaptic and a postsynaptic cell can vary, but the average is closely controlled.

The type of connection algorithm used is specified by the type of presynaptic arbor and the the type of postsynaptic arbor. These properties are specified in the nval.n file as DENDARB and AXARBT. A value of 0 means non-branched, 1 means branched, and 2 means highly branched. When connecting a synapse to an unbranched postsynaptic dendritic tree, the postsynaptic tree is extended to generate more branches from the soma if the GROWPOST parameter for that synapse is set. A branched postsynaptic cell will extend new branches from its proximal dendrites. A highly branched postsynaptic cell will not grow branches but will allow synaptic contacts to be made if the presynaptic cell is within a criterion distance (MAXSDIST).

Trimming the unconnected neural arrays

After the neural arrays are generated and interconnected according to a connection algorithm, the neurons that didn't get connected are removed. This is necessary because the presynaptic circuit of a ganglion cell only extends typically 20-50 um beyond the ganglion cell's dendritic tips, yet precisely which presynaptic neurons are connected depends on the connection algorithm, as well as the original placement of the neurons in the presynaptic arrays.

During the synaptic connection procedure, for each neuron the numbers of presynaptic and postsynaptic neurons it connects to are totaled and saved in a table. Any neurons that don't connect to a postsynaptic cell are removed. The process is started by first checking the layer immediately presynaptic to the ganglion cell, i.e. the bipolar cells, and afterwards checking the more distal neurons, i.e. the photoreceptors.

To see all the neurons, even those that didn't get connected, you can set the parameter "remove_nconns" to 0, either on the command line or in the setparams() procedure.

Stimulus types

Stimuli can include voltage clamp, current clamp, and a variety of light stimuli such as spots, bars, sine wave gratings, etc. A special transduction element is available that voltage clamps the cell to which it is attached at a voltage specified by the stimulus intensity. When the stimulus procedure is called, the stimulus is added to a list that is run at the correct time during the simulation (i.e. during the "step()" procedure). To generate complex stimuli, for example a bar moving to/fro, a set of stimulus functions is available in "stimfuncs".

Record types

A variety of recording methods are available. An experiment can define a list of nodes to record from, either current or voltage. Light flux into a photoreceptor can be recorded, as well as the concentration of calcium or a neurotransmitter or second messenger. The recorded values can be stored into an array or file or plotted onto the video screen.

Several plotting functions are available to generate plots. Plots can include several traces, e.g. several recording points, and several of these plots can be displayed simultaneously on the screen. Each trace can have its own color and a label and units. Plotting functions are available for "voltage at a node", "synaptic release rate", or for displaying the voltage or some other parameter of a neuron as a color applied to the display of morphology.

Onplot procedure

An "onplot" procedure can be defined which runs automatically at plot time, i.e. when the plot traces are updated, controlled by the "ploti" variable. Although this procedure is not necessary (because the simulation can be run incrementally), it allows the simulation to run faster. For example, the onplot procedure allows a special procedure to compute some function of the neural circuit's responses. It also can be used to plot more complex functions, such as the color-coded voltage superimposed on the morphology. For the compiled version, the onplot procedure is defined by the "setonplot()" procedure.

Making movies

To make a movie, include "onplot_movie" in your experiment file, and call it at plot time, i.e. inside the "onplot()" procedure. At each plot step, it displays the voltage (or other parameter such as inactivation) of the membrane as a color code superimposed on the morphology.

You can look at the movie using the "vid" display, or you can generate separate frames using the "-P name" command line switch. This creates an individual PostScript file for each frame, which you can convert to another appropriate file format. Typically you will need to convert all the frames to a ppm format, then use "mpeg_encode" to create a movie.

You create the movie with a shell script like this:

#! /bin/tcsh -f
#
# make_movie script
#
ps2ppm100 $argv*.ps
movconvert -f "$argv"_ -n 2000
cp xxx_paramfile2 "$argv"_paramfile2
replace xxx "$argv" "$argv"_paramfile2
mpeg_encode "$argv"_paramfile2
rm "$argv"*.ppm

Since the vid display integrates the graphics input from the simulator, the frames it generates after the first do not contain static objects (calibration bars, etc) that should remain throughout the movie. The "movconvert" program accomplishes this integration in the movie for the frames in .ppm format. These are then read and converted to a standard movie format by "mpeg_encode". To view the movie in you can use "mplayer".

Compiling and linking the compiled version

The NeuronC API is defined in "nc/src/ncfuncs.h" and described in the NeuronC User's Manual. Each function call in "ncfuncs.h" replaces a statement in the interpreted version of NeuronC. The retsim script defines an array of neurons and connects them using these function calls. To see an example of source code for this compiled version, see the "retsim.cc" model in nc/models/retsim". The command-line switches for "retsim" are identical to those listed by "nc -h", but note that running "retsim" without arguments displays a list of simulation experiments and parameters. In addition simulation variables can be set from the command line.

The NeuronC API is incorporated into a static library called "libnc.a". This file is created in "nc/src" and must be linked with a neural circuit program such as "nc/models/retsim/retsim.cc". To link this library correctly you may need to set the "NC_HOME" variable in nc/models/retsim/makefile, either by setting it as an environment variable or by changing the makefile. The libnc.a library is created as a static library because as a dynamic library it reduces run-time speed.

The experiments defined for "nc/models/retsim" such as "expt_gc_cbp_flash.cc" are compiled to be dynamically linked to the "retsim" program at runtime, i.e. each experiment is compiled into a dynamic library, e.g. "expt_gc_cbp_flash.so". To allow this process of dynamic runtime linking, you must set the environment variable LD_LIBRARY_PATH or include the directory where the experiment ".so" file is located in (for Linux) "/etc/ld.so.conf". That will allow the runtime linker to find "expt_gc_cbp_flash.so"

(tcsh)  setenv LD_LIBRARY_PATH .
(bash)  export LD_LIBRARY_PATH="."

Another way to direct the dynamic linking process is to make a symbolic link from a file in /usr/local/lib to the experiment .so file in nc/models/retsim. The dynamic linker will identify the file because it starts with "lib_": ln -s /usr/local/lib/lib_expt_gc_cbp_flash.so expt_gc_cbp_flash.so

At the top of the "retsim.cc" script, there are several files included:

 #include "ncio.h"         // defines "ncfprintf()" for I/O to a C++ stream
 #include "ncfuncs.h"      // defines the C++ functions for the simulator
 #include "retcolors.h"    // defines the standard colors 0-15  
 #include "retsim.h"       // defines constants and functions for retsim.cc
 #include "retsim_var.cc"  // defines parameters and "setptrs()" which initializes them
 #include "ncinit.h"       // defines a null "setptrs()" in case it is not already defined
 #include "setexpt.h"      // defines "defparams()", "setparams()", "setdens()" and "runexpt()" for the experiment file

# NC_HOME = ~/nc

Compiling retsim on Mac OSX

# OSFLAGS = -DMACOSX

Parameter initialization

Defining an experiment

The retsim script is controlled by a set of variables that tell it which neurons to create and how to connect them. The variables are read from the default neuron parameter table, "nval.n", but are also set by an "experiment file", and from the command line.

Typically an experiment file defines the general form of the experiment. It directs retsim which cells to include in the model, what synaptic connections and biophysical properties they should have. Then the retsim script constructs the neural circuit model, and returns control back to the experiment file, which runs the experiment. The retsim script, either the interpreted ("retsim1.n") or compiled ("retsim.cc") version, is designed to be run with many different experiments. It is typically run with several script files which define the details of how to construct all the neurons and how to connect them. Many experiment files can be created to define different circuits or different experiment protocols.

Usually the experiment file allows parameters to change the details, i.e. the exact details of the neurons or their spacing, the size, frequency, or timing of a stimulus, or the exact form of the output plots. The idea is to minimize the number of different experiment files by selecting appropriate parameters to control their behavior.

An interpreted experiment file is written in the nc script language, and should contain the "setparams()" procedure, (and optionally the "setdens()" procedure), and "runexpt()" procedure, as explained below. The setparams() procedure sets the values of parameters, for example to control how the circuit is constructed. The "runexpt()" procedure sets up stimuli and plots, and runs the experiment using a "step" or "run" statement. A good way to start would be to take an existing experiment, e.g. "expt_gc_cbp_flash.n", and modify it to make a different circuit and/or experiment.

A compiled experiment file is written as a standard .cc file, then compiled and linked as a dynamically-linked library (in linux, ".so"). This allows the retsim script to select an experiment file at runtime instead of requiring that retsim be linked separately with each experiment file. A good way to accomplish this is to look in the "makefile" and modify an existing entry for compiling and linking an experment file.

defparams()   Defines the experiment and its parameters for command line.
	      This is called before the nval.n parameter file is read,
              so you can set a different nval file name here, or on
	      the command line. Also called before the "setvar()" 
              procedure sets variables from the command line. 
              
setparams()   Sets variables controlling construction of the circuit
              after the neuron parameter (nval) file has been read.
	      Called after defparams(), but before the density files
	      are read, and before construction of the neural circuit.

setdens()     Sets neuron parameters and variables modifying the 
	      channel densities after they have been read from the 
	      density files. Optional, called after densities have been
              read in, but before construction.

runexpt()     Runs the experiment. Fine tunes neurons, sets stimuli and plots.
              Called after circuit is constructed.

// The defparams procedure defines parameters needed by the experiment.
//  It is run before "setvar()" (which defines the parameters from the command line). 

void defparams(void)
{
  setptr("temp_freq", &temp_freq);
  setptr("ntrials",   &ntrials);
  setptr("dstim",     &dstim);
  setptr("sdia",      &sdia);
  setptr("stimtime",  &stimtime);
  setptr("minten",    &minten);
  setptr("scontrast", &scontrast);
}

// The setparams procedure sets parameters needed for construction of the circuit.

void setparams(void)
{
  make_rods = 0;
  make_cones= 1;        /* make cones, cbp, gc */
  make_ha   = 0;
  make_hb   = 0;
  make_cbp  = 1;
  make_gc   = 1;
  if (notinit(bg_inten)) bg_inten = 2.0e4;      /* background light intensity */
}

// The setdens procedure allows the user to modify channel densities read from the 
// density files. 

void setdens(void)
{
  if (!notinit(cone_cond)) setval(xcone,SCOND5,cone_cond);		// override synaptic val
  if (!notinit(ca_cond)) celdens[cone][_CA][R_AXON] bg_inten = ca_cond; // override Ca density, S/m2

}

// The runexpt() procedure sets up the experiment stimuli and plots, and
//  runs the experiment using "step()" or "run()".  

void runexpt(void)
{
   double temp_freq;

  if (notinit(stimtime))   stimtime = .10;       /* stimulus time */
  if (notinit(minten))       minten = bg_inten;  /* background intensity (for make cone)*/
  if (notinit(scontrast)) scontrast = .5;        /* intensity increment */
  if (notinit(temp_freq)) temp_freq = 2;

  dtrial = 1 / temp_freq;
  exptdur = dtrial * ntrials;

  plot_v_nod(ct=xcone,cn=midcone,n=soma,Vmin=-.037,Vmax =-.027,colr=cyan,"", -1, -1); /* plot Vcones*/
  stim_spot(sdia, 0, 0, minten*scontrast, start=t+stimtime,dur=dstim);
  step(dtrial);
}



Examples of how to run retsim

   nc     --expt gc_cbp_flash --ninfo 2 -d 1 -v retsim1.n | vid                       display the model
   retsim --expt gc_cbp_flash --ninfo 2 -d 1 -v           | vid 

   nc     --expt gc_cbp_flash --ninfo 2 -d 9 -v retsim1.n | vid                       display the nodes
   retsim --expt gc_cbp_flash --ninfo 2 --node_scale -3.05 -d 9 -v   | vid 

   retsim --expt gc_cbp_flash --ninfo 2 -d 9 -v   | vid -c > file.ps                  make .ps file.
   
   nc     --expt gc_cbp_flash -d 1 -R retsim1.n > file.pov                            display into povray format
   retsim --expt gc_cbp_flash -d 1 -R           > file.pov

   povray +h1000 +w1000 +ifile.pov +dx                                                generate image with povray

   nc     --expt gc_cbp_flash --mxrot 90 -d 1 -v retsim1.n | vid                      rotate, display the model
   retsim --expt gc_cbp_flash --mxrot 90 -d 1 -v           | vid 

   nc     --expt gc_cbp_flash --ninfo 2 --arrsiz 100 -d 1 -v retsim1.n | vid          limit model to 100 um
   retsim --expt gc_cbp_flash --ninfo 2 --arrsiz 100 -d 1 -v           | vid 

   nc     --expt gc_cbp_flash --ninfo 2 --n_cbp 1 --n_gc 0 -d 1 -v retsim1.n | vid    limit model to 1 bipolar
   retsim --expt gc_cbp_flash --ninfo 2 --n_cbp 1 --n_gc 0 -d 1 -v           | vid 

   nc     --expt gc_cbp_flash --ninfo 2 -v retsim1.n | vid                            run model, display plots
   retsim --expt gc_cbp_flash --ninfo 2 -v | vid 

   nc     --expt gc_cbp_flash retsim1.n > file.r                                      run model into data file
   retsim --expt gc_cbp_flash           > file.r 

   plotmod file.r | vid                                                                display plots from data file