Release/0.3.0

.gitignore

@@ -23,3 +23,4 @@ auto_ver.sh
 !docs/source/_static/img/*.jpg
 .venv*
 .nfs*
+build/

README.md

@@ -42,11 +42,12 @@ pip install scmidas
 A bundled 1600-cell PBMC RNA+ADT mosaic dataset lets you go from `pip install` to a UMAP in about a minute on a single GPU — no extra downloads, no config files. Click the [Colab badge](https://colab.research.google.com/github/labomics/midas/blob/main/examples/quickstart.ipynb) to run it without installing anything, or copy the snippet:
 
 ```python
+import scanpy as sc
 import scmidas
 
-mdata = scmidas.datasets.quickstart()      # bundled toy MuData
-model = scmidas.integrate(mdata)           # ~1 min on a mid-range GPU
-out   = model.predict(joint_latent=True)   # latent embeddings per batch
+mdata = scmidas.datasets.quickstart()       # bundled toy MuData
+model = scmidas.integrate(mdata)            # ~1 min on a mid-range GPU; writes mdata.obsm['X_midas']
+sc.pp.neighbors(mdata, use_rep='X_midas')   # any scanpy downstream works directly
 ```
 
 This produces lineage-separated clusters that mix freely across batches:
@@ -57,6 +58,23 @@ This produces lineage-separated clusters that mix freely across batches:
 
 > ⚠️ **`scmidas.integrate()` defaults are tuned for the bundled toy dataset.** For your own data, override `max_epochs` (1000-2000 is typical) and consider letting `batch_size` default back to 256, e.g. `scmidas.integrate(my_mdata, max_epochs=2000, batch_size=256)`. See the [full demos](https://scmidas.readthedocs.io/en/latest/) for end-to-end pipelines on real-sized data, including imputation, batch correction, and cross-modality translation.
 
+## Bring your own data
+
+If you already have an :class:`AnnData` per modality, the bridge to MIDAS is one cell:
+
+```python
+import mudata as mu
+import scmidas
+
+mdata = mu.MuData({'rna': adata_rna, 'adt': adata_adt})  # share a 'batch' obs column
+scmidas.MIDAS.setup_mudata(mdata, batch_key='batch')
+model = scmidas.MIDAS(mdata)
+model.train(max_epochs=2000)
+mdata.obsm['X_midas'] = model.get_latent_representation()
+```
+
+For a full scanpy-native walkthrough (download a 10x CITE-seq sample → QC → HVG → MuData → MIDAS), see [Preparing your data](https://scmidas.readthedocs.io/en/latest/tutorials/basics/preparing_your_data.html). For the data contract (what goes where in the MuData), see [Data layout](https://scmidas.readthedocs.io/en/latest/tutorials/basics/data_layout.html).
+
 ## Reproducibility
 
 Code and data to reproduce the results in the paper live on the [`reproducibility`](https://github.com/labomics/midas/tree/reproducibility) branch.

docs/source/modules/modules_index.rst

@@ -4,8 +4,11 @@ API
 .. toctree::
    :maxdepth: 1
 
+   scmidas.api
    scmidas.config
+   scmidas.datasets
    scmidas.model
+   scmidas.plot
    scmidas.data
    scmidas.nn
    scmidas.utils

docs/source/modules/scmidas.api.rst

@@ -0,0 +1,7 @@
+scmidas.api
+===========
+
+.. automodule:: scmidas.api
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/modules/scmidas.datasets.rst

@@ -0,0 +1,7 @@
+scmidas.datasets
+================
+
+.. automodule:: scmidas.datasets
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/modules/scmidas.plot.rst

@@ -0,0 +1,7 @@
+scmidas.plot
+============
+
+.. automodule:: scmidas.plot
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/release.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## Version 0.3.x
+
+### v0.3.0 (2026-05-09)
+
+Major refresh of the user-facing API around a single :class:`MuData`. The new entry points (`setup_mudata`, `MIDAS(mdata)`, `get_latent_representation`, `get_imputed_values`, `save` / `load`) compose directly with `mdata.obsm`, `sc.pp.neighbors(use_rep=...)`, and the rest of the standard single-cell stack. A new plotting namespace `scmidas.pl` and a data-prep tutorial round out the package for users coming straight from raw 10x output.
+
+*   **🚀 New — `MIDAS` entry points centred on `MuData`**
+    *   `MIDAS.setup_mudata(mdata, batch_key=...)` — register a MuData (writes config to `mdata.uns['_scmidas']`).
+    *   `MIDAS(mdata, ...)` — construct directly from a registered MuData; instance state instead of class-level state (fixes a multi-instance interference bug).
+    *   `model.get_latent_representation(kind='c'|'u'|'joint')` — returns the joint latent aligned to `mdata.obs_names`. Drop straight into `mdata.obsm['X_midas']`.
+    *   `model.get_imputed_values(modality='rna')` — returns imputed counts aligned to `mdata.obs_names`.
+    *   `model.save(dir)` / `MIDAS.load(dir, mdata)` — symmetric save/load (writes `model.pt` + `setup.json`).
+    *   `MIDAS(mdata)` now defaults to `transform={'atac': 'binarize'}` whenever `'atac'` is among the modalities (override by passing your own `transform` dict).
+*   **🚀 New — `scmidas.pl` plotting namespace**
+    *   `scmidas.pl.umap(mdata, basis='X_midas', color=[...])` — one-line UMAP that works around the current scanpy + MuData plotting limitations via a thin AnnData wrapper.
+    *   `scmidas.pl.modality_grid(model, mdata, label_key=...)` — collapses the per-modality vs per-batch grid (~22 lines in the previous demos) into one call. Modality columns are ordered ATAC, RNA, ADT, Joint when present.
+*   **🚀 New — `scmidas.datasets.from_dir`**
+    *   Loads the directory-format datasets (`mat/<m>.mtx`, `mask/<m>.csv`, `feat/feat_dims.toml`) into a `MuData`, including masks, labels, and ATAC chunk dims.
+*   **📚 New tutorial — Preparing your data**
+    *   `docs/source/tutorials/basics/preparing_your_data.ipynb` walks from a public 10x Genomics 5k PBMC CITE-seq sample through QC, HVG selection, MuData wrap, MIDAS integration, Leiden clustering, and a synthetic mosaic example.
+*   **📚 Docs cleanup**
+    *   `inputs.rst` + `outputs.rst` merged into `data_layout.rst` — a single page describing the MuData input/output contract. The directory format is moved to an "advanced" section.
+    *   All three demos (`demo1`, `demo2`, `demo3`) rewritten to use the new API: `from_dir` → `setup_mudata` → `MIDAS(mdata)` → `get_latent_representation`. The 22-line per-modality grid block became `scmidas.pl.modality_grid(model, mdata)`. Each demo gained a 6.4 "After integration" section (Leiden + UMAP).
+    *   README adds a "Bring your own data" section linking the new tutorial and the data-layout reference.
+*   **🛠 Backwards compatibility**
+    *   `MIDAS.configure_data_from_mdata` and `MIDAS.configure_data_from_dir` still work — they emit a `DeprecationWarning` and will be removed in 0.4.0.
+    *   `save_checkpoint` / `load_checkpoint` still work; new code should use `save` / `load`.
+*   **🐛 Fixes**
+    *   `predict(joint_latent=False)` no longer raises `KeyError: 'z_c'`.
+    *   Multiple `MIDAS()` instances in one process now have independent state (was previously class-level — a second instance would clobber the first).
+
+---
+
 ## Version 0.2.x
 
 ### v0.2.0 (2026-05-03)