Update API page

scverse · Apr 12, 2021 · 4e922df · 4e922df
1 parent 4518410
commit 4e922df
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 17 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -16,18 +16,23 @@ as closely as possible.
 Input/Output: `io`
 ------------------
 
+.. module:: scirpy.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. 
 
+   .. autosummary::
+      :toctree: ./generated
+
+      upgrade_schema
+
 
 The following functions allow to import :term:`V(D)J` information from various
 formats.
 
-.. module:: scirpy.io
-
 .. autosummary::
    :toctree: ./generated
 
@@ -36,8 +41,14 @@ formats.
    read_tracer
    read_bracer
    read_airr
-   write_airr
    from_dandelion
+
+Scirpy can export data to the following formats:
+
+.. autosummary::
+   :toctree: ./generated
+
+   write_airr
    to_dandelion
 
 To convert own formats into the scirpy :ref:`data-structure`, we recommend building
@@ -51,7 +62,6 @@ For more details, check the :ref:`Data loading tutorial <importing-data>`.
    AirrCell
    from_airr_cells
    to_airr_cells
-   upgrade_schema
 
 
 Preprocessing: `pp`

diff --git a/docs/usage-principles.rst b/docs/usage-principles.rst
@@ -22,7 +22,7 @@ Scirpy is an extension to `Scanpy <https://scanpy.readthedocs.io>`_ and adheres
  * The :class:`~anndata.AnnData` instance is modified inplace, unless the functions
    is called with the keyword argument `inplace=False`.
 
-We decided to handle a few minor points differenlty to Scanpy:
+We decided to handle a few minor points differently to Scanpy:
 
  * Plotting functions with inexpensive computations (e.g. :func:`scirpy.pl.clonal_expansion`)
    call the corresponding tool (:func:`scirpy.tl.clonal_expansion`) on-the-fly and

diff --git a/scirpy/io/_io.py b/scirpy/io/_io.py
@@ -339,9 +339,7 @@ def read_airr(
     include_fields: Optional[Collection[str]] = DEFAULT_AIRR_FIELDS,
 ) -> AnnData:
     """\
-    Read AIRR-compliant data.
-
-    Reads data organized in the `AIRR rearrangement schema <https://docs.airr-community.org/en/latest/datarep/rearrangements.html>`_.
+    Read data from `AIRR rearrangement <https://docs.airr-community.org/en/latest/datarep/rearrangements.html>`_ format.
 
     The following columns are required by scirpy: 
      * `cell_id`
@@ -558,7 +556,7 @@ def read_bracer(path: Union[str, Path]) -> AnnData:
 
 @_check_upgrade_schema()
 def write_airr(adata: AnnData, filename: Union[str, Path]) -> None:
-    """Write immune receptor fields from `adata.obs` in AIRR Rearrangement TSV format.
+    """Export :term:`IR` data to :term:`AIRR` Rearrangement `tsv` format.
 
     Parameters
     ----------
@@ -629,8 +627,7 @@ def upgrade_schema(adata) -> None:
 
 @_check_upgrade_schema()
 def to_dandelion(adata: AnnData):
-    """
-    Convert a scirpy-initialized AnnData object to Dandelion format using `to_ir_objs`.
+    """Export data to `Dandelion <https://github.com/zktuong/dandelion>`_ (:cite:`Stephenson2021`).
 
     Parameters
     ----------
@@ -640,7 +637,6 @@ def to_dandelion(adata: AnnData):
     Returns
     -------
     `Dandelion` object.
-
     """
     try:
         import dandelion as ddl
@@ -664,8 +660,12 @@ def to_dandelion(adata: AnnData):
     return ddl.Dandelion(ddl.load_data(data))
 
 
+@_doc_params(doc_working_model=doc_working_model)
 def from_dandelion(dandelion, transfer=False) -> AnnData:
-    """Import data from `Dandelion <https://github.com/zktuong/dandelion>`_ (:cite:`Stephenson2021`).
+    """\
+    Import data from `Dandelion <https://github.com/zktuong/dandelion>`_ (:cite:`Stephenson2021`).
+
+    {doc_working_model}
 
     Parameters
     ----------

diff --git a/scirpy/io/_util.py b/scirpy/io/_util.py
@@ -7,13 +7,13 @@
 
 .. note::
     Reading data into *Scirpy* has the following constraints:
-     * each cell can have up to four productive chains chains (:term:`Dual IR`):
+     * Each cell can have up to four productive chains chains (:term:`Dual IR`):
        two :term:`VJ<V(D)J>` and two :term:`VDJ<V(D)J>` chains. 
      * Excess chains are ignored (those with lowest read count/:term:`UMI` count)
        and cells flagged as :term:`Multichain-cell`.
-     * non-productive chains are ignored. 
-     * chain loci must be valid :term:`IGMT locus names<Chain locus>`.
-     * excess chains, non-productive chains, or chains with invalid loci
+     * Non-productive chains are ignored. 
+     * Chain loci must be valid :term:`IGMT locus names<Chain locus>`.
+     * Excess chains, non-productive chains, or chains with invalid loci
        are serialized to JSON and stored in the `extra_chains` column. They are not 
        used by scirpy except when exporting the `AnnData` object to AIRR format.