Merge pull request #675 from theislab/release/0.2.4

Release/0.2.4

.flake8

@@ -0,0 +1,11 @@
+[flake8]
+max-line-length = 88
+filename = *.py
+exclude =
+    .git,
+    __pycache__,
+    docs/*
+# F403: unable to detect undefined names
+# F405: undefined, or defined from star imports
+# W503: Linebreak before binary operator
+ignore = F403, F405, W503

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,22 +6,31 @@ labels: bug
 assignees: ''
 ---
 
-<!-- Description of the bug: -->
+<!-- Description of the bug -->
 ...
 
-<!-- Reproducible example in the code block below (if applicable, else delete): -->
+
+<!-- Reproducible example -->
 ```python
-...
+# paste your code here, if applicable
 ```
 
-<!-- Error output in the code block below (if applicable, else delete): -->
+
+<!-- Error Output -->
 <details>
-<summary> Error </summary>
+
+<summary> Error output </summary>
+
 ```pytb
-...
+# paste the error output here, if applicable
 ```
 </details>
 
-#### Versions:
-<!-- Output of scv.logging.print_versions() -->
-> 
+
+<!-- Versions -->
+<details> <summary> Versions </summary>
+
+```pytb
+# paste the ouput of scv.logging.print_versions() here
+```
+</details>

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [master, develop]
+    branches: [master, develop, 'release/**']
   pull_request:
-    branches: [master, develop]
+    branches: [master, develop, 'release/**']
 
 jobs:
   # Skip CI if commit message contains `[ci skip]` in the subject
@@ -19,7 +19,7 @@ jobs:
       - id: ci-skip-step
         uses: mstachniuk/ci-skip@master
 
-  # Check if code agrees with `black` and if README.rst can be converted to HTML
+  # Check if pre-commit hooks pass and if README.rst can be converted to HTML
   linting:
     needs: init
     if: ${{ needs.init.outputs.skip == 'false' }}
@@ -33,9 +33,9 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install black>=20.8b1 docutils
-      - name: Check code style
-        run: black --check --diff --color .
+          pip install pre-commit docutils
+      - name: Check pre-commit compatibility
+        run: pre-commit run --all-files --show-diff-on-failure
       - name: Run rst2html.py
         run: rst2html.py --halt=2 README.rst >/dev/null
 
@@ -55,6 +55,6 @@ jobs:
       - name: Install dependencies
         run: |
           pip install -e .
-          pip install pytest pytest-cov
+          pip install hypothesis pytest pytest-cov
       - name: Unit tests
         run: python -m pytest --cov=scvelo

.gitignore

@@ -7,6 +7,7 @@ scripts/
 write/
 scanpy*/
 benchmarking/
+htmlcov/
 
 scvelo.egg-info/
 
@@ -37,4 +38,7 @@ docs/source/scvelo*
 /dist/
 
 .coverage
-.eggs
+.eggs
+
+# Files generated by unit tests
+.hypothesis/

.pre-commit-config.yaml

@@ -3,3 +3,18 @@ repos:
     rev: 20.8b1
     hooks:
     - id: black
+-   repo: https://gitlab.com/pycqa/flake8
+    rev: 3.8.4
+    hooks:
+    -   id: flake8
+-   repo: https://github.com/pycqa/isort
+    rev: 5.7.0
+    hooks:
+    -   id: isort
+        name: isort (python)
+    -   id: isort
+        name: isort (cython)
+        types: [cython]
+    -   id: isort
+        name: isort (pyi)
+        types: [pyi]

CONTRIBUTING.rst

