Metadata-Version: 2.4
Name: argscape
Version: 0.7.1
Summary: ARGscape: interactive ARG visualization and analysis
Author-email: Chris Talbot <cat267@cornell.edu>
License-Expression: MIT
Project-URL: Homepage, https://argscape.com
Project-URL: Documentation, https://argscape.com/docs
Project-URL: Repository, https://github.com/chris-a-talbot/argscape
Project-URL: Paper, https://arxiv.org/abs/2510.07255
Keywords: ARG,ancestral recombination graph,tree sequence,population genetics,visualization,spatial inference,temporal inference
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas
Requires-Dist: tskit>=0.5.0
Requires-Dist: tszip>=0.2.3
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Requires-Dist: matplotlib
Requires-Dist: pydantic
Provides-Extra: spatial
Requires-Dist: geopandas>=0.14.1; extra == "spatial"
Requires-Dist: shapely>=2.0.2; extra == "spatial"
Requires-Dist: pyproj>=3.4.0; extra == "spatial"
Requires-Dist: fiona>=1.9.5; extra == "spatial"
Requires-Dist: fastapi; extra == "spatial"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "spatial"
Requires-Dist: python-multipart>=0.0.6; extra == "spatial"
Requires-Dist: apscheduler>=3.10.4; extra == "spatial"
Requires-Dist: cryptography>=41.0.0; extra == "spatial"
Requires-Dist: tsdate; extra == "spatial"
Requires-Dist: fastgaia; extra == "spatial"
Requires-Dist: geoancestry; extra == "spatial"
Requires-Dist: msprime>=1.0.0; extra == "spatial"
Requires-Dist: sympy; extra == "spatial"
Provides-Extra: docs
Requires-Dist: jupyter-book<2.0,>=1.0; extra == "docs"
Requires-Dist: sphinx-book-theme>=1.1; extra == "docs"
Requires-Dist: myst-nb>=1.0; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Provides-Extra: all
Requires-Dist: argscape[spatial]; extra == "all"
Requires-Dist: playwright>=1.40; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/chris-a-talbot/argscape/dev/.github/images/banner.png" alt="ARGscape Banner">
</p>

#

**ARGscape** is a visualization and analysis toolkit for ancestral recombination graphs (ARGs) encoded as tree sequences. Use it as a Python library in Jupyter notebooks, as a command-line tool, or through the web application.

```python
import argscape
import msprime

ts = msprime.sim_ancestry(samples=10, sequence_length=1e4, recombination_rate=1e-8)
viz = argscape.visualize(ts)
viz.show()  # Opens interactive visualization in browser
```

## Links

- **Web App**: [argscape.com](https://argscape.com)
- **Documentation**: [argscape.com/docs](https://argscape.com/docs)
- **Paper**: [arxiv.org/abs/2510.07255](https://arxiv.org/abs/2510.07255)

## Installation

### Python Package (Recommended)

```bash
# Basic installation (visualization only)
pip install argscape

# With spatial inference support
# Requires spatial dependencies pre-installed
# Conda installation recommended - see below
pip install argscape[spatial]
```

### Conda Environment (Full Features)

For the complete toolkit including all inference methods:

```bash
# Download environment file from GitHub or argscape.com/install
conda env create -f environment.yml
conda activate argscape_local
```

## Quick Start

### Python API

```python
import argscape

# Load and visualize a tree sequence
ts = tskit.load("example.trees")
viz = argscape.visualize(ts)
viz.display()  # Jupyter notebook
viz.show()     # Browser
viz.export("figure.png", dpi=300)  # Export

# Run spatial inference
result = argscape.infer(ts, method="fastgaia")
result.ts  # Tree sequence with inferred locations
```

### Web Application

```bash
# Start the web app locally
argscape serve

# Or visit argscape.com for the hosted version
```

### Command Line

```bash
# Run inference from terminal
argscape infer run --input data.trees --method fastgaia --output ./results
```

## Features

### Visualization

| Feature | Description |
|---------|-------------|
| **2D Force Graph** | Interactive force-directed ARG layout with D3.js |
| **3D Spatial** | Geographic visualization with Three.js for spatially-embedded data |
| **Themes** | Four built-in themes: `liquid`, `tskit`, `paper`, `grayscale` |
| **Custom Colors** | Override any theme color for publication figures |
| **Filtering** | Genomic range and temporal filtering with interactive sliders |
| **Export** | PNG, SVG, and PDF export at custom DPI |

### Spatial Inference

Estimate ancestral locations from sample coordinates:

| Method | Description | Speed |
|--------|-------------|-------|
| `midpoint` | Weighted midpoint of descendants | Fast |
| `fastgaia` | Fast GAIA algorithm | Fast |
| `gaia-quadratic` | GAIA with quadratic cost | Medium |
| `gaia-linear` | GAIA with linear cost | Medium |

```python
# Infer locations and visualize in 3D
result = argscape.infer(ts, method="fastgaia")
viz = argscape.visualize(result.ts, mode="spatial_3d")
viz.show()
```

### Interactive Controls

When using `.show()` or `.display(show_controls=True)`:

| Control | Key | Description |
|---------|-----|-------------|
| Nodes | N | Adjust sizes, toggle labels |
| Edges | E | Width and opacity |
| Mutations | M | Toggle markers |
| Layout | L | Sample ordering, spacing |
| Theme | T | Switch themes |
| Stats | I | View ARG statistics |
| Export | X | Save visualization |

## Gallery

### 2D Network Visualization

![2D ARG Visualization](https://raw.githubusercontent.com/chris-a-talbot/argscape/dev/.github/images/2D.png)

### 3D Spatial Visualization

![3D ARG Visualization](https://raw.githubusercontent.com/chris-a-talbot/argscape/dev/.github/images/3D.png)

## CLI Reference

### `argscape` - Web Application

```bash
argscape [--port PORT] [--no-browser] [--no-tsdate]
```

### `argscape infer` - Spatial Inference

```bash
# Interactive mode
argscape infer

# Direct execution
argscape infer run --input data.trees --method fastgaia --output ./results

# Session management
argscape infer load --file data.trees --name mydata
argscape infer list
```

### `argscape load` - Session Storage

```bash
argscape load load --file data.trees --name mydata
argscape load list
argscape load rm --name mydata
```

## Development

```bash
# Clone repository
git clone https://github.com/chris-a-talbot/argscape.git
cd argscape

# Backend
conda env create -f argscape/api/environment.yml
conda activate argscape_local
pip install -e .
uvicorn argscape.api.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend && npm install && npm run dev
```

## Citation

If you use ARGscape in your research, please cite:

> Talbot, C., & Bradburd, G. (2025). ARGscape: A modular, interactive tool for manipulation of spatiotemporal ancestral recombination graphs. *arXiv*. https://arxiv.org/abs/2510.07255

## License

MIT License

## Acknowledgments

- **tskit team** for the tree sequence toolkit and feedback
- **Bradburd Lab** for funding, support, and the GAIA algorithms
- **James Kitchens and Coop Lab** for testing and the SPARG and spacetrees algorithms
- **Messer Lab** for continued support

---

**Documentation**: [argscape.com/docs](https://argscape.com/docs) | **Issues**: [GitHub](https://github.com/chris-a-talbot/argscape/issues)
