Accessors and paths#

anndata.acc provides accessors that create references to axis-aligned 1D and 2D arrays in AnnData objects. You can use these to drive e.g. plotting or validation code. For these purposes, they are

  1. easy to create:

    The central A object is an accessor for the whole AnnData object, and allows you to create AdRef objects, which are references to arrays spanning one or two dimensions of an AnnData object (without being bound to a specific object):

    >>> from anndata.acc import A
>>> A.X[:, "gene-3"]  # reference to `adata[:, "gene-3"].X` as 1D vector
A.X[:, 'gene-3']
>>> type(A.X[:, "gene-3"])
<class 'anndata.acc.AdRef'>

    … and to use:

    >>> import scanpy as sc
>>> adata = sc.datasets.pbmc3k_processed()

    E.g. to check if adata.varm["PCs"] has at least 30 columns:

    >>> A.varm["PCs"][:, 30] in adata
True

    or to extract the referenced vector:

    >>> adata[A.obs["louvain"]].categories[:2]
Index(['CD4 T cells', 'CD14+ Monocytes'], dtype=...)
>>> adata[A.varm["PCs"]]
array([[...
      ...]],... dtype=float32)

  2. introspectible:

    AdRefs have the AdRef.dims, AdRef.idx, and AdRef.acc attributes, allowing you to inspect all relevant properties.

    >>> pc0 = A.obsm["pca"][:, 0]
>>> pc0
A.obsm['pca'][:, 0]
>>> pc0.idx
0
>>> pc0.acc
A.obsm['pca']
>>> A.var["symbol"].dims
{'var'}
>>> pc0.acc.k
'pca'

  3. convenient:

    Want to reference multiple vectors from the same object? Pass a list of indices to the vector accessor:

    >>> A.obsp["connectivities"][:, ["cell0", "cell1"]]
[A.obsp['connectivities'][:, 'cell0'], A.obsp['connectivities'][:, 'cell1']]

  4. extensible: see extending accessors.

API & Glossary#

The central accessor is A:

anndata.acc.A: AdAcc[AdRef] = A#

A global accessor to create AdRefs.

See AdAcc for examples of how to use it to create references (i.e., AdRefs).

AdAcc([ref_class, layer_cls, meta_cls, ...])

Accessor to create AdRefs (A).

AdRef(acc, idx)

A reference to a 1D or 2D array along one or two dimensions of an AnnData object.
reference#

An instance of AdRef. References a 1D or 2D array in AnnData objects. It is independent of individual objects and can be inspected, checked for equality, used as mapping keys, or applied to concrete objects, e.g. via ref in adata or adata[ref]. An example of this would be A.obsm["d"][:, 2] but not A.obsm["d"], which is a reference accessor.

accessor#

An instance of any of the *Acc classes, i.e. AdAcc, or subclasses of MapAcc or RefAcc. Can be descended into via attribute access to get deeper accessors (e.g. A → A.obs) or references (e.g. A.obs.index, A.obs["c"]). Their presence in an anndata object can also be checked via acc in adata.

reference accessor#

RefAcc subclasses directly create references (AdRef instances). They can be accessed from these references using the AdRef.acc attribute, and are therefore useful in matches or isinstance() checks:

RefAcc(*, ref_class)

Abstract base class for reference accessors.

Class

has attributes

available as A.???

Example reference creation

LayerAcc

k

X, layers[key]

A.X[:, :], A.layers["c"][:, "g0"]

MetaAcc

dim

obs, var

A.obs["a"], A.var["b"]

MultiAcc

dim, k

obsm[key], varm[key]

A.obsm["d"][:, 2]

GraphAcc

dim, k

obsp[key], varp[key]

A.obsp["e"][:, "c1"], A.vbsp["e"]["g0", :]
mapping accessor#

MapAcc subclasses can be indexed with a string to create reference accessors, e.g. A.layers or A.obsm are both MapAccs, while A.layers["a"] is a LayerAcc and A.obsm["b"] is a MultiAcc. MapAccs are mostly useful for extending, but might be useful for APIs that need to refer to a Mapping of arrays:

