https://github.com/tskit-dev/tsbrowse

Utilities for evaluating inferred tree sequences
https://github.com/tskit-dev/tsbrowse

Last synced: 3 months ago
JSON representation

Utilities for evaluating inferred tree sequences

• Host: GitHub
• URL: https://github.com/tskit-dev/tsbrowse
• Owner: tskit-dev
• License: mit
• Created: 2023-04-04T14:10:30.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2025-09-29T14:46:11.000Z (7 months ago)
• Last Synced: 2025-11-04T09:23:05.594Z (6 months ago)
• Language: Python
• Homepage:
• Size: 29.3 MB
• Stars: 4
• Watchers: 5
• Forks: 8
• Open Issues: 24
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: docs/contributing.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# 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/jeromekelleher/sc2ts),

[Relate](https://github.com/MyersGroup/relate),

[KwARG](https://github.com/a-ignatieva/kwarg),

[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.