Metadata-Version: 2.4
Name: tsbrowse
Version: 0.1.1
Summary: Webapp to view and visualise the information structure in tskit ARGs
Author-email: Tskit Developers <admin@tskit.dev>
License-Expression: MIT
Project-URL: Bug Tracker, https://github.com/tskit-dev/tsbrowse/issues
Project-URL: Source Code, https://github.com/tskit-dev/tsbrowse
Project-URL: Homepage, https://tskit.dev/tsbrowse/
Keywords: tree sequence,ancestral recombination graph,tskit,quality control
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: daiquiri
Requires-Dist: panel<=1.6.1,>=1.5.2
Requires-Dist: hvplot
Requires-Dist: datashader>=0.16.3
Requires-Dist: matplotlib
Requires-Dist: tskit
Requires-Dist: tszip
Requires-Dist: zarr>=2.18
Dynamic: license-file

# tsbrowse
[![License](https://img.shields.io/github/license/tskit-dev/tsbrowse)](https://github.com/tskit-dev/tsbrowse/blob/main/LICENSE) [![PyPI version](https://img.shields.io/pypi/v/tsbrowse.svg)](https://pypi.org/project/tsbrowse/) [![Supported Python Versions](https://img.shields.io/pypi/pyversions/tsbrowse.svg)](https://pypi.org/project/tsbrowse/) [![Docs Build](https://github.com/tskit-dev/tsbrowse/actions/workflows/docs.yml/badge.svg)](https://github.com/tskit-dev/tsbrowse/actions/workflows/docs.yml) [![Tests](https://github.com/tskit-dev/tsbrowse/actions/workflows/tests.yml/badge.svg)](https://github.com/tskit-dev/tsbrowse/actions/workflows/tests.yml)
Inspect large genetic genealogies (e.g. ARGs) stored in the [tskit](https://tskit.dev) "succinct tree sequence" format, via a web app.
_Tsbrowse_ can scale to ARGs with millions of samples.

Documentation: https://tskit.dev/tsbrowse/docs/stable/ (latest: https://tskit.dev/tsbrowse/docs/latest/)

It is particularly useful to help evaluate ARGs that have been inferred using tools such as
[tsinfer](https://github.com/tskit-dev/tsinfer),
[sc2ts](https://github.com/tskit-dev/sc2ts),
[Relate](https://github.com/MyersGroup/relate),
[Threads](https://pypi.org/project/threads-arg/), etc.

## Quickstart

## Installation

Install from PyPI:

```
python -m pip install tsbrowse
```

A tskit tree sequence must first be preprocessed to a `.tsbrowse` file:

`python -m tsbrowse preprocess /path/to/trees-file`

This will write a `.tsbrowse` file that can then be viewed using the web app:

`python -m tsbrowse serve /path/to/tsbrowse-file`

This command will launch a web server that can be accessed at `http://localhost:8080` in a web browser.

To display the genes track use:

`python -m tsbrowse serve /path/to/tsbrowse-file --annotations-file genes.csv`

(where `genes.csv` is a semicolon-separated text file containing a header and information about one gene per row in the order: `chr;start;end;strand;ensembl ID;gene name`)

An example tree sequence file can be found here: [example.trees](https://raw.githubusercontent.com/tskit-dev/tsbrowse/refs/heads/main/example/example.trees.tsz).

## Tips

If you are using Windows Subsystem for Linux (WSL) you may need to disable Numba's CUDA support:

`NUMBA_DISABLE_CUDA=1 python -m tsbrowse serve /path/to/tsbrowse-file`

A PNG of a specific page in tsbrowse can be generated using the `screenshot` command:

`python -m tsbrowse screenshot /path/to/tsbrowse-file mutations`


## Development

Tests are run with pytest:

`python -m pytest`

To run the UI tests so you can see what the browser is doing use

`python -m pytest --headed --slowmo 1000 tests/test_ui.py`

`playwright codegen` is also useful for writing UI test code.

## Citing tsbrowse
If you use `tsbrowse` in your work, please cite [this paper](<https://doi.org/10.1093/bioinformatics/btaf393>)
