diff --git a/README.md b/README.md index 619cc0e..0adb20f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # tsbrowse -Inspect large genetic genealogies (e.g. ARGs) stored in the [tskit](https://tskit.dev) "succinct tree sequence" format, -via a genome browser style app. _Tsbrowse_ can deal with ARGs of thousands or potentially millions of samples. +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. + 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), @@ -8,37 +9,40 @@ It is particularly useful to help evaluate ARGs that have been inferred using to [KwARG](https://github.com/a-ignatieva/kwarg), [Threads](https://pypi.org/project/threads-arg/), etc. -To view a tskit tree sequence or tszip file first pre-process it: +## Quickstart -`python -m tsbrowse preprocess /path/to/trees-file` +First install `tsbrowse` from PyPI: + +`python -m pip install tsbrowse` + +A tskit tree sequence must first be preprocessed to a `.tsbrowse` file: -This will write a `.tsbrowse` file +`python -m tsbrowse preprocess /path/to/trees-file` -To launch the app use: +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.` (where `genes.csv` is a semicolon-separated text file containing no header and information about one gene on a row in the order: `chr;start;end;strand;ensembl ID;gene name`) -To generate a PNG of a specific page use, e.g: +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). -`python -m tsbrowse screenshot /path/to/tsbrowse-file mutations` +## Tips -On WSL, it may be necessary to disable Numba's CUDA support: +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` -## Installation +A PNG of a specific page in tsbrowse can be generated using the `screenshot` command: -tsbrowse is currently in development. To install the latest dev version from github, try +`python -m tsbrowse screenshot /path/to/tsbrowse-file mutations` -``` -python -m pip install git+https://github.com/tskit-dev/tsbrowse -``` ## Development diff --git a/example/example.trees.tsz b/example/example.trees.tsz new file mode 100644 index 0000000..612dfa2 Binary files /dev/null and b/example/example.trees.tsz differ diff --git a/tsbrowse/__main__.py b/tsbrowse/__main__.py index d441dfb..0f1258e 100644 --- a/tsbrowse/__main__.py +++ b/tsbrowse/__main__.py @@ -113,7 +113,10 @@ def preprocess(tszip_path, output, verbose): preprocess_.preprocess(tszip_path, output, show_progress=True) logger.info(f"Preprocessing completed. Output saved to: {output}") - print(f"Preprocessing completed. You can now view with `tsbrowse serve {output}`") + print( + "Preprocessing completed. You can now view with " + f"`python -m tsbrowse serve {output}`" + ) @cli.command()