ARCADE

ARCADE is a research implementation for spatial mosaic multi-omics integration with reference-guided negative-binomial deconvolution.

The public package is being organized from the final Human Tonsil and Mouse Brain experiment notebooks. Reproduction fidelity is the primary design constraint: dataset-specific preprocessing, modality layouts, graph settings, reference construction, training, and evaluation are retained as separate workflows.

Documentation

Documentation is available through Read the Docs:

https://arcade-omics.readthedocs.io/en/latest/

It includes:

• installation and data preparation guides
• complete Human Tonsil and Mouse Brain tutorials
• validated result visualizations and evaluation metrics
• reproducibility notes
• API reference

A new user should follow the documentation in this order:

1. Installation
2. Data preparation
3. Four step-by-step tutorials
4. Result evaluation
5. API reference

The tutorials contain complete final commands, expected outputs, plotting code, representative 200-epoch results, and explanations of what each figure does and does not represent.

Current contents

• arcade_omics/: the canonical Python API
• mosaic_core/: compatibility imports for the final experiment notebooks
• scripts/run_human_tonsil.py: parameterized final Human Tonsil workflow
• scripts/run_mouse_brain.py: parameterized final Mouse Brain workflow
• docs/: Sphinx and Read the Docs sources

The two original final notebooks are retained locally as line-by-line references, but are ignored by Git because they contain internal absolute paths. Their dataset-specific calculations are represented by the two public scripts instead of publishing private server paths.

Installation

The validated development environment is Linux, Python 3.12, PyTorch 2.8.0 with CUDA 12.8, and PyTorch Geometric 2.6.1. Install PyTorch first, then install the matching PyTorch Geometric extension wheels. For the validated server environment:

pip install torch_scatter torch_sparse \
  -f https://data.pyg.org/whl/torch-2.8.0+cu128.html

Install the released package from PyPI:

pip install arcade-omics

To run the repository scripts or contribute code, clone the real repository and install the source checkout in editable mode:

git clone https://github.com/HokazeJunko/ARCADE.git
cd ARCADE
pip install -e .

For another PyTorch or CUDA version, select the matching extension wheel index before installing ARCADE. The complete environment notes are in the installation guide.

Quick import check

python -c "import arcade_omics; print(arcade_omics.__version__)"

The legacy import remains available for the confirmed final notebooks:

import mosaic_core

New code should use:

import arcade_omics

Run the final workflows

Human Tonsil:

python scripts/run_human_tonsil.py \
  --data-dir /path/to/data/human_tonsil \
  --output-dir /path/to/results/human_tonsil \
  --gpu 0 \
  --epochs 200

Mouse Brain:

python scripts/run_mouse_brain.py \
  --data-dir /path/to/data/mouse_brain \
  --output-dir /path/to/results/mouse_brain \
  --gpu 0 \
  --epochs 200

These commands use the confirmed final optimization settings by default. See the RTD tutorial sources under docs/ for exact input and output filenames.

The formal reproduction value is --epochs 200. A one-epoch run is only an installation smoke test and is not used for the published result figures.

Evaluation is intentionally separate. The public scripts scripts/evaluate_human_tonsil.py and scripts/evaluate_mouse_brain.py retain the final notebook metrics and annotation conventions. External annotations and comparison-method outputs are not included; their expected filenames are documented in docs/evaluation.rst.

Result visualization

The formal plotting scripts read saved outputs and do not rerun preprocessing or training:

python scripts/plot_human_tonsil_results.py \
  --result-dir outputs/human_tonsil \
  --figure-dir outputs/human_tonsil/figures

python scripts/plot_mouse_brain_results.py \
  --result-dir outputs/mouse_brain \
  --figure-dir outputs/mouse_brain/figures

Continuous spatial proportions use a shared per-cell-type turbo scale across sections; categorical colors remain fixed. Main plots are written as 300 dpi PNG and vector PDF. ARCADE does not claim denoised-expression outputs because the confirmed final workflows do not generate them.

The documentation uses the same result-display policy as the validated experiments: complete numeric outputs and individual cell-type maps are retained, while overview pages show a readable representative subset. Human Tonsil uses one globally selected top-12 set in all four panels; Mouse Brain has ten coarse cell types, so all ten are shown.

Representative Human Tonsil result (Section 1, shared top-12 display set):

Data availability

The validated Human Tonsil and Mouse Brain datasets are not distributed in this repository. Do not add H5AD files or generated outputs to Git. See the documentation data page for the exact expected filenames and directory tree.

Reproduction policy

ARCADE does not merge the two experiments into a synthetic one-size-fits-all pipeline. In particular, the following differences are preserved:

• Human Tonsil uses four sections with a partial RNA/ADT mosaic.
• Mouse Brain uses three paired sections with RNA and section-specific H3K27ac, H3K27me3, or ATAC gene-activity modalities.
• Coordinate repair, barcode alignment, reference grouping, preprocessing, graph weights, and evaluation annotations remain experiment-specific.

Citation and license

Formal citation and license information will be added after confirmation by the project authors.