@@ -0,0 +1,78 @@
+Contributing guide
+==================
+
+
+Getting started
+^^^^^^^^^^^^^^^
+
+Contributing to scVelo requires a developer installation. As a first step, we suggest creating a new environment
+
+.. code:: bash
+
+    conda create -n ENV_NAME python=PYTHON_VERSION && conda activate ENV_NAME
+
+
+Following, fork the scVelo repo on GitHub `here <https://github.com/theislab/scvelo>`.
+If you are unsure on how to do so, please checkout the corresponding
+`GitHub docs <https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo>`.
+You can now clone your fork of scVelo and install the development mode
+
+.. code:: bash
+
+    git clone https://github.com/YOUR-USER-NAME/scvelo.git
+    cd scvelo
+    git checkout --track origin/develop
+    pip install -e '.[dev]'
+
+The last line can, alternatively, be replaced by
+
+.. code:: bash
+
+    pip install -r requirements-dev.txt
+
+
+Finally, to make sure your code follows our code style guideline, install pre-commit:
+
+.. code:: bash
+
+    pre-commit install
+
+
+Coding style
+^^^^^^^^^^^^
+
+Our code follows `black` and `flake8` coding style. Code formatting (`black`, `isort`) is automated through pre-commit hooks. In addition, we require that
+
+- functions are fully type-annotated.
+- variables referred to in an error/warning message or docstrings are enclosed in \`\`.
+
+
+Testing
+^^^^^^^
+
+To run the implemented unit tests locally, simply run
+
+.. code:: bash
+
+    python -m pytest
+
+
+Documentation
+^^^^^^^^^^^^^
+
+The docstrings of scVelo largely follow the `numpy`-style. New docstrings should
+
+- include neither type hints nor return types.
+- reference an argument within the same docstrings using \`\`.
+
+
+Submitting pull requests
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+New features and bug fixes are added to the code base through a pull request (PR). To implement a feature or bug fix, create a branch from `develop`. For hotfixes use `master` as base. The existence of bugs suggests insufficient test coverage. As such, bug fixes should, ideally, include a unit test or extend an existing one. Please ensure that
+
+- branch names have the prefix `feat/`, `bug/` or `hotfix/`.
+- your code follows the project conventions.
+- newly added functions are unit tested.
+- all tests pass locally.
+- if there is no issue solved by the PR, create one outlining what you try to add/solve and reference it in the PR description.

README.rst

@@ -34,6 +34,7 @@ patients and dynamic processes in human lung regeneration. Find out more in this
 
 Latest news
 ^^^^^^^^^^^
+- Aug/2021: `Perspectives paper out in MSB <https://doi.org/10.15252/msb.202110282>`_
 - Feb/2021: scVelo goes multi-core
 - Dec/2020: Cover of `Nature Biotechnology <https://www.nature.com/nbt/volumes/38>`_
 - Nov/2020: Talk at `Single Cell Biology <https://coursesandconferences.wellcomegenomecampus.org/our-events/single-cell-biology-2020/>`_
@@ -42,11 +43,15 @@ Latest news
 - Sep/2020: Talk at `Single Cell Omics <https://twitter.com/fabian_theis/status/1305621028056465412>`_
 - Aug/2020: `scVelo out in Nature Biotech <https://www.helmholtz-muenchen.de/en/aktuelles/latest-news/press-information-news/article/48658/index.html>`_
 
-Reference
-^^^^^^^^^
+References
+^^^^^^^^^^
+La Manno *et al.* (2018), RNA velocity of single cells, `Nature <https://doi.org/10.1038/s41586-018-0414-6>`_.
+
 Bergen *et al.* (2020), Generalizing RNA velocity to transient cell states through dynamical modeling,
 `Nature Biotech <https://doi.org/10.1038/s41587-020-0591-3>`_.
-|dim|
+
+Bergen *et al.* (2021), RNA velocity - current challenges and future perspectives,
+`Molecular Systems Biology <https://doi.org/10.15252/msb.202110282>`_.
 
 Support
 ^^^^^^^

docs/requirements.txt

@@ -9,5 +9,5 @@ sphinx_autodoc_typehints<=1.6
 
 # converting notebooks to html
 ipykernel
-sphinx>=1.7
-nbsphinx>=0.7
+sphinx>=1.7,<4.0
+nbsphinx>=0.7,<0.8.7

docs/source/_ext/edit_on_github.py

@@ -5,7 +5,6 @@
 import os
 import warnings
 
-
 __licence__ = "BSD (3 clause)"
 
 

docs/source/api.rst

@@ -153,6 +153,12 @@ Datasets
    datasets.pancreas
    datasets.dentategyrus
    datasets.forebrain
+   datasets.dentategyrus_lamanno
+   datasets.gastrulation
+   datasets.gastrulation_e75
+   datasets.gastrulation_erythroid
+   datasets.bonemarrow
+   datasets.pbmc68k
    datasets.simulation
 
 

docs/source/conf.py

@@ -1,50 +1,77 @@
-import sys
-import os
 import inspect
 import logging
-from pathlib import Path
+import os
+import sys
 from datetime import datetime
