README for main.hoc
For detailed information, view Model_Manual.pdf
Produced by: [email protected] 2016

PURPOSE OF CODE:
This code creates a scalable network of cells and runs a simulation.
It models the rat CA1 using several cell types and can include
characteristics of an epileptic network (sprouting and cell death).

INSTRUCTIONS FOR RUNNING CODE FROM BITBUCKET:


In your terminal, move to the parent directory where you want to place the ca1 repository (which will come in a ca1 directory) and then enter the following commands:
hg clone ssh://[email protected]/mbezaire/ca1
cd ca1/
hg clone ssh://[email protected]/mbezaire/ca1datasets
mv ca1datasets datasets
nrnivmodl  # Or mknrndll for Windows
mkdir results
nrniv -c "NumData=101" -c "ConnData=430" -c "SynData=120" -c "Scale=10000" -c "SimDuration=100" -c "strdef RunName" -c "RunName=\"TestRun\"" ./main.hoc -c "quit()"

Results from this run would appear in:

./results/TestRun/

I recommend running with a small scale and short time for the personal computer, I chose 10000 here but 1000 would work as well (Scale = how many real neurons are represented by 1 model neuron).




INSTRUCTIONS FOR RUNNING THE PROGRAM
>SETUP:
1. Ensure neuron is installed on the head node and has its directory added to PATH
2. Ensure that mpich2 is installed on the head node and has its directory added to PATH
3. Compile the mod files into the directory from which the model program will be run
	a. To compile all mod files in the directory, simply enter:
		$ nrnivmodl
	b. To compile specific mod files, enter them after the command:
		$ nrnivmodl ccanl nca tca

>RUNNING:
1. Edit the parameter input files (listed below) as necessary
2. Turn on mpd:
		$ mpdboot	
	or alternatively:
		$ mpd &
3. Call the program with the number of available hosts where the '2' is:
		$ mpiexec -n 2 $NEURONHOME/nrn/x86_64/bin/nrniv -nobanner -nogui -mpi ca1.hoc	
4. When finished using mpi, shut down mpd:
		$ mpdallexit

FILE ORGANIZATION:
root folder:
	- main.hoc (main hoc file) and all mechanism files
cells folder:
	- individual files defining each cell type
	- individual files defining the axonal distribution of each cell type
connections folder:
	- individual files specifing the probability, strength, and delay of each connection type
setupfiles folder:
	- default parameter definitions file
	- cell numbers and soma layers
	- other files needed by ca1.hoc to run the model
stimulation folder:
	- individual files defining each stimulation protocol
results folder:
	- contains result folders for each run
tools folder:
	- contains MATLAB and NEURON scripts to organize results and generate figures
jobscripts folder:
	- contains scripts generated by you to submit a model run to a batch queue. This folder can be moved to another location.
x86_64 folder:
	- automatically generated when mechanisms are compiled, stores compiled mechanisms

FILES IN RESULTS FOLDER
spikeraster.dat
connections.dat
numcons.dat
position.dat
celltype.dat
runtimes.dat
ranseeds.dat
runreceipt.txt
lowindex.hoc

