Full accessor support

.pre-commit-config.yaml

@@ -12,11 +12,11 @@ repos:
       - id: biome-format
         exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.24.1
+    rev: v2.25.0
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.17
+    rev: v0.15.18
     hooks:
       - id: ruff-check
         types_or: [python, pyi, jupyter]

CHANGELOG.md

@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning][].
 
 ## [0.4.0] (Unreleased)
 
+### Added
+
+- MuData accessors. These are similar to and build on [AnnData accessors](https://anndata.scverse.org/page/accessors.html), but add an additional
+  level for modalities.
+
 ### Changed
 
 - `update()` no longer automatically pulls obs/var columns from individual modalities by default. Set `mudata.set_options(pull_on_update=true)`

docs/_templates/autosummary/class-accessor.rst

@@ -0,0 +1,28 @@
+{{ fullname | escape | underline}}
+
+{%if fullname == "mudata.acc.MuAcc" %}
+{% set attributes = attributes | select("ne", "X") | select("ne", "layers") %}
+{% endif %}
+
+.. currentmodule:: {{ module }}
+
+..  autoclass:: {{ objname }}
+    :show-inheritance:
+
+    {% block attributes %}
+    {%- for item in attributes %}
+    {%- if loop.first %}
+    .. rubric:: Attributes
+    {% endif %}
+    .. autoattribute:: {{ item }}
+    {%- endfor %}
+    {% endblock %}
+
+    {% block methods %}
+    {%- for item in methods if item != "__init__" and item not in inherited_members %}
+    {%- if loop.first %}
+    .. rubric:: Methods
+    {% endif %}
+    .. automethod:: {{ item }}
+    {%- endfor %}
+    {% endblock %}

docs/accessors.md

@@ -0,0 +1,35 @@
+# Accessors and paths
+
+```{eval-rst}
+.. module:: mudata.acc
+```
+
+[](#mudata.acc) provides [accessors](inv:anndata:*:term#accessor) that create [references](inv:anndata:*:term#reference) to axis-aligned 1D and 2D arrays in [MuData](#mudata.MuData) objects.
+See the corresponding [AnnData documentation](inv:anndata:*:doc#accessors).
+
+:::{important}
+This functionality requires AnnData 0.13 or newer.
+:::
+
+The central [accessor](inv:anndata:*:term#accessor) is [](#A).
+```{eval-rst}
+.. autodata:: A
+```
+See [](#MuAcc) and [AdAcc](#anndata.acc.AdAcc) for examples of how to use it to create [references](inv:anndata:*:term#reference) (i.e. [AdRefs](#anndata.acc.AdRef)).
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated
+   :template: class-accessor
+
+   MuAcc
+   MultiModAcc
+   ModAcc
+   ModMapAcc
+   ModMetaAcc
+   ModLayerAcc
+   ModGraphAcc
+   ModMultiAcc
+   ModMultiMapAcc
+   ModGraphMapAcc
+```

docs/api.md

@@ -35,6 +35,14 @@
    write_zarr
 ```
 
+## Accessors
+```{eval-rst}
+.. toctree::
+   :hidden:
+
+   mudata.acc <accessors>
+```
+
 ## Extensions
 ```{eval-rst}
 .. autosummary::

docs/conf.py

@@ -15,6 +15,7 @@
 
 HERE = Path(__file__).parent
 sys.path.insert(0, str(HERE / "extensions"))
+acc_schema = HERE.parent / "src/mudata/acc/acc-schema-v1.json"
 
 
 # -- Project information -----------------------------------------------------
@@ -120,6 +121,7 @@
 #
 html_theme = "sphinx_book_theme"
 html_static_path = ["_static"]
+html_extra_path = [str(acc_schema)]
 html_logo = "_static/img/mudata.svg"
 html_css_files = ["css/custom.css"]
 
@@ -135,8 +137,11 @@
 pygments_style = "default"
 katex_prerender = shutil.which(katex.NODEJS_BINARY) is not None
 
-nitpick_ignore = [
+nitpick_ignore = (
     # If building the documentation fails because of a missing link that is outside your control,
     # you can add an exception to this list.
     #     ("py:class", "igraph.Graph"),
-]
+    ("py:obj", "typing.R"),
+    ("py:obj", "anndata.acc.Axes"),
+    ("py:class", "AdRef"),
+)

docs/extensions/skip_private_bases.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, get_origin
+
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def skip_private_bases(app: Sphinx, name: str, obj: type, _unused, bases: list[type]) -> None:
+    bases[:] = [b for b in bases if b is not object if get_origin(b) is not Generic if not b.__name__.startswith("_")]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.connect("autodoc-process-bases", skip_private_bases)
+    return ExtensionMetadata(parallel_read_safe=True)

pyproject.toml

@@ -48,8 +48,9 @@ dev = [
   "pre-commit",
   "twine>=4.0.2",
 ]
-test = [ "coverage>=7.10", "mudata[io]", "packaging", "pytest" ]
+test = [ "coverage>=7.10", "jsonschema", "mudata[io]", "packaging", "pytest", "referencing" ]
 doc = [
+  "anndata>=0.13rc1",
   "docutils>=0.8,!=0.18.*,!=0.19.*",
   "ipykernel",
   "ipython",
@@ -124,7 +125,7 @@ lint.ignore = [
   "TID252", # allow relative imports
 ]
 lint.per-file-ignores."*/__init__.py" = [ "F401" ]
-lint.per-file-ignores."docs/*" = [ "I" ]
+lint.per-file-ignores."docs/*" = [ "D", "I" ]
 lint.per-file-ignores."docs/notebooks/*" = [ "D", "F403", "F405" ]
 lint.per-file-ignores."tests/*" = [ "D" ]
 lint.pydocstyle.convention = "numpy"

src/mudata/__init__.py

@@ -1,5 +1,7 @@
 """Multimodal datasets"""
 
+from contextlib import suppress
+
 from anndata import AnnData
 from scverse_misc import ExtensionNamespace
 from scverse_misc import make_register_namespace_decorator as _make_register_namespace_decorator
@@ -51,3 +53,8 @@
     "register_mudata_namespace",
     "ExtensionNamespace",
 ]
+
+with suppress(ImportError):
+    from . import acc
+
+    __all__.append("acc")

src/mudata/_core/mudata.py

@@ -556,8 +556,17 @@ def __contains__(self, key) -> bool:
         with suppress(ImportError):
             from anndata.acc import AdRef, MapAcc, RefAcc
 
-            if isinstance(key, AdRef | RefAcc | MapAcc):
+            from ..acc import ModAcc, MultiModAcc, _ModalityMapAcc, _ModalityMixin
+
+            if isinstance(key, ModAcc | _ModalityMapAcc):
+                return key.isin(self)
+            elif isinstance(key, _ModalityMixin):
+                return key in self.mod[key.mod]
+            elif isinstance(key, MultiModAcc):
+                return bool(self.mod)
+            elif isinstance(key, AdRef | RefAcc | MapAcc):
                 return AnnData.__contains__(self, key)
+
         raise TypeError(f"Unexpected key {key!r}.")
 
     @property