Metadata-Version: 2.4
Name: arcade-omics
Version: 0.1.1
Summary: ARCADE: spatial mosaic multi-omics integration with reference-guided negative-binomial deconvolution
Author: Shucun Xiong
Project-URL: Homepage, https://github.com/HokazeJunko/ARCADE
Project-URL: Documentation, https://arcade-omics.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/HokazeJunko/ARCADE
Project-URL: Issues, https://github.com/HokazeJunko/ARCADE/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: anndata>=0.10
Requires-Dist: annoy>=1.17
Requires-Dist: harmony-pytorch>=0.1.8
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy<2.3,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scanpy>=1.10
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.10
Requires-Dist: torch>=2.3
Requires-Dist: torch-geometric>=2.6
Requires-Dist: torch-scatter>=2.1
Requires-Dist: tqdm>=4.66
Provides-Extra: docs
Requires-Dist: nbsphinx==0.9.8; extra == "docs"
Requires-Dist: sphinx==9.1.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "docs"

# 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](docs/installation.rst)
2. [Data preparation](docs/data.rst)
3. [Four step-by-step tutorials](docs/tutorials.rst)
4. [Result evaluation](docs/evaluation.rst)
5. [API reference](docs/api.rst)

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

ARCADE documents two environments that have been run with the public
workflow:

| Environment | OS | Python | PyTorch | CUDA | PyTorch Geometric |
| --- | --- | --- | --- | --- | --- |
| Paper environment | Linux | 3.11 | 2.3.0 | 12.1 | 2.7.0 |
| Compatibility-tested environment | Linux | 3.12 | 2.8.0 | 12.8 | 2.6.1 |

For paper reproduction, clone the repository and create the curated Conda
environment. The full exported package snapshot is retained separately as
`environments/paper-lock.yml` for provenance.

```bash
git clone https://github.com/HokazeJunko/ARCADE.git
cd ARCADE
conda env create -f environments/paper.yml
conda activate arcade-paper
pip install -e . --no-deps
```

For the compatibility-tested PyTorch 2.8/CUDA 12.8 environment, install the
matching compiled PyTorch Geometric extensions before ARCADE:

```bash
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128
pip install torch_scatter torch_sparse \
  -f https://data.pyg.org/whl/torch-2.8.0+cu128.html
```

Install the released package from PyPI:

```bash
pip install arcade-omics
```

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

```bash
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](https://arcade-omics.readthedocs.io/en/latest/installation.html).

## Quick import check

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

The legacy import remains available for the confirmed final notebooks:

```python
import mosaic_core
```

New code should use:

```python
import arcade_omics
```

## Run the final workflows

Human Tonsil:

```bash
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:

```bash
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:

```bash
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):

![ARCADE Human Tonsil cell-type proportions](https://raw.githubusercontent.com/HokazeJunko/ARCADE/main/docs/_static/results/human_tonsil/human_tonsil_section1_cell_type_proportion_top12.png)

## Data availability

The Human Tonsil and Mouse Brain source datasets are publicly available, but
the tutorial-ready processed H5AD files are not distributed in this
repository. Do not add H5AD files or generated outputs to Git. See the
[data preparation page](https://arcade-omics.readthedocs.io/en/latest/data.html)
for official source accessions, download pages, exact input filenames, and the
recommended 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.
