.. SynapseGenerator documentation master file, created by
   sphinx-quickstart on Mon Mar  2 16:22:41 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Summary
=======

SynapseGenerator is a software package used to predict connectivity at the synapse level
based on statistical properties of all neuron populations that co-exist in the 
given brain region of interest. For each population, the spatial distribution 
of the dendritic and axonal arborizations needs to be either specified as a probability density
function (e.g. a mixture of Gaussians), or can be estimated from samples of
reconstructed dendritic/axonal arborizations.

.. image:: _static/ProcessingSteps0.PNG
  :width: 90 %

The five main processing steps are illustrated in the figure above:

1. Parameters (lpar): Define the statistical parameters for each neuron population and setup a discrete space to place neurons in. The space can be 1, 2 or 3 dimensional; the discrete grid is chosen fine enough to have at most one synapse per voxel.
2. Gaussian parameters (Yinfo): Parse the input parameters and convert the specified densities to a Gaussian Mixture model, which defines the target density Y. The presynaptic and postsynaptic neurons are specified seperately, each can consist of several neuron populations.
3. Target Density (Y): Compute a discrete spatial sampling of the Gaussian Mixture model. Y is a (sparse) two dimensional matrix in which each row represents a voxel, containing the synapse densities of all contributing neurons.
4. Synaptic Elements (X): Place synapses in target space such that:

  * A preset overall synaptic density is reached.
  * Synapses are placed where dendritic and axonal densities are highest.
  * No more than one synapse is placed in a single discrete voxel.
  
  Several methods to optimize these criteria can be used:
  
  1. Random draws, followed by pruning;
  2. The Lasso method (under development), a linear least squares algorithm that uses a constraint that parameters cannot exceed a given value (here: at most one synapse per voxel);
  3. The Ising model (under development), which computes an optimal synapse configuration by minimizing an energy function.

  The resulting matrix X has the same size as Y but is much sparser since it contains only ones (potential synapse) and zeros (no synapse).

5. Return results:

  * Connectivity (conMat): Each synapse is assigned to a pre- and postsynaptic neuron;  
  * Minimum Spanning Tree: The entire set of synapses for a given neuron is used to reconstruct its arborization, using the *minimal spanning tree* algorithm, as implemented in the TREES toolbox;
  * Standard set of visualizations, to analyse the consecutive steps of the pipeline.

SynapseGenerator is implemented in Matlab; its core elements are currently ported to Python.

Contents
==================

This second iteration of the online documentation consists of the following parts:

* A worked out example of `long range, zeroth order connectivity <./LongRangeZerothOrder.html>`_;
* A worked out example of thalamocortical projections to spiny stellates, `limited to only a few neurons <./DemoOberlander3fewN.html>`_;
* A worked out example of thalamocortical projections to spiny stellates, `limited to a small piece of cortex <./DemoOberlander3Part.html>`_;
* A description of the `lpar input parameter structure <./explanationLpar.html>`_;
* A listing of `all functions <./functionlist.html>`_ in the SynGenPipeline package with descriptions derived rom *AutoDoc comments* placed in the code.

The examples are designed such that they run smoothly on normal desktop computers with 8GB memory.
With the forthcoming port to Python, we will develop a parallel computing strategy to keep requirements low.

List of contents
----------------

.. toctree::
  :maxdepth: 1

  LongRangeZerothOrder
  DemoOberlander3fewN
  DemoOberlander3Part
  explanationLpar
  functionlist

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`