diff --git a/docs_sphinx/code/merging.png b/docs_sphinx/code/merging.png index ee8a5742..e00d1724 100644 Binary files a/docs_sphinx/code/merging.png and b/docs_sphinx/code/merging.png differ diff --git a/docs_sphinx/code/merging.rst b/docs_sphinx/code/merging.rst index a0196c69..291872fa 100644 --- a/docs_sphinx/code/merging.rst +++ b/docs_sphinx/code/merging.rst @@ -2,21 +2,26 @@ Automatic Merging ================= Need for an meta merging step ----------------------------------- +----------------------------- Because for high number of channels, the chance that a cell can be split among several templates are high, one need to merge putative templates belonging to the same cells. This is a classical step in most of the spike sorting technique, and traditionally, this step was performed by a human operator, reviewing all templates one by one. Problem is that with the new generation of dense probes that the code can handle (4225 channels), the output of the algorithm can lead to more than 1000 templates, and one can not expect a human to go through all pairs iteratively. To automatize the procedure, we developed a so-called meta-merging step that will allow to quickly identify pairs of templates that have to be merged. To do so, first, we consider only pairs that have a similarity between their templates higher than ``cc_overlap``. This allow not to considerate all the possible pairs, but only those that are likely to be the same cells, because their templates are similar. +.. note:: + + Since 0.8.2, the merging step is now included in the deafault pipeline of the algorithm, in order to simplify the evaluation with automatic procedures. However, since we don't want to claim that such a meta-merging is optimal for all dataset, all species, and also for long and non-stationary recordings, we would encourage users to look at full results if the meta merging is suspicious. + + Comparison of CrossCorrelograms ------------------------------- -Then, for all those pairs of cells, we are computing the cross-correlation function in a time window of [-100, 100] ms, with a particular time bin ``cc_bin``. The rationale behind is that a pair of template that should be merged should have a dip in the center of its cross-correlogram. To quantify that in an automated manner, we compute a control cross-correlogram in the same window of interest, but by reverting in time the spikes of cell 2. This allow us to compare the normal cross-correlogram between the two cells to a "control" one, keeping the same amount of correlation (see Figure). +Then, for all those pairs of cells, we are computing the cross-correlation function in a time window of [-100, 100] ms, with a particular time bin ``cc_bin``. The rationale behind is that a pair of template that should be merged should have a dip in the center of its cross-correlogram. To quantify that in an automated manner, we compute the theoretical amount of correlation that we should have, assuming the two cells would be independent. This allow us to compare the normal cross-correlogram between the two cells to a "control" one, keeping the same amount of correlation (see Figure). .. figure:: merging0.png :align: center - Difference between a normal cross-correlogram for a given pair of cells, and a control version where the spikes from the second cells are reversed in time. The center area in between the red dash dotted line is the one of interest. + Difference between a normal cross-correlogram for a given pair of cells, and a ``control`` version. The center area in between the red dash dotted line is the one of interest. To quantify the dip, we measure the difference between the cross correlogram and its shuffled version in a window of interest [``-cc_average``, ``cc_average``]. diff --git a/docs_sphinx/code/merging2.png b/docs_sphinx/code/merging2.png index ff76925c..b3d94de2 100644 Binary files a/docs_sphinx/code/merging2.png and b/docs_sphinx/code/merging2.png differ diff --git a/docs_sphinx/code/merging3.png b/docs_sphinx/code/merging3.png index 8320b574..dbdd4eb8 100644 Binary files a/docs_sphinx/code/merging3.png and b/docs_sphinx/code/merging3.png differ diff --git a/docs_sphinx/code/parameters.rst b/docs_sphinx/code/parameters.rst index eef3aaec..20d983b5 100644 --- a/docs_sphinx/code/parameters.rst +++ b/docs_sphinx/code/parameters.rst @@ -29,6 +29,8 @@ What are the steps of the algorithm you would like to perform. Defaults steps ar 2. whitening 3. clustering 4. fitting + 5. merging + Note that filtering is performed only once, and if the code is relaunched on the same data, a flag in the parameter file will prevent the code to filter twice. You can specify only a subset of steps by doing:: @@ -36,7 +38,7 @@ Note that filtering is performed only once, and if the code is relaunched on the .. note:: - Extra steps are available, such as ``merging`` (see the devoted section :doc:`documentation on Meta Merging <../code/merging>`), or even more (:doc:`documentation on extra steps <../advanced/extras>`). + The results of the ``merging`` step are still saved with a different extension compared to the full results of the algorithm. This is because we don't claim that a full automation of the software can work out of the box for all dataset, areas, species, ... So if you want to work from merged results, use the ``-e merged`` extension while converting/displaying results. But otherwise, just look to the ra results, without the merging step (see the devoted section :doc:`documentation on Meta Merging <../code/merging>`), or even more (:doc:`documentation on extra steps <../advanced/extras>`). * ``-c`` or ``--cpu`` diff --git a/docs_sphinx/code/quickstart.rst b/docs_sphinx/code/quickstart.rst index 2a774ce2..0383a1c3 100644 --- a/docs_sphinx/code/quickstart.rst +++ b/docs_sphinx/code/quickstart.rst @@ -102,6 +102,8 @@ Once the algorithm has run on the data path/mydata.extension, you should have th See the details here see :doc:`file formats <../advanced/files>` to know more how those files are structured. +Since 0.8.2, you should also have the same files, but with the ``-merged`` extension for some of them. This is because the merging step has been included in the default pipeline of the algorithm. Both results (with or without this extra merging) can be visualized, and/or exported for MATLAB_ and phy_. + Matlab GUI ~~~~~~~~~~ diff --git a/docs_sphinx/introduction/install.rst b/docs_sphinx/introduction/install.rst index 0339e46d..48259d01 100644 --- a/docs_sphinx/introduction/install.rst +++ b/docs_sphinx/introduction/install.rst @@ -42,6 +42,16 @@ To do so, use the ``pip`` utility:: >> pip install spyking-circus + +Note that if you are using a linux distribution, you must be sure that you have ``mpich`` instead of ``openmpi`` (default on Ubuntu). To do that, please do:: + + >> sudo apt remove openmpi + >> sudo apt install mpich libmpich-dev + +And to be sure that mpi4py is not installed with precompiled binary that would link with openmpi, you need to do:: + + >> pip install spyking-circus --no-binary=mpi4py + You might want to add the ``--user`` flag, to install SpyKING CIRCUS for the local user only, which means that you don't need administrator privileges for the installation. In principle, the above command also install SpyKING CIRCUS's dependencies, and CUDA_ support if ``nvcc`` command is found in your environment. Once the install is complete, you need to add the ``PATH`` where SpyKING CIRCUS has been installed into your local ``PATH``, if not already the case. To do so, simply edit your ``$HOME/.bashrc`` and add the following line:: diff --git a/docs_sphinx/introduction/release_notes.rst b/docs_sphinx/introduction/release_notes.rst index 153660b3..5b1ca8e0 100644 --- a/docs_sphinx/introduction/release_notes.rst +++ b/docs_sphinx/introduction/release_notes.rst @@ -31,7 +31,7 @@ Code and documentation contributions (ordered by the number of commits): * Cyrille Rossant ============= -Release 0.8.1 +Release 0.8.2 ============= * add a docker file to build the software