update docs and release notes

docs/index.rst

@@ -7,22 +7,20 @@
     <center><a href="https://doi.org/10.1101/174029"><img src="http://falexwolf.de/img/scanpy_figure_1.png" title="Overview of Scanpy's analysis features." style="width: 500px"></a></center>
 
 .. include:: ../README.rst
-   :start-line: 10
-   :end-line: 12
+   :start-line: 12
+   :end-line: 14
 
 
-Report issues and see the code on `GitHub <https://github.com/theislab/scanpy>`_. Learn more about conceptual ideas in our `preprint <https://doi.org/10.1101/174029>`_.
+Report issues and see the code on `GitHub <https://github.com/theislab/scanpy>`_. If Scanpy has been useful for your research, please consider citing our preprint: `Wolf, Angerer & Theis, bioRxiv 174029 (2017) <https://doi.org/10.1101/174029>`_.
 
 .. include:: release_notes.rst
 
-
-**Contents**
-
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    examples
-   api/index
    basic_usage
    installation
+   api/index
    references

docs/release_notes.rst

@@ -1,8 +1,30 @@
-**November 15, 2017**: version 0.3
+**Plans for upcoming versions:**
 
-- `AnnData can now be concatenated <https://scanpy.readthedocs.io/en/stable/api/scanpy.api.AnnData.concatenate.html>`_
-- `AnnData is also available as a separte package <https://pypi.python.org/pypi/anndata/>`_
+- common file format for exchanging :class:`~scanpy.api.AnnData` with packages such as Seurat and SCDE
+- better correction for confounders
+- partial loading of data into memory
+
+
+**November 16, 2017**: version 0.3
+
+Consistency updates in the design of :class:`~scanpy.api.AnnData` and the code base. Everything is backwards compatible.
+
+- `AnnData can now be concatenated <https://scanpy.readthedocs.io/en/stable/api/scanpy.api.AnnData.html>`_
+- `AnnData is also available as a separate package <https://pypi.python.org/pypi/anndata/>`_
 - `results of approximate graph abstraction (AGA) are simplified <https://github.com/theislab/graph_abstraction>`_
-- moved python-igraph and louvain out of the requirements
 - stability fixes
-
+
+
+**October 25, 2017**: version 0.2.9
+
+Initial release of `approximate graph abstraction (AGA) <https://github.com/theislab/graph_abstraction>`_.
+
+
+**July 24, 2017**: version 0.2.1
+
+Scanpy now includes preprocessing, visualization, clustering, pseudotime and trajectory inference, differential expression testing and simulation of gene regulatory networks. The implementation efficiently deals with datasets of more than one million cells.
+
+
+**May 1, 2017**: version 0.1
+
+Scanpy computationally outperforms the Cell Ranger R kit and allows reproducing most of Seurat's guided clustering tutorial.

scanpy/plotting/tools.py

