Skip to content

Commit 6d4955c

Browse files
aafshinfardlcoombe
andauthored
Improve readme (#180)
* Update README.md * v1.0.4 Co-authored-by: Lauren Coombe <lauren.e.coombe@gmail.com>
1 parent 78cee8c commit 6d4955c

6 files changed

Lines changed: 107 additions & 44 deletions

File tree

README.md

Lines changed: 99 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,77 @@
11
[![Published in DNA](https://img.shields.io/badge/Published%20in-DNA-blue.svg)](https://www.mdpi.com/2673-8856/2/2/9)
22
[![Release](https://img.shields.io/github/release/bcgsc/physlr.svg)](https://github.com/bcgsc/physlr/releases)
3+
[![Conda](https://img.shields.io/conda/dn/bioconda/physlr?label=Conda%20downloads)](https://anaconda.org/bioconda/physlr)
4+
[![Downloads](https://img.shields.io/github/downloads/bcgsc/physlr/total?logo=github)](https://github.com/bcgsc/physlr/releases/download/v1.0.4/physlr-1.0.4.tar.gz)
5+
6+
<p align="center">
7+
<img src="physlr-logo-transparent.png" width="600" title="Physlr stages">
8+
</p>
9+
10+
Physlr: Next-generation Physical Maps
11+
================================================================================
12+
13+
Physlr `physical-map` constructs a *de novo* physical map using linked reads from 10X Genomics or MGI stLFR. This physical map can then be used for various genomics analyses, including scaffolding. Physlr `scaffolds` uses the physical map generated in the first stage to scaffold an existing genome assembly to yield chromosome-level contiguity.
14+
15+
<p align="center">
16+
<img src="physlr-stages.png" width="250" title="Physlr stages">
17+
</p>
18+
19+
Contents
20+
================================================================================
21+
* [Installation](#installation)
22+
* [Install Physlr using Conda](#install-physlr-using-conda)
23+
* [Compile Physlr from source](#compile-physlr-from-source)
24+
* [Compiling](#compiling)
25+
* [Dependencies](#dependencies)
26+
* [Optional dependencies](#optional-dependencies)
27+
* [Running Physlr](#running-physlr)
28+
* [Generate a physical map](#generate-a-physical-map)
29+
* [Scaffold an assembly](#scaffold-an-assembly)
30+
* [Output files](#output-files)
31+
* [Citation](#citation)
32+
* [Support](#support)
33+
* [Acknowledgements](#acknowledgements)
34+
35+
36+
Installation
37+
================================================================================
38+
You can install Physlr either via Conda or by compiling from source. We recommend installing Physlr via [Conda](https://docs.conda.io/en/latest/) package manager (Linux, MacOS), which will handle compilation and dependencies automatically.
39+
40+
## Install Physlr using Conda
41+
In an active `conda` environment:
42+
```
43+
conda install -c bioconda physlr
44+
physlr help
45+
```
46+
Physlr can generate complmentary reports (included in the pipeline by default) - you can install dependencies for these optional features using conda:
47+
```
48+
conda install -c r r-rmarkdown
49+
conda install -c conda-forge r-ggplot2
50+
```
351

4-
![Logo](https://github.com/bcgsc/physlr/blob/logo/physlr-logo-wide.png)
52+
## Compile Physlr from source
53+
### Compiling
554

6-
# Physlr: Next-generation Physical Maps
55+
Compile Physlr using the following commands:
56+
```
57+
pip3 install --user git+https://github.com/bcgsc/physlr
58+
git clone https://github.com/bcgsc/physlr
59+
cd physlr/src && make install
60+
```
761

8-
Physlr constructs a *de novo* physical map using linked reads from 10X Genomics or MGI stLFR. This physical map can then be used to scaffold an existing assembly to yield chromosome-level contiguity.
62+
or, to install Physlr in a specified directory (like `/opt/physlr`):
963

10-
# Dependencies
64+
```
65+
pip3 install --user git+https://github.com/bcgsc/physlr
66+
git clone https://github.com/bcgsc/physlr
67+
cd physlr/src && make install PREFIX=/opt/physlr
68+
```
69+
after compiling, Physlr commands will be available through:
70+
```
71+
bin/physlr-make
72+
bin/physlr-make help
73+
```
74+
### Dependencies
1175

1276
* [ntCard](https://github.com/bcgsc/ntCard)
1377
* [ntHits](https://github.com/bcgsc/ntHits)
@@ -19,62 +83,50 @@ Physlr constructs a *de novo* physical map using linked reads from 10X Genomics
1983
* [scipy](https://www.scipy.org/)
2084
* [sklearn](https://scikit-learn.org/stable/)
2185
* [tqdm](https://tqdm.github.io/)
22-
23-
Additionally, we recommend using pypy3 over regular python3 for speed.
24-
25-
26-
## Optional dependencies
27-
28-
- [pigz](https://zlib.net/pigz/) for parallel gzip
29-
- [zsh](https://sourceforge.net/projects/zsh/) for reporting time and memory usage
30-
31-
32-
# Compiling Physlr from source
33-
86+
87+
Additionally, we recommend using `pypy3` over regular python3 for speed.
88+
pypy v3 or `pypy3` is the default python executable for Physlr. To switch to other executables set the `python_executable` argument:
3489
```
35-
pip3 install --user git+https://github.com/bcgsc/physlr
36-
git clone https://github.com/bcgsc/physlr
37-
cd physlr/src && make install
90+
physlr [OPTION]... python_executable=python3
3891
```
39-
40-
To install Physlr in a specified directory:
41-
92+
If you install our tool via `conda`, pypy3 is included as a dependency. Otherwise, you can install pypy3 using conda:
4293
```
43-
pip3 install --user git+https://github.com/bcgsc/physlr
44-
git clone https://github.com/bcgsc/physlr
45-
cd physlr/src && make install PREFIX=/opt/physlr
94+
conda install -c conda-forge pypy3.7 # for python3.7
4695
```
4796

48-
# Running Physlr
97+
### Optional dependencies
4998

50-
## Generating Physlr Physical Map with stLFR reads
99+
- [pigz](https://zlib.net/pigz/) for parallel gzip
100+
- [zsh](https://sourceforge.net/projects/zsh/) for reporting time and memory usage
51101

102+
Running Physlr
103+
================================================================================
104+
105+
## Generate a physical map
52106
To construct a physical map _de novo_, you need linked reads (from 10X Genomics or MGI stLFR).
53107

54108
In this example, the linked reads dataset is called `linkedreads.fq.gz`. The linked reads are from stLFR so we specify `protocol=stlfr` to use the default value for stLFR reads.
55109

56110
```
57111
cd experiment # Change to working directory
58-
bin/physlr-make physical-map lr=linkedreads protocol=stlfr # Constructs the physical map
112+
physlr physical-map lr=linkedreads protocol=stlfr # Constructs the physical map
59113
```
60114
You also have the option to provide a reference genome (with `ref`) for Physlr to evaluate the physical map. Assuming the reference is called `reference.fa`, you can run the following command for the previous example:
61115
```
62116
cd experiment
63-
bin/physlr-make physical-map lr=linkedreads ref=reference protocol=stlfr # Constructs the physical map and reference-based evaluations for it
117+
physlr physical-map lr=linkedreads ref=reference protocol=stlfr # Constructs the physical map and reference-based evaluations for it
64118
```
65119

66120
If you provide a reference genome, Physlr first constructs a physical map and then maps it to the input reference. In this case, Physlr automatically outputs a `*.map-quality.tsv` file reporting assembly-like quality metrics for the physical map. In addition, Physlr visualizes the correctness and contiguity of the physical map.
67121

68122
You can also independently run the physical map construction and evaluation steps:
69123
```
70124
cd experiment
71-
bin/physlr-make physical-map lr=linkedreads protocol=stlfr
72-
bin/physlr-make map-quality lr=linkedreads ref=reference
125+
physlr physical-map lr=linkedreads protocol=stlfr
126+
physlr map-quality lr=linkedreads ref=reference
73127
```
74128

75-
76-
## Scaffolding a draft assembly with Physlr Physical Map
77-
129+
## Scaffold an assembly
78130
To scaffold a draft assembly, you need linked reads from 10X Genomics or stLFR, and an existing assembly.
79131
In this example, the linked reads and draft assembly are called `linkedreads.fq.gz` and `draft.fa`, respectively. The linked reads are from 10X Genomics so we specify `protocol=10x` to use the default value for 10X Genomics reads.
80132

@@ -91,22 +143,32 @@ bin/physlr-make scaffolds lr=linkedreads ref=reference draft=draft protocol=10x
91143
See the help page for further information.
92144
`bin/physlr-make help`
93145

94-
# Output files
146+
## Output files
95147

96148
* `lr.physlr.physical-map.path`: Paths of barcodes (backbones).
97149
* `lr.physlr.physical-map.ref.n10.paf.gz.*.pdf`: Various graphs showing the contiguity and correctness of the backbones with respect to the reference.
98150
* `draft.physlr.fa`: Physlr scaffolded assembly using the physical map.
99151
* `draft.physlr.quast.tsv`: Quast metrics comparing the Physlr scaffolded assembly against the reference.
100152

101-
# Citing Physlr
153+
154+
Citation
155+
================================================================================
102156

103157
If you use Physlr in your research, please cite:
104158

105159
Afshinfard A, Jackman SD, Wong J, Coombe L, Chu J, Nikolic V, Dilek G, Malkoç Y, Warren RL, Birol I. Physlr: Next-Generation Physical Maps. DNA. 2022 Jun 10;2(2):116-30. doi: https://doi.org/10.3390/dna2020009
106160

107161
[![link](https://img.shields.io/badge/Physlr-manuscript-brightgreen)](https://doi.org/10.3390/dna2020009)
108162

109-
# Acknowledgements
163+
Support
164+
================================================================================
165+
166+
[Create a new issue on GitHub.](https://github.com/bcgsc/physlr/issues)
167+
168+
[![GitHub issues](https://img.shields.io/github/issues/bcgsc/physlr.svg)](https://gitHub.com/bcgsc/physlr/issues)
169+
170+
Acknowledgements
171+
================================================================================
110172

111173
This projects uses:
112174
* [btl_bloomfilter](https://github.com/bcgsc/btl_bloomfilter) BTL C/C++ Common bloom filters for bioinformatics projects implemented by Justin Chu

bin/physlr-make

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ endif
189189

190190
# Help
191191
help:
192-
@echo "Usage: ./physlr-make [COMMAND] [OPTION=VALUE]..."
192+
@echo "Usage: physlr [COMMAND] [OPTION=VALUE]..."
193193
@echo " Commands:"
194194
@echo ""
195195
@echo " physical-map run physlr and generate a physical map with linked reads (10X or stLFR)."
@@ -212,6 +212,7 @@ help:
212212
@echo " 2: progress bar."
213213
@echo " 3: verbose messages."
214214
@echo " m % of edges to remove in the overlap graph [90]. Available options are [0-100]."
215+
@echo " python_executable Path to the Python executable [pypy3]."
215216
@echo " protocol Available options are stlfr and 10x. Specify the protocol option to use the default m value for the respective linked read protocol."
216217
@echo " stlfr: m=85."
217218
@echo " 10x: m=92.5."
@@ -235,10 +236,10 @@ help:
235236
@echo " ./physlr-make physical-map lr=myreads m=86"
236237
@echo "Example: To scaffold a draft assembly using physlr with 10X reads myreads.fq.gz and draft.fa, run:"
237238
@echo " ./physlr-make scaffolds lr=myreads protocol=10x draft=draft"
238-
@echo "To ensure that the pipeline runs correctly, make sure that the following tools are in your PATH: ntCard, ntHits, and Quast."
239+
@echo "To ensure that the pipeline runs correctly, make sure that the following tools are in your PATH: ntCard (ntcard), ntHits (nthits), and QUAST (quast)."
239240

240241
version:
241-
@echo "physlr 1.0.2"
242+
@echo "physlr 1.0.4"
242243

243244
################################################################################
244245
# Test m=1 prune_branches=1 prune_bridges=1

data/profile-physlr.Rmd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ if (dim(df)[1] == 0) {
235235
labs(
236236
title = "Physlr - time Gantt chart",
237237
subtitle = paste("path:", ldir),
238-
caption = "physlr version: 1.0.2"
238+
caption = "physlr version: 1.0.4"
239239
) +
240240
theme(
241241
plot.title = element_text(color = "black", face = "bold"),
@@ -271,7 +271,7 @@ if (dim(df)[1] == 0) {
271271
labs(
272272
title = "Physlr - memory usage",
273273
subtitle = paste("path:", ldir),
274-
caption = "physlr version: 1.0.2"
274+
caption = "physlr version: 1.0.4"
275275
) +
276276
theme(
277277
plot.title = element_text(color = "black", face = "bold"),

physlr-stages.png

35.1 KB
Loading

physlr/physlr.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2800,7 +2800,7 @@ def parse_arguments():
28002800
"-V", "--verbose", action="store", dest="verbose", type=int, default="2",
28012801
help="the level of verbosity: 0:silent, 1:periodic, 2:progress, 3:verbose [2]")
28022802
argparser.add_argument(
2803-
"--version", action="version", version="physlr 1.0.2")
2803+
"--version", action="version", version="physlr 1.0.4")
28042804
argparser.add_argument(
28052805
"command",
28062806
help="A command")

setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
setuptools.setup(
77
name="physlr",
8-
version="1.0.2",
8+
version="1.0.4",
99
author="Amirhossein Afshinfard",
1010
author_email="aafshinfard@bcgsc.ca",
1111
description="Next-generation Physical Maps using Linked Reads",

0 commit comments

Comments
 (0)