~ COMPOSITE NETWORK/FIELD MODEL OF PARKINSON'S DISEASE ~

This code generates the key results figures shown in:

Kerr CC, Van Albada SJ, Neymotin SA, Chadderdon GL, Robinson PA,
Lytton WW (2013). Cortical information flow in Parkinson's disease:
a composite network/field model. Front Comput Neurosci 7:39.

The 37MB code needs to be downloaded from this link:

http://senselab.med.yale.edu/modeldb/data/147366/composite.zip

This document provides very brief installation and usage
instructions.


=== SUPER EASY QUICK START ===

On a "typical" Linux system (i.e., mine!) the following sequence of
commands will install the model, run it, and then create the
figures. Compilation takes ~1 minute, running takes ~1 hour, and
analysis takes ~1 minute.

unzip composite.zip
cd network
nrnivmodl *.mod
cd ..
runsim
cd analysis
matlab -r "fig4fieldspectra; fig5firing; fig6spectral; fig7granger"



=== INSTALLATION ===

This code has been designed to work on Linux machines. It may work
on Macs and will definitely not work on Windows. If this is a
problem, please let me know and I can try to help you get it working
on your system.

REQUIREMENTS

1. NEURON (7.3, but may work with earlier versions);
2. Python (2.7, including NumPy and Pylab);
3. MATLAB (2012b, but may work with earlier versions);
4. At least 15 GB of RAM to run the full model.

INSTRUCTIONS

Type "nrnivmodl *.mod" in the "network" directory to compile the
spiking model, which is written in NEURON. This should create a
directory called either i686 or x86_64, depending on your computer's
architecture, and put a file called "special" in that directory.


=== USAGE ===

1. Run the executable script "runsim". It takes roughly an hour on a
2.7 GHz machine, and saves a number of text files to the "output"
directory.

2. Run any or all of the fig*.m files in the "analysis" directory
from Matlab; each will generate the listed figure from the
paper. The other .m files in that directory are called by the fig*.m
files, but do not themselves generate figures.

3. Options are mainly set in runsim. For example, if you don't have
15 GB of RAM, change "simsize=10" (line 21) to "simsize=2", for
example. These options can also be adjusted as input arguments to
runsim, e.g.

runsim all ./output/output 22 2

has the same effect as changing the default to "simsize=2". NB: I
cannot guarantee that all options will work without modifications to
the code!

By default, runsim will execute all four models (white-noise-driven,
thalamocortically-driven, healthy-basal-ganglia-driven, and
Parkinson's-disease-driven). This is equivalent to the option
"runsim all". To run any single model, just type "runsim wh",
"runsim tc", "runsim bg", or "runsim pa". However, note that (a) it
will still take 15 GB of RAM to run a single model, and (b) you
won't be able to run the analysis codes until all four have been
run.


=== TROUBLESHOOTING ===

If you have MATLAB <2011a, fig5firing.m won't work because of the
rng(1) function (which resets the random number generator). Simply
delete this line and the code will work, or else replace that line
with

RandStream.setGlobalStream(RandStream('mt19937ar','Seed',1));

to reproduce the exact results of the original code. (From the
hideous line above, you can see why they changed the syntax!)


=== HOW THE MODEL WORKS ===

The codebase for this model has evolved over several decades, so it
is not exactly what one would call "user-friendly". Briefly, the
spiking model is implemented in the .hoc and .mod files; the field
model is implemented in the C++, and is translated into
NEURON-friendly format using the Python code; the analysis is done
in the Matlab files; and everything is tied together with the
"runsim" bash script.

The crux of the network model is intf6.mod, which implements the
event-driven integrate-and-fire neurons. Other key files are
main.hoc, which initializes the network model; hybrid.hoc and
stimuli.hoc, which translate the field model output into the spikes
used to drive the network model; params.hoc, which sets the network
model's cellular properties; and network.hoc, which sets its network
properties.

The "analysis" directory contains the m-files for analyzing the
results. The "field" directory contains the code for the field
model. The "network" directory contains the code for the spiking
network model. The output generated by the models is saved to the
"output" directory.


=== ACKNOWLEDGEMENTS ===

The spiking network model was developed primarily by Bill Lytton and
Sam Neymotin. The field model was developed primarily by Peter
Robinson and Peter Drysdale. I was responsible for the integration
of the two models and the analysis codes.

If you want to know more about how any of the individual models or
codes work, I'd be happy to help.

-- Cliff Kerr (cliffk@neurosim.downstate.edu)