Usage Principles — episcanpy 0.0.1 documentation

# Usage Principles

Import the Scanpy API as:

    import episcanpy.api as epi

## Workflow

The typical workflow consists of subsequent calls of data analysis tools in `sc.tl`, e.g.:

    sc.tl.tsne(adata, **tool_params)  # embed the data using tSNE

where `adata` is an `AnnData` object. Each of these calls adds annotation to an expression matrix X, which stores n_obs observations (cells) of n_vars variables (genes). For each tool, there typically is an associated plotting function in `sc.pl`:

    sc.pl.tsne(adata, **plotting_params)

If you pass `show=False`, a `matplotlib.axes.Axes` instance is returned and you have all of matplotlib’s detailed configuration possibilities.

To facilitate writing memory-efficient pipelines, by default, Scanpy tools operate inplace on `adata` and return `None` - this also allows to easily transition to out-of-memory pipelines. If you want to return a copy of the `AnnData` object and leave the passed `adata` unchanged, pass `copy=True`.

## AnnData

Scanpy is based on `anndata`, which provides the `AnnData` class.

At the most basic level, an `AnnData` object `adata` stores a data matrix (`adata.X`), dataframe-like annotation of observations (`adata.obs`) and variables (`adata.var`) and unstructured dict-like annotation (`adata.uns`). Values can be retrieved and appended via `adata.obs['key1']` and `adata.var['key2']`. Names of observations and variables can be accessed via `adata.obs_names` and `adata.var_names`, respectively. `AnnData` objects can be sliced like dataframes, for example, `adata_subset = adata[:, list_of_gene_names]`. For more, see this blog post.

To read a data file to an `AnnData` object, call:

    adata = sc.read(filename)

to initialize an `AnnData` object. Possibly add further annotation using, e.g., `pd.read_csv`:

    import pandas as pd
    anno = pd.read_csv(filename_sample_annotation)
    adata.obs['cell_groups'] = anno['cell_groups']  # categorical annotation of type pandas.Categorical
    adata.obs['time'] = anno['time']                # numerical annotation of type float
    # alternatively, you could also set the whole dataframe
    # adata.obs = anno

To write, use:

    adata.write(filename)
    adata.write_csvs(filename)
    adata.write_loom(filename)