VIEWING THE RESULTS
Try our simulation management tool, SimTracker (http://mariannebezaire.com/simtracker/)

USING MERCURIAL
Mercurial is a code versioning program; this model is meant to be used with Mercurial.
To get started:
1. Download and install Mercurial from http://mercurial.selenic.com/
2. At the command prompt, cd to the root folder of this model
3. To create a Mercurial repository of the model, enter:
	$ hg init
4. To commit changes to the repository, enter:
	$ hg commit -m "comment about this code version"
5. To check which code version you are using:
	$ hg parent
6. To list all the code versions in the repository:
	$ hg log
7. To switch to a different code version (ex: version 2):
	$ hg update -C -r 2
8. To switch to back to the most recent version:
	$ hg update -C -r tip
9. To check the changes made since you last commit:
	$ hg status
10. To have Mercurial start tracking a file:
	$ hg add myfile.txt
11. To have Mercurial remove and stop tracking a file:
	$ hg remove myfile.txt
12. To have Mercurial move and keep tracking a file:
	$ hg mv original.txt target.txt
13. For more extensive instructions, see:
	http://mercurial.selenic.com/guide/

SPECIFYING PARAMETER VALUES AT EXECUTION TIME
Add the '-c' option, followed by the equation to set the parameter in quotes:
	$ mpiexec -n 2 $NEURONHOME/nrn/x86_64/bin/nrniv -nobanner -nogui -mpi -c "mytstop=100" ca1.hoc	
For strings, include another '-c' option to define the string and enclose the string value in '\"':
	$ mpiexec -n 2 $NEURONHOME/nrn/x86_64/bin/nrniv -nobanner -nogui -mpi -c "strdef RunName" "RunName=\"myrun\"" ca1.hoc	

CODE OUTLINE:
I.  LOAD LIBRARIES & PARAMETERS
	1. Load the main nrngui.hoc
	2. Load the template for the parallelnetmanager class (used to parallelize the code)
	3. Load the template for the randomstream class (used to generate random number streams)
	4. Load the template for CellCategoryInfo class, which generates 1 object per cell type
		to store celltype specific data and enable the removal of all hard-coded cell type refs
		
II. SET MODEL SIZE, CELL DEFINITIONS
	1. Load some parameters from file
	2. Set more static parameters directly in this code
	3. Load celltype specific data
		a. For each cell type specified in the cells2include.hoc file
			i.  Read in the cell name, # cells, layer specifier, stim input specifier
			ii. Compute the start and end of the gid # range
			iii.Create an object of the CellCategoryInfo class and store the data from i & ii
			iv. Load the hoc file containing the celltype class template
		b. Load the hoc file containing the perforant path stimulation template
	4. Kill off a % of cells (specified by sclerosis factor) that specified as being in the hilar layer
	5. Recalculate the gid ranges for each cell type, now that the number of cells for some types has decreased
	6. Calculate the total number of cells including and excluding the perforant path stimulation cell(s)
	
III.SET UP PARALLEL CAPABILITY
	1. Set up a ParallelNetManager object
	2. Create a ParallelContext
	3. Call the round robin command, which distributes all cells among all processors in a round
	4. Define an iterator that can iterate over all the cells in a given range that are owned by
		the host that called the iterator
		
IV. CREATE, UNIQUELY ID, AND POSITION CELLS
	1. For each cell type defined in cells2include.hoc:
		a. For each host in the cluster:
			i.  Check that the gid is owned by the host (and it should be, because we are using the iterator)
			ii. Create a cell of that cell type and reference it in a list contained by that cellType object
			iii.Add the cell to the 'cells' list (this is something proposed by NEURON developers,
				but we don't use explicitly use it in the code)
			iv. Create an empty connection for the cell to use as a spike detector
			v.  Associate the cell with its gid and with the spike generation location (empty connection)
			vi. Calculate and store the cell's position using an algorithm based on gid, cell type,
				# of cells of that type, # available 'bins'

V.	CONNECT THE MODEL CELLS AND CONNECT THE STIMULATING AFFERENTS TO THE MODEL CELLS
	1. For each cell type x cell type combination, load in the connection properties
		(probability, weight, delay # synapses to choose from)
		a. If the probability of connection is not 0, for a given cell type x cell type combination:
		b. Iterate through each (potential) post-synaptic cell of that type that exists on the host executing this code
			i.  Iterate through each (potential) pre-synaptic cell of that type (regardless of where it lives)
			ii. Algorithmically obtain the positions of the pre- and post- cells
			iii.Calculate the distance between the cells and obtain a probability factor based on the distance and
				distribution of axon length for the pre-synaptic cell
			iv. Multiply the distribution number by the probability of those two types of cells connecting
				and by a connection factor that was artificially added to ensure the proper amount of connectivity
				between cells in a network of a given size
			v.  Pick a random number between 0 and 1 and check if it is less than this product.
			vi. If the above statement is true, make a connection between the cells with the given weight and delay
				and add the connection to a list 'nclist' (this is something proposed by NEURON developers)
	2. For each perforant path stimulator cell:
		a. Connect the cell with the middle 10% of granule cells in the network
		b. Connect the cell with the middle 10% of basket cells in the network
		c. Make 10 connections to the middle 10% of mossy cells in the network (note that with small network sizes,
			a given cell may receive more than 1 connection)
			
VI.	INITIALIZE AND RUN NETWORK, OUTPUT RESULT FILES
	1. Initialize the network using parameters specified in part I.
	2. Run a low resolution 'pre-simulation' to allow cells to 'settle' and all components to reach steady state
	3. Set the program to records all spikes of all cells on the host executing this code
	4. Run the simulation for the time specified in part I, at the resolution specified in part I.
	5. Output various result files:
		a. A spike raster file giving spike times # gids of spiking cells
		b. A connection file that gives pre- and post- synaptic cell gids and synapse types
		c. A position file that gives the gid and x, y, and z coordinates of each cell
		d. A cell type file that gives cell name and gid range for each cell type
		e. A runtimes file that gives the real time taken by each code section in seconds

DATASETS
Dataset Files - Column Headers

cellnumbers_###.dat:
Cell Type Name - name of the cell as it will be referred to in the conndata and syndata datasets, as well as elsewhere in the code and analysis
Technical Type - which code template to use for the cell (class_[technicalcell].hoc). have these two decoupled means we can play around with which ephys profile to use with which cell if we are trying to study/break a phenomenon we see in the network
Number - number of cells to include in the model (if at full scale, Scale==1.  Will be scaled down proportionally for smaller scale models)
Layer - Which layer (in 3D) to place the cell, 0-oriens, 1-pyramidale, 2-radiatum, 3-lacunosum-moleculare
Artifical Flag - 0: realistic cell, 1: artificial point process spike train cell, 2: Izhikevich neuron


conndata_###.dat:
Presynaptic Cell Type
PostSynaptic Cell Type
Synapse Weight - weight of each synaptic connection in the units of the corresponding mod file's conductance. For this model, we always use microSemiens, uS
Number of Connections - In terms of Convergence onto a single cell: the number of presynaptic cells of that type that connect to 1 postsynaptic cell of the postsynaptic type
Synapses/Connection - since connections between cells often comprise multiple synapses, here set the number of synapses that will be made between each "connection" of 1 presynaptic to 1 postsynaptic cell

syndata_###.dat:
PostSynaptic Cell Type
Presynaptic Cell Type
Synapse Mechanism - corresponds to the name of the NMODL mechanism to use for the synapse (the SUFFIX within the NEURON block of the mod file)
Section List - the section list on the postsynaptic cell (must be defined in that celltype's class_.hoc template) where synapses of this type can be found
Distance Condition 1 - criteria for distance away from the soma synapses may occur (on sections within the section list only)
Distance Condition 2 - criteria for distance away from the soma synapses may occur (on sections within the section list only)
Scaling parameter - blank for all synapses in this model
Tau1 - for all synapses except mixed GABA_AB (for which this field is blank), the 10-90% rise time of the synapse (ms)
Tau2 - for all synapses except mixed GABA_AB (for which this field is blank), the decay time constant of the synapse (ms)
e - for all synapses except mixed GABA_AB (for which this field is blank), the reversal potential of the synapse (mV)
Tau1a - for mixed GABA_AB synapses only (for all others this is blank), the 10-90% rise time of the GABA_A conductance of the synapse (ms)
Tau2a - for mixed GABA_AB synapses only (for all others this is blank), the decay time constant of the GABA_A conductance of the synapse (ms)
ea - for mixed GABA_AB synapses only (for all others this is blank), the reversal potential of the GABA_A conductance of the synapse (mV)
Tau1b - for mixed GABA_AB synapses only (for all others this is blank), the 10-90% rise time of the GABA_B conductance of the synapse (ms)
Tau2b - for mixed GABA_AB synapses only (for all others this is blank), the decay time constant of the GABA_A conductance of the synapse (ms)
eb - for mixed GABA_AB synapses only (for all others this is blank), the reversal potential of the GABA_A conductance of the synapse (mV)=======
		e. A runtimes file that gives the real time taken by each code section in seconds>>>>>>> other