From 7bd61d55ac256e688eb1da7b019a3f1324542cf8 Mon Sep 17 00:00:00 2001 From: Savita Karthikeyan Date: Fri, 25 Oct 2024 11:28:48 +0100 Subject: [PATCH] Complete docs --- docs/contributing.md | 46 +++++++++++++++++++++++++++++++++++++++++++- docs/edges.md | 2 +- docs/index.md | 23 +++++++++++++++++++--- docs/install.md | 21 +++++++++++++++++++- docs/intro.md | 29 +++++++++++++++++++++++++--- docs/trees.md | 6 +++++- 6 files changed, 117 insertions(+), 10 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 85f112a..e1ff3ba 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -7,5 +7,49 @@ there is anything missing, please open an [issue](https://github.com/tskit-dev/t or [pull request](https://github.com/tskit-dev/tsbrowse/pulls) on Github. ## Quick start +### Using a virtual environment +First, set up a virtual environment: +``` +$ python3 -m venv tsbrowse_env +``` +Then, activate the virtual environment: +``` +$ source tsbrowse_env/bin/activate +``` +Within the virtual environment, install requirements: +``` +$ python3 -m pip install -r requirements.txt +``` -TODO! Add information for developers here. +### Github workflow +1. Fork the tsbrowse github repository at https://github.com/tskit-dev/tsbrowse/ to create your own copy of the project. + +2. Clone a local copy: +``` +$ git clone https://github.com/your-user-name/tsbrowse.git +$ cd tsbrowse +$ git remote add upstream https://github.com/tskit-dev/tsbrowse.git +``` +This creates the directory tsbrowse and connects your repository to the upstream (main project) tsbrowse repository. +3. Install pre-commit hooks. These will be executed automatically on every commit, to ensure the code meets development requirements. +``` +$ pre-commit install +``` +4. Run the test suite and make sure tests pass: +``` +$ python3 -m pytest +``` +5. Create a topic branch and add commits: +``` +$ git fetch upstream +$ git checkout upstream/main +$ git checkout -b topic_branch_name +``` +6. When you are ready to share your contribution, push changes to your fork: +``` +$ git push origin branch-name +``` +7. Create a [pull request](https://help.github.com/articles/about-pull-requests/) on GitHub. + +### Documentation +Tsbrowse documentation is written in markdown. These files are contained in the docs directory. To build the documentation, run `make` in the `docs` directory. diff --git a/docs/edges.md b/docs/edges.md index a13d954..cf0ddb4 100644 --- a/docs/edges.md +++ b/docs/edges.md @@ -13,4 +13,4 @@ The bottom panel contains three static histograms which, left to right, summaris ## Plot controls (sidebar): * The `log y-axis` checkbox plots node time on log scale. -* The checkbox group allows switching between the nodes represented on the Y-axis (parent or child). \ No newline at end of file +* The checkbox group allows switching between the nodes represented on the Y-axis (parent or child). diff --git a/docs/index.md b/docs/index.md index 4ecd52a..bd220a3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,24 @@ (sec_tsbrowse_docs_mainpage)= -# Tsbrowse documentation +# Tsbrowse documentation -tsbrowse is an open-source Python package for visualising ARGs in the [tskit](https://tskit.dev/tskit/docs/) tree sequence format. +This is the documentation for tsbrowse, an open-source Python package for visualising ARGs in the [tskit](https://tskit.dev/tskit/docs/) tree sequence format. -TODO! Add links to other pages +## Contents +### Getting started +This section includes an introduction to tsbrowse, amd notes on how to install and use the app. + [Introduction](intro.md) + [Installing tsbrowse](install.md) +### Pages +This section provides an overview of the various pages displayed in the webapp. + [Overview](overview.md) + [Tables](tables.md) + [Mutations](mutations.md) + [Edges](edges.md) + [Nodes](nodes.md) + [Trees](trees.md) +### Extras +Feedback and bug reports are welcome. This section contains information on contributing and engaging with the tskit community. + [Contributing](contributing.md) + [Changelog](CHANGELOG.md) + [Community](https://tskit.dev/community/) \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index 90de1b8..13433ff 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,5 +1,24 @@ (install)= # Installing tsbrowse +``` +python3 -m pip install tsbrowse +``` -TODO! Add information on install and deps, then link to intro +To install the development version: +``` +python3 -m pip install git+https://github.com/tskit-dev/tsbrowse +``` +Please also see the documentation on [Contributing](contributing.md). + +# Dependencies +|Package |Minimum supported version| +|-----|--------| +|Datashader|0.16.3| +|Panel|1.5.2| +|Tszip|| +|Tskit|| +|Daiquiri|| +|Hvplot|| + +For an introduction to tsbrowse, see [Introduction](intro.md) \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index 80d5e52..b4335e1 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,8 +1,31 @@ (sec_intro)= # Introduction to tsbrowse +Tsbrowse is an open-source Python web-app intended as a genome browser for ARGs. It provides interactive visual summaries of the fundamental components of an ARG, i.e. the mutations, nodes, edges and trees it encodes. Tsbrowse operates on ARGs encoded as succinct tree sequences (see [tskit](https://tskit.dev/tskit/docs/stable/introduction.html)). It can be used to inspect biobank-scale ARGs without requiring data uploads to a server. -# Data Model +## Data Model +The foundation of tsbrowse is the [tskit data model](https://tskit.dev/tskit/docs/stable/data-model.html), which is a generalised ARG representation. Tsbrowse can therefore be applied to ARGs inferred using widely-used methods including [tsinfer](https://tskit.dev/tsinfer/docs/stable/), [Relate](https://myersgroup.github.io/relate/), [ARG-Needle](https://palamaralab.github.io/software/argneedle/) and [SINGER](https://github.com/popgenmethods/SINGER). Tsbrowse augments the underlying tree sequence tables with additional columns to create a compressed `.tsbrowse` file, containing all necessary semantic metadata required for automatic visualisation with the [Holoviz](https://holoviz.org/) ecosystem. -# How to -TODO! Add a quick start guide with example tree sequences +## How to +Consider an example tree sequence simulated with msprime: +``` +def make_sweep_ts(n, Ne, L, rho=1e-8, mu=1e-8): + sweep_model = msprime.SweepGenicSelection( + position=L/2, start_frequency=0.0001, end_frequency=0.9999, s=0.25, dt=1e-6) + models = [sweep_model, msprime.StandardCoalescent()] + ts = msprime.sim_ancestry( + n, model=models, population_size=Ne, sequence_length=L, recombination_rate=rho, random_seed=1234) + return msprime.sim_mutations(ts, rate=mu, random_seed=4321) + +sim_ts = make_sweep_ts(300, Ne=10_000, L=5_000_000, mu=1e-8) +sim_ts.dump("example.trees") +``` +To run tsbrowse on this tree sequence, we first run the preprocessing step. +``` +python -m tsbrowse preprocess example.trees +``` +This creates a `.tsbrowse` file in the same directory as the input tree sequence. +We can then run the serve step to view the app in a web browser: +``` +python -m tsbrowse serve example.tsbrowse --port 8080 +``` \ No newline at end of file diff --git a/docs/trees.md b/docs/trees.md index d7862b3..c2031d2 100644 --- a/docs/trees.md +++ b/docs/trees.md @@ -2,4 +2,8 @@ # Trees page -![Trees Page](tsbrowse:example.tsbrowse:trees) \ No newline at end of file +![Trees Page](tsbrowse:example.tsbrowse:trees) +A tree sequence generally consists of multiple highly correlated genetic genealogies along the sequence, referred to as trees. This page summarises the individual trees in a tree sequence. The histograms show the distribution of various aspects of the trees, including the number of sites and mutations in each tree, the genomic span (i.e., the length of sequence the tree spans), the total branch length (i.e., the total sum of branch lengths over all samples in the tree, in time units), and the arity (i.e., the number of children nodes in the tree have). + +## Plot controls (sidebar): +* The `log y-axis` checkbox plots the number of trees on the log scale. \ No newline at end of file