MapAcc()

Accessor for mapping containers.

LayerMapAcc(*, ref_class[, ref_acc_cls])

Accessor for layers (A.layers).

MultiMapAcc(dim, *, ref_class[, ref_acc_cls])

Accessor for multi-dimensional array containers (A.obsm/A.varm).

GraphMapAcc(dim, *, ref_class[, ref_acc_cls])

Accessor for graph containers (A.obsp/A.varp).

Serialization#

references round-trip through JSON-compatible lists via AdAcc.to_json() and AdAcc.from_json():

>>> A.to_json(A.obsm["pca"][:, 0])
['obsm', 'pca', 0]
>>> A.from_json(["obsm", "pca", 0])
A.obsm['pca'][:, 0]

So do the reference accessors they came from, as the same lists without the trailing index:

>>> A.to_json(A.obsm["pca"])
['obsm', 'pca']
>>> A.from_json(["layers", None])
A.X

Pass vec=True or vec=False to from_json() to accept only references or only reference accessors, like AdAcc.resolve() does for strings. MetaAcc (i.e. obs/var) is the exception: only its references are serializable, as it has no array of its own.

Both are described by acc-schema-v1.json, as separate subschemas you can validate against independently using JSON pointers into it: #/$defs/ref matches references, #/$defs/acc reference accessors, and the schema itself either.

Extending accessors#

There are three layers of extensibility:

  1. subclassing AdRef and creating a new AdAcc instance for creating them:

    from matplotlib import pyplot as plt
from anndata.acc import AdAcc, AdRef

class MplRef(AdRef, str):
    """Matplotlib will only treat strings as references, so we subclass `str`."""
    def __new__(cls, acc, idx) -> None:
        obj = str.__new__(cls, str(AdRef(acc, idx)))
        AdRef.__init__(obj, acc, idx)
        return obj

A = AdAcc(ref_class=MplRef)

adata = sc.datasets.pbmc3k_processed()
plt.scatter(*A.obsm["X_umap"][:, [0, 1]], c=A.obs["n_counts"], data=adata)

  2. subclass one or more of the reference accessors, and create a new AdAcc instance:

    >>> from anndata.acc import AdAcc, AdRef, MetaAcc
>>>
>>> class TwoDRef(AdRef):
...     """A reference able to refer to multiple metadata columns."""
...     ...
>>>
>>> class MyMetaAcc(MetaAcc):
...     def __getitem__(self, k):
...         if isinstance(k, list):
...             # override default behavior of returning a list of refs
...             return self.ref_class(self, k)
...         return super().__getitem__(k)
>>>
>>> A = AdAcc(ref_class=TwoDRef, meta_cls=MyMetaAcc)
>>> A.obs[["a", "b"]]
A.obs[['a', 'b']]

    Note that for implementing RefAcc.get() when subclassing, you will need NO_IDX.

  3. subclass AdAcc to add new accessors:

    >>> from dataclasses import dataclass, field
>>> from anndata.acc import AdAcc, MetaAcc
>>>
>>> @dataclass(frozen=True)
... class EHRAcc(AdAcc):
...     tem: MetaAcc = field(init=False)
...     def __post_init__(self) -> None:
...         super().__post_init__()
...         tem = MetaAcc("tem", ref_class=self.ref_class)
...         object.__setattr__(self, "tem", tem)  # necessary because it’s frozen
>>>
>>> A = EHRAcc()
>>> A.tem["visit_id"]
A.tem['visit_id']

To make your subclasses writable (see accessor encoding), register your AdAcc instance as an anndata.acc entry point named after your project, and make sure its to_json() and from_json() round-trip them:

[project.entry-points."anndata.acc"]
my-project = "my_project.acc:A"

anndata picks the entry point whose module is in the same top-level package as your classes, and stores my-project with the written element so it can find your AdAcc when reading it. If no entry point matches, it isn’t named after the project that registers it, or your AdAcc cannot reproduce the original accessor from its JSON form, writing fails instead of losing information.