Merge pull request #241 from icbi-lab/airr-compliance

Improve interoperability by fully supporting the AIRR standard

.conda/meta.yaml

@@ -27,8 +27,8 @@ requirements:
   run:
     - python >=3.7
     - anndata >=0.7.3
-    - scanpy>=1.5.1
-    - pandas>=0.21
+    - scanpy>=1.6.0
+    - pandas>=1.0
     - numpy
     - scipy
     - parasail-python
@@ -37,7 +37,7 @@ requirements:
     - python-igraph
     - networkx
     - squarify
-    - tqdm>=4.29.1
+    - tqdm>=4.42.0
     - airr>=1.2
 
 test:
@@ -54,7 +54,7 @@ test:
   imports:
     - scirpy
   commands:
-    - pytest --pyargs scirpy
+    - pytest --pyargs scirpy -m "not extra"
     - cd docs && jupytext --execute tutorials/tutorial_3k_tcr.md
 
 about:

.github/workflows/docs.yml

@@ -55,8 +55,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
+        # TODO this is to workaround an issue with dandelion's skbio dependency
         run: |
-          pip install .[doc,test,rpack]
+          pip install numpy
+          pip install .[doc,test,rpack,dandelion]
       - name: run sphinx
         run: |
           cd docs && make html SPHINXOPTS="-W --keep-going"

.github/workflows/test.yml

@@ -26,6 +26,10 @@ jobs:
           key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
           restore-keys: |
             ${{ runner.os }}-pip-
+      - name: Install Ubuntu system dependencies
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get install libhdf5-serial-dev
       - name: Install macOS system dependencies
         if: matrix.os == 'macos-latest'
         run: |
@@ -35,8 +39,10 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
+        # TODO the separate numpy installation is to workaround an issue with dandelion's skbio dependency
         run: |
-          pip install .[test,rpack]
+          pip install numpy
+          pip install .[test,rpack,dandelion]
       - name: Check black formatting
         run: |
           black --check .

docs/api.rst

@@ -16,6 +16,13 @@ as closely as possible.
 Input/Output: `io`
 ------------------
 
+.. note::
+   In scirpy v0.7.0 the way VDJ data is stored in `adata.obs` has changed to 
+   be fully compliant with the `AIRR Rearrangement <https://docs.airr-community.org/en/latest/datarep/rearrangements.html#productive>`__ 
+   schema. Please use :func:`~scirpy.io.upgrade_schema` to make `AnnData` objects
+   from previous scirpy versions compatible with the most recent scirpy workflow. 
+
+
 The following functions allow to import :term:`V(D)J` information from various
 formats.
 
@@ -29,19 +36,22 @@ formats.
    read_tracer
    read_bracer
    read_airr
+   write_airr
+   from_dandelion
+   to_dandelion
 
 To convert own formats into the scirpy :ref:`data-structure`, we recommend building
-a list of :class:`~scirpy.io.IrCell` objects first, and then converting them into
-an :class:`~anndata.AnnData` object using :func:`~scirpy.io.from_ir_objs`.
+a list of :class:`~scirpy.io.AirrCell` objects first, and then converting them into
+an :class:`~anndata.AnnData` object using :func:`~scirpy.io.from_airr_cells`.
 For more details, check the :ref:`Data loading tutorial <importing-data>`.
 
 .. autosummary::
    :toctree: ./generated
 
-   IrCell
-   IrChain
-   from_ir_objs
-   to_ir_objs
+   AirrCell
+   from_airr_cells
+   to_airr_cells
+   upgrade_schema
 
 
 Preprocessing: `pp`
@@ -53,6 +63,7 @@ Preprocessing: `pp`
    :toctree: ./generated
 
    merge_with_ir
+   merge_airr_chains
    ir_dist
 
 

docs/conf.py

@@ -75,6 +75,7 @@
     seaborn=("https://seaborn.pydata.org/", None),
     sklearn=("https://scikit-learn.org/stable/", None),
     networkx=("https://networkx.github.io/documentation/networkx-1.10/", None),
