.. _connectivity: Connectivity ============ Overview -------- There are two connectivity options available: * fastconn * repeatconn They differ only in that `repeatconn` allows the same presynaptic cell to make multiple connections to a given postsynaptic cell while `fastconn` does not allow repeated connections. In scaled down networks with very small numbers of cells, in order to make the number of connections specified in the connection matrix (conndata_### file), it may be necessary to allow repeated connections by switching from the `fastconn` algorithm to the `repeatconn` algorithm. The connectivity algorithm is implemented in a mod file (NMODL), compiled prior to simulation execution to allow the connection process to go much faster than if it were written completely in interpreted NEURON code. Connectivity Algorithm ---------------------- The algorithm in the NMODL file decides which cells will be connected. It is called once for each combination of presynaptic cell by postsynaptic cell type on each processor. For all cells of that type owned by that processor, first their positions are determined. Then, for each possible presynaptic type, the number of expected connections onto a given postsynaptic cell (as specified in the conndata_### file) is distributed into distance-bins according to the presynaptic cell type's axonal distribution profile. Next, the positions of all cells of the presynaptic type are determined and their distance from the postsynaptic cell calculated. For cells within a given distance-bin, the appropriate number of connections is randomly selected. If there are fewer potential presynaptic cells in a given distance-bin than are expected to fulfill both the axonal distribution and total the number of connections specified for the postsynaptic cell, the algorithm will attempt to make extra connections from other cells in nearby distance bins. The goal is to let the constraint for the total number of connections onto the postsynaptic cell allow slight distortion in the presynaptic cell's axonal distribution if that's what it takes to make the necessary number of connections. Sometimes there are not enough presynaptic cells available even considering the entire axonal extent of the presynaptic cell. In this case, when the `fastconn` version of the algorithm is used, the postsynaptic cell have fewer incoming connections from that presynaptic cell type than were specified in the connection matrix. Alternatively, when the `repeatconn` version of the algorithm is used, the postsynaptic cell can instead receive multiple connections from the presynaptic cells that are close enough, so that the total number of connections in the connection matrix is respected. Note: when using SimTracker, it is easy to check how the actual connectivity of the network compares to the connectivity specified in the input connectivity matrix. From the list of possible analyses in the bottom right corner of SimTracker (the **Generate Outputs** panel), simply select the checkbox for **Connectivity Matrix** and type in the option 'grade' in the third column. Click the **Generate** button to see how the actual and expected numbers compare. The NEURON model code works with the compiled connectivity algorithm in the following manner. In the NEURON code, each postsynaptic cell type is looped over in each processor. For each instance of the loop (each postsynaptic cell type), each presynaptic cell type is looped over. For each presynaptic X postsynaptic combination, a placeholder vector of connections-to-make is created and passed, along with connectivity parameters (presynaptic cell axonal distribution and positioning, postsynaptic cell positioning, number of connections expected, etc), to the compiled connectivity algorithm. The algorithm iterates through each postsynaptic cell of the given type owned by that processor, using the parameters and positioning information of the cells to randomly select the presynaptic connections to make. It adds these presynaptic cells to the placeholder vector until all desired or possible connections have been determined for the postsynaptic cells. Back in the NEURON code, the vector of connections to make (specific presynaptic and postsynaptic cells) is iterated through to make the actual connections. For each connection, the desired number of synapses are made by randomly selecting a location from a list of possible synaptic locations on the postsynaptic cell (for that particular presynaptic cell type) and connecting the presynaptic cell at those locations. Printing Connectivity Information to File ----------------------------------------- Many users may wish to have a list of all connections in the model network. For small models, this is feasible and can be accomplished by setting the `PrintConnDetails` parameter prior to executing the simulation as follows: * `PrintConnDetails = 1` // print out all synapses after the simulation is finished * `PrintConnDetails = 2` // print out all synapses immediately after they are made * `PrintConnDetails = 0` // do not print out all synapses ; only print out connections for small fraction of cells If `PrintConnDetails > 0`, a `connections.dat` file will be printed along with the other results, containing a list of every synapse made in the network. For each synapse, the GID (global identifier, a unique number assigned to each cell in the network) of the presynaptic cell and the GID of the postsynaptic cell will be printed, along with a synapse ID unique to the postsynaptic cell type. Since many connections comprise multiple synapses, there are likely to be several times as many synapses (and therefore rows in this output file) as there are total connections in the model. The table below shows an example of 6 lines from a `connections.dat` file, where the postsynaptic cell with GID 45 is seen to receive 2 connections, from presynaptic cells 2 and 17, comprising 3 synapses each: ========= ========== ========= PreCellID PostCellID PostSynID ========= ========== ========= 2 45 27 2 45 14 2 45 3 17 45 18 17 45 20 17 45 23 ========= ========== ========= The `connections.dat` file can get quite large. For example, the full scale `ca1` network contains 5 billion synapses. Setting `PrintConnDetails > 0` for the ca1 network, which is not recommended, would print 15 billion datapoints to record those 5 billion synapses. Currently, there has been no attempt to allow the creation of an HDF5 file for large connectivity datasets in this model code. Even for smaller networks for which it is feasible to print out all the synapses, printing to file may take a long time on a supercomputer. Therefore, the code by default will cause each processor to print to a separate file, and to print only the synapses that it owns. The resulting files may either be concatenated during simulation or later. The synapses owned by each processor are the synapses on the postsynaptic cells belonging to that processor. If `CatFlag==1`, the disparate files will be concatenated into a single file during the supercomputing job. To leave them as separate, set `CatFlag=0`. To print everything to a single file in serial, change the callsto `allCellConnsParallel()` (in `main.hoc` and `sim_execution_functions.hoc`) `to allCellConnsSerial()`. To summarize: * `(allCellConnsParallel() && CatFlag==1) || allCellConnsSerial()` produces a single connections.dat (allCellConnsSerial() does so very slowly) * `(allCellConnsParallel() && CatFlag==0` produces multiple connections_[host#].dat files - one for each processor that lists only the synapses onto cells on that host/processor Related Result Files -------------------- There are several other result files relevant to connectivity that are generated at the end of a simulation: * allsyns.dat - gives the range of unique (possible) synapse IDs for each pre X post cell, where the synapse IDs are unique within each postsynaptic celltype * cell_syns.dat - gives complete connectivity info for a small fraction of cells in the model * celltype.dat - gives the mapping of cell type string to numerical typeIndex, as well as the range of gid values for that type * numcons.dat - contains a summary of the number of connections (not synapses) in the network, broken down by preXpost combo per processor (connections are assigned to the processor that owns the postsynaptic cell):| host ID | precell type | postcell type | number of connections for that pre/post combo on that host | * runreceipt.txt- contains parameter values used in the run. parameters of interest here would be: * Connectivity = 'try_all_randfaststim'; // this does not allow for repeated connections; use try_all_repeatstim to allow repeats and better innnervation in scaled down networks. * Scale = 1; // size of model in terms of how many real cells are represented by a single model cell (1000 is 1/1000 the size of the full model) and is used to scale down the model volume as well to keep cell density similar * PrintConnDetails = 0; // whether to print the full connections.dat file (see later in this email for explanation) * PrintConnSummary = 1; // whether to print numcons.dat summary file of connections per pre X post combo for each host/processor * TransverseLength = 1000; // y dimension of network volume in microns * LongitudinalLength = 4000; // x dimension of network volume in microns * ConnData = 501; // which connection matrix used to determine number of connections to make * SynData = 120; // synapses between each pre X post cell type must be defined here too for the connection to be made * CatFlag = 0; // relevant to how all connections are written out, see later in this email for explanation * RandomSeedsConn = 0; // to change the specific connections that are made (where along the random number generator stream to start picking numbers), change this number. This can be used to make unique networks that have the same numbers & types of connections * AxConVel = 0; // if set to 0, a constant delay of 3 ms is used. If set >0, this value is scaled by the distance between two cells to determine the conduction delay and added to a constantof 0.5 ms representing the cleft delay (and ensuring the delay > the timestep dt). * myConDelay = 1.2; //(ms) not used in this code, but could be used to allow varying the constant delay (or the constant part of the variable delay). * sumnumout.txt - includes a line giving the total number of synapses in the model (misleadingly called NumConnections, should be NumSynapses): NumConnections = 5.14159e+09; * synlist.dat - tells which section each possible synapse location is on the postsynaptic cell (but does not give x location within section):| postcell type | precell type | postsynaptic celltype-specific synapse ID | section on postsynaptic cell where synapse is located | Users can also separately run launch_synapse_printer.hoc to obtain synlist.dat and allsyns.dat. :ref:`tutorials`