@@ -1223,7 +1223,7 @@ def dpt(
     ----------
     adata : AnnData
         Annotated data matrix.
-    basis : {'diffmap', 'pca', 'tsne', 'draw_graph_...'}
+    basis : {`'diffmap'`, `'pca'`, `'tsne'`, `'draw_graph_...'`}
         Choose the basis in which to plot.
     color : string or list of strings, optional (default: None)
         Sample/ cell annotation for coloring in the form "ann1,ann2,...". String
@@ -1422,7 +1422,7 @@ def louvain(
     ----------
     adata : AnnData
         Annotated data matrix.
-    basis : {'diffmap', 'pca', 'tsne', 'draw_graph_...'}
+    basis : {`'diffmap'`, `'pca'`, `'tsne'`, `'draw_graph_...'`}
         Choose the basis in which to plot.
     color : string or list of strings, optional (default: None)
         Keys for sample/cell annotation either as list `["ann1", "ann2"]` or

scanpy/tools/diffmap.py

@@ -3,57 +3,49 @@
 from ..tools import dpt
 from .. import logging as logg
 
-def diffmap(adata, n_comps=15, n_neighbors=None, knn=True, n_pcs=50, sigma=0, n_jobs=None,
-            flavor='haghverdi16', copy=False):
+
+def diffmap(adata, n_comps=15, n_neighbors=None, knn=True, n_pcs=50, sigma=0,
+            n_jobs=None, flavor='haghverdi16', copy=False):
     """Diffusion Maps [Coifman05]_ [Haghverdi15]_ [Wolf17]_.
 
     Diffusion maps [Coifman05]_ has been proposed for visualizing single-cell
     data by [Haghverdi15]_. The tool uses the adapted Gaussian kernel suggested
-    by [Haghverdi16]_. Uses the implementation of [Wolf17]_.
+    by [Haghverdi16]_ in the implementation of [Wolf17]_.
 
     Parameters
     ----------
-    adata : AnnData
+    adata : :class:`~scanpy.api.AnnData`
         Annotated data matrix.
-    n_comps : int, optional (default: 10)
+    n_comps : `int`, optional (default: 10)
         The number of dimensions of the representation.
-    n_neighbors : int, optional (default: 30)
+    n_neighbors : `int`, optional (default: 30)
         Specify the number of nearest neighbors in the knn graph. If knn ==
         False, set the Gaussian kernel width to the distance of the kth
         neighbor (method 'local').
-    knn : bool, optional (default: True)
+    knn : `bool`, optional (default: True)
         If True, use a hard threshold to restrict the number of neighbors to
         k, that is, consider a knn graph. Otherwise, use a Gaussian Kernel
         to assign low weights to neighbors more distant than the kth nearest
         neighbor.
-    n_pcs : int, optional (default: 50)
+    n_pcs : `int`, optional (default: 50)
         Use n_pcs PCs to compute the Euclidian distance matrix, which is the
         basis for generating the graph. Set to 0 if you don't want preprocessing
         with PCA.
-    n_jobs : int or None
-        Number of CPUs to use (default: sett.n_cpus).
-    copy : bool (default: False)
+    n_jobs : `int` or `None`
+        Number of CPUs to use (default: `sc.settings.n_jobs`).
+    copy : `bool` (default: `False`)
         Return a copy instead of writing to adata.
 
     Returns
     -------
-    The following is added to adata.smp
-        X_diffmap : np.ndarray
-            Array of shape n_samples × n_comps. DiffMap representation of data,
-            which is the right eigen basis of transition matrix with eigenvectors as
-            columns.
-    The following is added to adata.uns
-        diffmap_evals : np.ndarray
-            Eigenvalues of the transition matrix.
+    Depending on `copy`, returns or updates `adata` with the following fields.
 
-    References
-    ----------
-    - Diffusion Maps: Coifman et al., PNAS 102, 7426 (2005).
-    - Diffusion Maps applied to single-cell data: Haghverdi et al., Bioinformatics
-      31, 2989 (2015).
-    - Diffusion Pseudotime: Haghverdi et al., Nature Methods 13, 3971 (2016).
-    - Diffusion Maps as a flavour of spectral clustering: von Luxburg,
-      arXiv:0711.0189 (2007).
+    X_diffmap : `np.ndarray` (`adata.smpm`, dtype `float`)
+        Array of shape (#samples) × (#eigen vectors). DiffMap representation of
+        data, which is the right eigen basis of the transition matrix with
+        eigenvectors as columns.
+    diffmap_evals : `np.ndarray` (`adata.uns`)
+        Array of size (number of eigen vectors). Eigenvalues of transition matrix.
     """
     logg.info('running Diffusion Maps', r=True)
     adata = adata.copy() if copy else adata

scanpy/tools/dpt.py

@@ -15,20 +15,20 @@ def dpt(adata, n_branchings=0, n_neighbors=None, knn=True, n_pcs=50, n_dcs=10,
         min_group_size=0.01, recompute_graph=False, recompute_pca=False,
         allow_kendall_tau_shift=True, flavor='haghverdi16', n_jobs=None,
         copy=False):
-    """Infer progression of cells, identify *branching* subgroups [Haghverdi16]_ [Wolf17]_.
+    """Infer progression of cells and branching subgroups [Haghverdi16]_ [Wolf17]_.
 
     Reconstruct the progression of a biological process from snapshot data and
     detect branching subgroups. `Diffusion Pseudotime analysis` has been
-    introduced by [Haghverdi16]_. Here, we use a further developed,
-    `hierarchical` version, which is able to detect multiple branching events
-    [Wolf17]_ by setting the parameter `n_branchings`.
+    introduced by [Haghverdi16]_. Here, we use a further developed, faster and
+    `hierarchical` version, which is able to detect multiple branching events by
+    setting the parameter `n_branchings` [Wolf17]_.
 
-    The tool is similar to the R package destiny_ of [Angerer16]_; the Scanpy
+    The tool is similar to the R package destiny of [Angerer16]_; the Scanpy
     implementation though runs faster and scales to much higher cell numbers.
 
     Parameters
     ----------
-    adata : AnnData
+    adata : :class:`~scanpy.api.AnnData`
         Annotated data matrix.
     n_branchings : `int`, optional (default: 1)
         Number of branchings to detect.
@@ -74,18 +74,18 @@ def dpt(adata, n_branchings=0, n_neighbors=None, knn=True, n_pcs=50, n_dcs=10,
     -------
     Depending on `copy`, returns or updates `adata` with the following fields.
 
-    dpt_pseudotime : ``np.ndarray`` in ``adata.smp``
+    dpt_pseudotime : `pd.Series` (`adata.smp`, dtype `float`)
         Array of dim (number of samples) that stores the pseudotime of each
         cell, that is, the DPT distance with respect to the root cell.
-    dpt_groups : ``np.ndarray`` of type string in ``adata.smp``
+    dpt_groups : `pd.Series` (``adata.smp``, dtype `category`)
         Array of dim (number of samples) that stores the subgroup id ('0',
         '1', ...) for each cell. The groups  typically correspond to
         'progenitor cells', 'undecided cells' or 'branches' of a process.
-    X_diffmap : ``np.ndarray`` in ``adata.smp``
-        Array of shape (number of samples) × (number of eigen
-        vectors). DiffMap representation of data, which is the right eigen
-        basis of the transition matrix with eigenvectors as columns.
-    dpt_evals : ``np.ndarray`` in ``adata.uns``
+    X_diffmap : `np.ndarray` (`adata.smpm`, dtype `float`)
+        Array of shape (#samples) × (#eigen vectors). DiffMap representation of
+        data, which is the right eigen basis of the transition matrix with
+        eigenvectors as columns.
+    diffmap_evals : `np.ndarray` (`adata.uns`)
         Array of size (number of eigen vectors). Eigenvalues of transition matrix.
     """
     adata = adata.copy() if copy else adata

scanpy/tools/louvain.py

@@ -54,12 +54,10 @@ def louvain(adata,
         much more powerful.
     copy : bool (default: False)
 
-    References
-    ----------
-    - implementation of Louvain algorithm: Traag, doi:10.5281/zenodo.35117 (2017)
-    - Louvain algorithm: Blondel et al., J. Stat. Mech., P10008 (2008)
-    - base graph package: Csardi et al., InterJournal Complex Systems, 1695 (2006)
-    - basic suggestion for single-cell: Levine et al., Cell 162, 184-197 (2015)
+    Returns
+    -------
+    Depending on `copy`, returns or updates `adata` with the following fields.
+
     """
     logg.info('running Louvain clustering', r=True)
     adata = adata.copy() if copy else adata