This is a complete set of code required to run and analyse the
striatum model from Humphries, Wood and Gurney (2009). The code is
freely available for study and modification.  Please cite the original
sources. For questions and assistance contact:
m.d.humphries@shef.ac.uk or drmdhumphries@gmail.com

************************************************************************
Top-level Files:

Experiment_RandomInput.m: the top-level function that runs the model;
			  this contains a selection of frequently
			  changed parameters
StriatumNetworkParameters.m: the complete specification of the model;
			a few of the parameters set here are
			overwritten in
			Experiment_RandomInput.m
RunSimulation.m: function called by Experiment_RandomInput.m to handle
		 passing the parameters to the MEX file that runs
		 model simulation
checkStriatumInputs.m: ensures that all parameters are of the right
		       class and type for handing to the MEX function
		       (called by RunSimulation.m)
./CreateNetwork (folder):
BuildStriatumNetwork.m: builds the network model according to the
			specified parameters (called by
			StriatumNetworkParameters.m); uses the
			probability of intersection functions supplied
			by the 4 .mat files in this folder
GetNeuronPositions.m: puts all neurons in their 3D positions, ensuring
		      that none are closer than the minimum set
		      distance (called by BuildStriatumNetwork.m)
./Simulation (folder):
This contains the MEX files and source C code for the simulation
engines that run the model. By default the simulation uses the
striatum_RK2 MEX file, solving the ODEs using the midpoint method (aka
2nd order Runge-Kutta). The original Euler-method solver is included
as striatum.cpp. We have also included the alternative
striatum_ZOH.cpp option, which solves the model using a zero-order
hold solution method (from Humphries & Gurney, 2007). The latter is
useful for double-checking the results of the RK2 method.  Simply swap
the function call in RunSimulation.m.

The RK2 method MEX files are provided compiled for 32-bit (.mexw32)
and 64-bit (.mexw64) Windows, and for 64-bit (.mexa64) Linux
systems. The other methods' MEX files are compiled for 64-bit
(.mexa64) Linux. we strongly recommend that you recompile the MEX code
from the source C++ for your platform

./Analyses (folder):
firing_stats_solo.m: a quick analysis of the firing properties of a
                     simulation cluster_words_winsize.m: does the
                     first pass of the clustering analysis detailed in
                     Humphries et al 2009, across the range of
                     specified binsizes
retained_graph_properties.m: takes the highest-scoring binsize from
			   cluster_words_winsize.m, and tests a range
			   of thresholds: the clustering with the
			   highest beta score from this second stage
			   was the one generally reported in the
			   paper. The second half of the code
			   extensively analyses the network of the
			   anatomy model, attempting to relate the
			   groups found by the clustering to some
			   properties of the anatomy.
firing_stats.m: called by retained_graph_properties.m, is a simplified
                version of firing_stats_solo.m

./Tools (folder):
helper functions for the analyses. Multileadevsplit.m is the main
function for the graph-cut clustering method.

************************************************************************

Notes:
(1) The solution method used in this code is RK2, not Euler as in the
paper; the effect of this is to improve the stability of the numerical
solution, and allow us to use an order of magnitude larger time-step
to speed up the simulations (dt = 0.1ms in the current code).

(2) This code represents the state-of-the-art of our striatal model
after completion of the Neural Networks paper in 2009, and is a
complete model. Since then we have improved components of the model in
further publications, but not yet published a combined overhaul. These
improvements are:
(a) an updated model of dopamine's effects on the MSN (Humphries,
Lepora, Wood & Gurney, 2009b)
(b) an updated model of the striatal anatomy model (Humphries, Wood &
Gurney, 2010); the code for this model will also be available on
ModelDB, and from the authors

**************************************************************************
References:

Humphries, M. D. & Gurney, K. (2007) Solution methods for a new class
of simple model neurons.  Neural Computation, 19, 3216-3225. [PDF copy
included with code]

Humphries, M. D., Wood, R. & Gurney, K. (2009) Dopamine-modulated
dynamic cell assemblies generated by the GABAergic striatal
microcircuit Neural Networks,22, 1174-1188. [PDF copy included with
code]

Humphries, M. D.; Lepora, N.; Wood, R. & Gurney, K. (2009b) Capturing
dopaminergic modulation and bimodal membrane behaviour of striatal
medium spiny neurons in accurate, reduced models. Frontiers in
Computational Neuroscience, 3, 26. Download at:
http://dx.doi.org/10.3389/neuro.10.026.2009

Humphries, M. D., Wood, R. & Gurney, K. (2010) Reconstructing the
three-dimensional GABAergic microcircuit of the striatum. PLoS
Computational Biology, in press.
