This readme file contains a description of the basic structure, as
well as a short summary of the components that make up the model.

Please take a moment to read this as it will help you understand the
various scripts that are necessary to run the FS network.

Contact information: 
Johannes Hjorth
hjorth@nada.kth.se

Contains:

1. Requirements
2. Basic structure
3. Explanation of parameters
  3.1 General parameters
  3.2 Input related parameters
  3.3 Morphology related parameters
4 MATLAB helper-scripts
5 GENESIS files

1. Requirements:

* MATLAB (2008b or later preferred)
http://www.mathworks.com/

* GENESIS 2.3
http://www.genesis-sim.org/GENESIS/

You will need GENESIS installed, and a .simrc file in your home
directory. Please see the GENESIS documentation for how to do that.

For those without access to a MATLAB licence it should be possible to
port the scripts to OCTAVE instead, as the syntax is very similar.

OCTAVE is available from, http://www.gnu.org/software/octave/

Some simulations run fast (minutes on my computer), but there are many
of the figures which require simulations to run for a very long time
(several days).


2. Basic structure

The scripts to generate the different figures are located in their
respective subdirectory. Located in the same directory as this
README.txt are readme-files for each figure, that give more specific
information on what to do in order to generate a figure.

To run a simulation a MATLAB script is first called, these files are
named runSomeSimulaton.m and are usually accompanied by two additional
scripts readSomeSimulationData.m and makeSomeKindOfPlot.m which are
located in the subdirectory of respective figure.

The run-scripts set the general parameters and write them to a file in
the INDATA subdirectory (located in respective article figure's
directory), GENESIS is then started by a system call from
MATLAB. Afterwards control is returned to MATLAB, and output files are
moved from UTDATA to a subdirectory of UTDATA/SAVED. The data-file
contains the time and soma voltages of the neurons, some simulations
have additional outputs. The info-file contains the parameters used to
run this specific simulation, which is quite helpful when you return
to old simulations and want to see for instance what kind of input was
used to generate the data. Only run one copy of MATLAB at a time,
unless the script explicitly states that it can be run in parallel.

Any figures generated by the read- or makePlot-scripts are saved in
the FIGS directory (located in respective article figure's directory).


3. Explanation of parameters

There are two types of genesis simulation scripts, those simulating
neurons driven by synaptic input and those simulating neurons driven
by current injection. MATLAB pregenerates input, morphology-files and
network connectivity before starting the simulation.


3.1 General parameters:

nReps      - Number of times the simulation is repeated. Each time it 
             runs with a different random seed set by the clock.

maxTime    - Specifies how many seconds the simulation will run for.

numCells   - Specifies how many FS neurons will be simulated



3.2 Input related parameters:

corrRudolph - This specifies how correlated the synaptic input to one
              neuron will be. This builds on the work of Rudolph and
              Destexhe, 2001. This is generally done using duplication
              of spikes, however there are some simulations that also
              use jittering of spike trains. Default value is 0.5, see
              methods section in the article (Hjorth et al 2009).

upFreq      - Input frequency per synapse. For some simulations there is
              also a downFreq to indicate the down-state frequency.
              Normally there is only upstate, standard values are in the
              range 1-4 Hz.

noiseFreq   - Additional input noise to the synapses.

allowVar    - Flag to indicate how duplication of spikes are generated.
              If set to 1, the number of duplicates will vary.
              If set to 0, there will be a constant number of duplicates 
              for each unique spikes (how many depends on corrRudolph).
              On average both will have the same number of duplicates of
              each spike, but the variation is different.


3.3 Morphology related parameters:

channelMask - This is a MATLAB cell-array with the names of the
              channels that should have their conductance varied to 
              generate an inhomogenous-population with different IF-curves.

cellVar     - Indicates how much each channel conductance should be varied.
              Eg, 0.5 means +/- 50%.

lenVar      - Indicates how much the length of each compartment should be 
              varied. If set to 0 there is no variation.



4 MATLAB helper-scripts

makeAllExternalInputAllUpstate

This script and others with similar names generate the input spikes
for the model. Each spike train is stored on file in the INDATA
directory and later read by GENESIS.


makeFSMorph

Generates the morphology p-files read by GENESIS, stored in the INDATA
directory.


makeFSrandomNetwork
makeFSconnectionMatrixOnlyPrimWrappedSetNGJ

The gap junctions are specified by two cell arrays of source and
destination compartments, as well as a vector with gap junction
resistance. You can set these variables by editing a file
(INDATA/parameters.txt), or you can let the MATLAB functions generate
them for you. You specify the number of neurons and the number of gap
junctions per neuron.


writeParameters

Writes information about simulation time, gap junction connectivity
and output file to INDATA/parameters.txt, read by GENESIS.




5 GENESIS files

simFsMultiInhomogene.g

This is the default GENESIS simulation script which is called by
MATLAB. There are a few variations of this main script, one that use
current injection instead of synaptic input, and another that in
addition to soma voltage also saves additional information to be able
to extract gap junction currents afterwards.


a_channel.g, k13_channel.g, k3132_channel.g, na_channel.g, 
ampa_channel.g, gaba_channel.g

Files containing the channels in the FS model, taken from original
model by Hellgren Kotaleski, Plenz, Blackwell, J Neurophysiol 2006.
These are included into the model by channels.g.


protodefsInhomogene.g

Creates the channel library and neuron morphologies, included by the
main GENESIS script.


fsConnect.g

Contains functions to connect FS neurons together by gap junction.
Also contains functions for adding GABA between neurons.


fsInputFromFile.g

GENESIS reads the synaptic input generated by MATLAB from file, this
script contains the functions necessary to do that.


fsInputInject.g

This file takes care of the current injections. This file is usually
not included in the synaptic input simulations.


fsNeuron.g, fsInhomogeneNeurons.g

Functions used to create the FS-neurons, including specifying how many
synapses there are on various compartments. Usually the inhomogenous
version is used.


fsSomaOutput.g

Used to send various data to file, easy setup of voltage outputs, but
can also handle custom messages.





*** Note that each FIG1,FIG2,...,FIGN-directory contains all the files
    necessary to run the simulations for that figure. I have choosen
    this modular design to make it easier to run the simulations for
    individual figures. Since the core GENESIS model is not changed
    between the figures, there are many identical copies of the
    g-files. Some of the figures share many common MATLAB scripts
    also, in those cases I have choosen to use a symbolic link to
    avoid too much duplication.