+    dandelion=("https://sc-dandelion.readthedocs.io/en/latest/", None),
 )
 
 
@@ -119,8 +120,7 @@ def setup(app):
 # See https://github.com/agronholm/sphinx-autodoc-typehints/issues/38 for more details.
 qualname_overrides = {
     "scipy.sparse.coo.coo_matrix": "scipy.sparse.coo_matrix",
-    "scirpy.io._datastructures.IrCell": "scirpy.io.IrCell",
-    "scirpy.io._datastructures.IrChain": "scirpy.io.IrChain",
+    "scirpy.io._datastructures.AirrCell": "scirpy.io.AirrCell",
     "pandas.core.arrays.categorical.Categorical": "pandas.Categorical",
     "pandas.core.series.Series": "pandas.Series",
 }
@@ -129,4 +129,15 @@ def setup(app):
     ("py:class", "igraph.Graph"),
     ("py:class", "igraph.Layout"),
     ("py:class", "igraph.layout.Layout"),
+    # the following entries are because the `MutableMapping` base class does not
+    # use type hints.
+    ("py:class", "None.  Remove all items from D."),
+    ("py:class", "D[k] if k in D, else d.  d defaults to None."),
+    ("py:class", "a set-like object providing a view on D's items"),
+    ("py:class", "a set-like object providing a view on D's keys"),
+    ("py:class", "v, remove specified key and return the corresponding value."),
+    ("py:class", "(k, v), remove and return some (key, value) pair"),
+    ("py:class", "D.get(k,d), also set D[k]=d if k not in D"),
+    ("py:class", "None.  Update D from mapping/iterable E and F."),
+    ("py:class", "an object providing a view on D's values"),
 ]

docs/references.bib

@@ -409,3 +409,14 @@ @article{Lindeman2018
   title     = {{BraCeR}: B-cell-receptor reconstruction and clonality inference from single-cell {RNA}-seq},
   journal   = {Nature Methods}
 }
+
+@article{Stephenson2021,
+  doi       = {10.1101/2021.01.13.21249725},
+  url       = {https://doi.org/10.1101/2021.01.13.21249725},
+  year      = {2021},
+  month     = jan,
+  publisher = {Cold Spring Harbor Laboratory},
+  author    = {Emily Stephenson and Gary Reynolds and Rachel A Botting and Fernando J Calero-Nieto and Michael Morgan and Zewen Kelvin Tuong and Karsten Bach and Waradon Sungnak and Kaylee B Worlock and Masahiro Yoshida and Natsuhiko Kumasaka and Katarzyna Kania and Justin Engelbert and Bayanne Olabi and Jarmila Stremenova Spegarova and Nicola K Wilson and Nicole Mende and Laura Jardine and Louis CS Gardner and Issac Goh and Dave Horsfall and Jim McGrath and Simone Webb and Michael W. Mather and Rik GH Lindeboom and Emma Dann and Ni Huang and Krzysztof Polanski and Elena Prigmore and Florian Gothe and Jonathan Scott and Rebecca P Payne and Kenneth F Baker and Aidan T Hanrath and Ina CD Schim van der Loeff and Andrew S Barr and Amada Sanchez-Gonzalez and Laura Bergamaschi and Federica Mescia and Josephine L Barnes and Eliz Kilich and Angus de Wilton and Anita Saigal and Aarash Saleh and Sam M Janes and Claire M Smith and Nusayhah Gopee and Caroline Wilson and Paul Coupland and Jonathan M Coxhead and Vladimir Y Kiselev and Stijn van Dongen and Jaume Bacardit and Hamish W King and Anthony J Rostron and A John Simpson and Sophie Hambleton and Elisa Laurenti and Paul A Lyons and Kerstin B Meyer and Marko Z Nikolic and Christopher JA Duncan and Ken Smith and Sarah A Teichmann and Menna R Clatworthy and John C Marioni and Berthold Gottgens and Muzlifah Haniffa and},
+  title     = {The cellular immune response to {COVID}-19 deciphered by single cell multi-omics across three {UK} centres},
+  journal   = {BioRxiv}
+}