-from typing import Optional, Union, Mapping
+from pathlib import Path, PurePosixPath
+from typing import Dict, List, Mapping, Optional, Tuple, Union
+from urllib.request import urlretrieve
 
+import sphinx_autodoc_typehints
+from docutils import nodes
+from jinja2.defaults import DEFAULT_FILTERS
+from sphinx import addnodes
 from sphinx.application import Sphinx
+from sphinx.domains.python import PyObject, PyTypedField
+from sphinx.environment import BuildEnvironment
 from sphinx.ext import autosummary
 
+import matplotlib  # noqa
+
+HERE = Path(__file__).parent
+sys.path.insert(0, str(HERE.parent.parent))
+sys.path.insert(0, os.path.abspath("_ext"))
+
+import scvelo  # isort:skip
+
 # remove PyCharm’s old six module
+
 if "six" in sys.modules:
     print(*sys.path, sep="\n")
     for pypath in list(sys.path):
         if any(p in pypath for p in ["PyCharm", "pycharm"]) and "helpers" in pypath:
             sys.path.remove(pypath)
     del sys.modules["six"]
 
-import matplotlib  # noqa
-
 matplotlib.use("agg")
 
-HERE = Path(__file__).parent
-sys.path.insert(0, f"{HERE.parent.parent}")
-sys.path.insert(0, os.path.abspath("_ext"))
-import scvelo
-
 logger = logging.getLogger(__name__)
 
 
-# -- Retrieve notebooks ------------------------------------------------
-
-from urllib.request import urlretrieve
+# -- Basic notebooks and those stored under /vignettes and /perspectives --
 
 notebooks_url = "https://github.com/theislab/scvelo_notebooks/raw/master/"
-notebooks = [
+notebooks = []
+notebook = [
     "VelocityBasics.ipynb",
     "DynamicalModeling.ipynb",
     "DifferentialKinetics.ipynb",
+]
+notebooks.extend(notebook)
+
+notebook = [
     "Pancreas.ipynb",
     "DentateGyrus.ipynb",
+    "NatureBiotechCover.ipynb",
+    "Fig1_concept.ipynb",
+    "Fig2_dentategyrus.ipynb",
+    "Fig3_pancreas.ipynb",
+    "FigS9_runtime.ipynb",
+    "FigSuppl.ipynb",
 ]
+notebooks.extend([f"vignettes/{nb}" for nb in notebook])
+
+notebook = ["Perspectives.ipynb", "Perspectives_parameters.ipynb"]
+notebooks.extend([f"perspectives/{nb}" for nb in notebook])
+
+# -- Retrieve all notebooks --
+
 for nb in notebooks:
+    url = notebooks_url + nb
     try:
-        urlretrieve(notebooks_url + nb, nb)
-    except:
+        urlretrieve(url, nb)
+    except Exception as e:
+        logger.error(f"Unable to retrieve notebook: `{url}`. Reason: `{e}`")
         pass
 
 
@@ -218,7 +245,6 @@ def get_linenos(obj):
 github_url_read_loom = "https://github.com/theislab/anndata/tree/master/anndata"
 github_url_read = "https://github.com/theislab/scanpy/tree/master"
 github_url_scanpy = "https://github.com/theislab/scanpy/tree/master/scanpy"
-from pathlib import PurePosixPath
 
 
 def modurl(qualname):
@@ -253,14 +279,11 @@ def api_image(qualname: str) -> Optional[str]:
 
 
 # modify the default filters
-from jinja2.defaults import DEFAULT_FILTERS
 
 DEFAULT_FILTERS.update(modurl=modurl, api_image=api_image)
 
 # -- Override some classnames in autodoc --------------------------------------------
 
-import sphinx_autodoc_typehints
-
 qualname_overrides = {
     "anndata.base.AnnData": "anndata.AnnData",
     "scvelo.pl.scatter": "scvelo.plotting.scatter",
@@ -292,12 +315,6 @@ def format_annotation(annotation):
 
 # -- Prettier Param docs --------------------------------------------
 
-from typing import Dict, List, Tuple
-from docutils import nodes
-from sphinx import addnodes
-from sphinx.domains.python import PyTypedField, PyObject
-from sphinx.environment import BuildEnvironment
-
 
 class PrettyTypedField(PyTypedField):
     list_type = nodes.definition_list