Metadata-Version: 2.4
Name: arcade-omics
Version: 0.1.0
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.5
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

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:

```bash
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, 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 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.
