phu 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of phu might be problematic. Click here for more details.
- phu-0.1.0/PKG-INFO +46 -0
- phu-0.1.0/README.md +35 -0
- phu-0.1.0/pyproject.toml +28 -0
- phu-0.1.0/src/phu/__init__.py +4 -0
- phu-0.1.0/src/phu/_exec.py +38 -0
- phu-0.1.0/src/phu/cli.py +67 -0
- phu-0.1.0/src/phu/seqclust.py +233 -0
phu-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: phu
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Phage bioinformatics utilities (seqclust runner and friends).
|
|
5
|
+
Author: Camilo García-Botero
|
|
6
|
+
Author-email: Camilo García-Botero <ca.garcia2@uniandes.edu.co>
|
|
7
|
+
License: MIT
|
|
8
|
+
Requires-Dist: typer>=0.17.3
|
|
9
|
+
Requires-Python: >=3.13
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# phu
|
|
13
|
+
|
|
14
|
+
phu (phage utilities) or phutilities, is a modular toolkit for viral genomics workflows. It provides command-line tools to handle common steps in phage bioinformatics pipelines—wrapping complex utilities behind a consistent and intuitive interface.
|
|
15
|
+
|
|
16
|
+
The first implemented module, seqclust, brings flexible clustering strategies for viral contigs and genomes, with additional modules under active development.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
> [!WARNING]
|
|
21
|
+
`phu` is currently in the process of being published on Bioconda. The package may not be immediately available. Please check back soon or follow this repository for updates.
|
|
22
|
+
|
|
23
|
+
phu will be available through Bioconda. To install (once available), use the following command:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
mamba create -n phu bioconda::phu
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
phu <command> [options]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Commands
|
|
36
|
+
|
|
37
|
+
- `seqclust`: Cluster viral sequences into operational taxonomic units (OTUs).
|
|
38
|
+
|
|
39
|
+
## Contributing
|
|
40
|
+
|
|
41
|
+
We welcome contributions to phu! Please follow these steps:
|
|
42
|
+
|
|
43
|
+
1. Fork the repository.
|
|
44
|
+
2. Create a new branch for your feature or bugfix.
|
|
45
|
+
3. Make your changes and commit them.
|
|
46
|
+
4. Submit a pull request describing your changes.
|
phu-0.1.0/README.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# phu
|
|
2
|
+
|
|
3
|
+
phu (phage utilities) or phutilities, is a modular toolkit for viral genomics workflows. It provides command-line tools to handle common steps in phage bioinformatics pipelines—wrapping complex utilities behind a consistent and intuitive interface.
|
|
4
|
+
|
|
5
|
+
The first implemented module, seqclust, brings flexible clustering strategies for viral contigs and genomes, with additional modules under active development.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
> [!WARNING]
|
|
10
|
+
`phu` is currently in the process of being published on Bioconda. The package may not be immediately available. Please check back soon or follow this repository for updates.
|
|
11
|
+
|
|
12
|
+
phu will be available through Bioconda. To install (once available), use the following command:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
mamba create -n phu bioconda::phu
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
phu <command> [options]
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Commands
|
|
25
|
+
|
|
26
|
+
- `seqclust`: Cluster viral sequences into operational taxonomic units (OTUs).
|
|
27
|
+
|
|
28
|
+
## Contributing
|
|
29
|
+
|
|
30
|
+
We welcome contributions to phu! Please follow these steps:
|
|
31
|
+
|
|
32
|
+
1. Fork the repository.
|
|
33
|
+
2. Create a new branch for your feature or bugfix.
|
|
34
|
+
3. Make your changes and commit them.
|
|
35
|
+
4. Submit a pull request describing your changes.
|
phu-0.1.0/pyproject.toml
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "phu"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Phage bioinformatics utilities (seqclust runner and friends)."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = { text = "MIT" }
|
|
7
|
+
authors = [
|
|
8
|
+
{ name = "Camilo García-Botero", email = "ca.garcia2@uniandes.edu.co" }
|
|
9
|
+
]
|
|
10
|
+
requires-python = ">=3.13"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"typer>=0.17.3",
|
|
13
|
+
]
|
|
14
|
+
|
|
15
|
+
[project.scripts]
|
|
16
|
+
phu = "phu.cli:main"
|
|
17
|
+
|
|
18
|
+
[build-system]
|
|
19
|
+
requires = ["uv_build>=0.8.13,<0.9.0"]
|
|
20
|
+
build-backend = "uv_build"
|
|
21
|
+
|
|
22
|
+
[dependency-groups]
|
|
23
|
+
dev = [
|
|
24
|
+
"pytest>=8.4.1"
|
|
25
|
+
]
|
|
26
|
+
lint = [
|
|
27
|
+
"ruff>=0.12.11",
|
|
28
|
+
]
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
import subprocess
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from shutil import which
|
|
5
|
+
from typing import Sequence
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class CmdNotFound(RuntimeError):
|
|
9
|
+
pass
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _executable(candidates: Sequence[str]) -> str:
|
|
13
|
+
"""
|
|
14
|
+
Find an executable in the PATH.
|
|
15
|
+
"""
|
|
16
|
+
for name in candidates:
|
|
17
|
+
path = which(name)
|
|
18
|
+
if path:
|
|
19
|
+
return path
|
|
20
|
+
raise CmdNotFound(f"None of the executables found in PATH: {', '.join(candidates)}")
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def run(
|
|
24
|
+
argv: Sequence[str],
|
|
25
|
+
cwd: str | Path | None = None,
|
|
26
|
+
check: bool = True,
|
|
27
|
+
) -> subprocess.CompletedProcess[str]:
|
|
28
|
+
"""
|
|
29
|
+
Run a command in a subprocess.
|
|
30
|
+
"""
|
|
31
|
+
proc = subprocess.run(
|
|
32
|
+
list(map(str, argv)),
|
|
33
|
+
cwd=str(cwd) if cwd else None,
|
|
34
|
+
text=True,
|
|
35
|
+
capture_output=False, # stream to console
|
|
36
|
+
check=check,
|
|
37
|
+
)
|
|
38
|
+
return proc
|
phu-0.1.0/src/phu/cli.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
# import sys
|
|
4
|
+
import typer
|
|
5
|
+
|
|
6
|
+
from phu import __version__
|
|
7
|
+
from .seqclust import SeqClustConfig, Mode, _seqclust
|
|
8
|
+
from ._exec import CmdNotFound
|
|
9
|
+
|
|
10
|
+
app = typer.Typer(
|
|
11
|
+
help="Phage utilities CLI",
|
|
12
|
+
rich_markup_mode="rich",
|
|
13
|
+
context_settings={"help_option_names": ["-h", "--help"]},
|
|
14
|
+
add_completion=False,
|
|
15
|
+
no_args_is_help=True
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
@app.callback(invoke_without_command=True)
|
|
19
|
+
def _root(ctx: typer.Context) -> None:
|
|
20
|
+
# any global init here (env checks, logging setup, etc.)
|
|
21
|
+
if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
|
|
22
|
+
typer.echo(ctx.get_help())
|
|
23
|
+
raise typer.Exit(0) # exit code 0 when no subcommand is given
|
|
24
|
+
|
|
25
|
+
@app.command("seqclust")
|
|
26
|
+
def seqclust(
|
|
27
|
+
mode: Mode = typer.Option(
|
|
28
|
+
..., "--mode", help="dereplication | votu-clustering | spp-clustering"
|
|
29
|
+
),
|
|
30
|
+
input_contigs: Path = typer.Option(
|
|
31
|
+
..., "--input-contigs", exists=True, readable=True, help="Input FASTA"
|
|
32
|
+
),
|
|
33
|
+
output_folder: Path = typer.Option(
|
|
34
|
+
Path("clustered-contigs"), "--output-folder", help="Output directory"
|
|
35
|
+
),
|
|
36
|
+
threads: int = typer.Option(
|
|
37
|
+
0, "--threads", min=0, help="0=all cores; otherwise N threads"
|
|
38
|
+
),
|
|
39
|
+
):
|
|
40
|
+
"""
|
|
41
|
+
Sequence clustering wrapper around external 'vclust' with three modes.
|
|
42
|
+
"""
|
|
43
|
+
cfg = SeqClustConfig(
|
|
44
|
+
mode=mode,
|
|
45
|
+
input_contigs=input_contigs,
|
|
46
|
+
output_folder=output_folder,
|
|
47
|
+
threads=threads,
|
|
48
|
+
)
|
|
49
|
+
try:
|
|
50
|
+
_seqclust(cfg) # the runner command
|
|
51
|
+
except FileNotFoundError as e:
|
|
52
|
+
typer.echo(str(e), fg=typer.colors.RED, err=True)
|
|
53
|
+
raise typer.Exit(1)
|
|
54
|
+
except CmdNotFound as e:
|
|
55
|
+
typer.secho(str(e), fg=typer.colors.RED, err=True)
|
|
56
|
+
typer.echo(
|
|
57
|
+
"Required executables on PATH: 'vclust' (or 'vclust.py') and 'seqkit'"
|
|
58
|
+
)
|
|
59
|
+
raise typer.Exit(1)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
# @app.callback(invoke_without_command=True)
|
|
63
|
+
def main() -> None:
|
|
64
|
+
app()
|
|
65
|
+
|
|
66
|
+
if __name__ == "__main__":
|
|
67
|
+
main()
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from enum import Enum
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Optional
|
|
6
|
+
|
|
7
|
+
from ._exec import run, _executable, CmdNotFound
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class Mode(str, Enum):
|
|
11
|
+
dereplication = "dereplication"
|
|
12
|
+
votu = "votu-clustering"
|
|
13
|
+
spp = "spp-clustering"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass
|
|
17
|
+
class SeqClustConfig:
|
|
18
|
+
mode: Mode
|
|
19
|
+
input_contigs: Path
|
|
20
|
+
output_folder: Path = Path("clustered-contigs")
|
|
21
|
+
threads: int = 0 # 0 => all cores
|
|
22
|
+
# defaults reflecting original bash behavior
|
|
23
|
+
ani_cutoff: float = 0.95
|
|
24
|
+
qcov_cutoff: float = 0.85
|
|
25
|
+
metric: str = "ani" # 'tani' for spp
|
|
26
|
+
algorithm: Optional[str] = None # set by mode
|
|
27
|
+
|
|
28
|
+
def plan(self) -> "SeqClustPlan":
|
|
29
|
+
algorithm = self.algorithm
|
|
30
|
+
metric = self.metric
|
|
31
|
+
ani_cutoff = self.ani_cutoff
|
|
32
|
+
qcov_cutoff: Optional[float] = self.qcov_cutoff
|
|
33
|
+
output_name = "clusters.tsv"
|
|
34
|
+
|
|
35
|
+
if self.mode == Mode.dereplication:
|
|
36
|
+
algorithm = "cd-hit"
|
|
37
|
+
elif self.mode == Mode.votu:
|
|
38
|
+
algorithm = "leiden"
|
|
39
|
+
elif self.mode == Mode.spp:
|
|
40
|
+
algorithm = "complete"
|
|
41
|
+
metric = "tani"
|
|
42
|
+
ani_cutoff = 0.95
|
|
43
|
+
qcov_cutoff = None
|
|
44
|
+
output_name = "species.tsv"
|
|
45
|
+
|
|
46
|
+
out = self.output_folder
|
|
47
|
+
return SeqClustPlan(
|
|
48
|
+
vclust_bin="",
|
|
49
|
+
seqkit_bin="",
|
|
50
|
+
input_contigs=self.input_contigs,
|
|
51
|
+
out_dir=out,
|
|
52
|
+
fltr=out / "fltr.txt",
|
|
53
|
+
ani=out / "ani.tsv",
|
|
54
|
+
ids=out / "ani.ids.tsv",
|
|
55
|
+
output=out / output_name,
|
|
56
|
+
representatives_ids=out / "cluster_representatives_ids.txt",
|
|
57
|
+
representatives_fna=out
|
|
58
|
+
/ (
|
|
59
|
+
"dereplicated_representatives.fna"
|
|
60
|
+
if self.mode == Mode.dereplication
|
|
61
|
+
else "representatives.fna"
|
|
62
|
+
),
|
|
63
|
+
algorithm=algorithm or "",
|
|
64
|
+
metric=metric,
|
|
65
|
+
ani_cutoff=ani_cutoff,
|
|
66
|
+
qcov_cutoff=qcov_cutoff,
|
|
67
|
+
threads=self.threads,
|
|
68
|
+
mode=self.mode,
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class SeqClustPlan:
|
|
74
|
+
vclust_bin: str
|
|
75
|
+
seqkit_bin: str
|
|
76
|
+
input_contigs: Path
|
|
77
|
+
out_dir: Path
|
|
78
|
+
fltr: Path
|
|
79
|
+
ani: Path
|
|
80
|
+
ids: Path
|
|
81
|
+
output: Path
|
|
82
|
+
representatives_ids: Path
|
|
83
|
+
representatives_fna: Path
|
|
84
|
+
algorithm: str
|
|
85
|
+
metric: str
|
|
86
|
+
ani_cutoff: float
|
|
87
|
+
qcov_cutoff: Optional[float]
|
|
88
|
+
threads: int
|
|
89
|
+
mode: Mode
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _threads(n: int) -> int:
|
|
93
|
+
import os
|
|
94
|
+
|
|
95
|
+
return max(1, n or (os.cpu_count() or 1))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _binaries() -> tuple[str, str]:
|
|
99
|
+
"""
|
|
100
|
+
Discover required binaries for sequencing clustering.
|
|
101
|
+
"""
|
|
102
|
+
vclust = _executable(["vclust", "vclust.py"])
|
|
103
|
+
seqkit = _executable(["seqkit"])
|
|
104
|
+
return vclust, seqkit
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _seqclust(cfg: SeqClustConfig) -> SeqClustPlan:
|
|
108
|
+
"""
|
|
109
|
+
Run sequence clustering with vclust.
|
|
110
|
+
"""
|
|
111
|
+
if not cfg.input_contigs.exists():
|
|
112
|
+
raise FileNotFoundError(f"Input file not found: {cfg.input_contigs}")
|
|
113
|
+
|
|
114
|
+
vclust_bin, seqkit_bin = _binaries()
|
|
115
|
+
plan = cfg.plan()
|
|
116
|
+
plan.vclust_bin = vclust_bin
|
|
117
|
+
plan.seqkit_bin = seqkit_bin
|
|
118
|
+
|
|
119
|
+
plan.out_dir.mkdir(parents=True, exist_ok=True)
|
|
120
|
+
|
|
121
|
+
# Step 1: prefilter
|
|
122
|
+
min_ident = 0.7 if plan.mode == Mode.spp else 0.95
|
|
123
|
+
print(f"Step 1: Creating pre-alignment filter (min-ident={min_ident})…")
|
|
124
|
+
run(
|
|
125
|
+
[
|
|
126
|
+
plan.vclust_bin,
|
|
127
|
+
"prefilter",
|
|
128
|
+
"-i",
|
|
129
|
+
plan.input_contigs,
|
|
130
|
+
"-o",
|
|
131
|
+
plan.fltr,
|
|
132
|
+
"--min-ident",
|
|
133
|
+
f"{min_ident}",
|
|
134
|
+
"--threads",
|
|
135
|
+
str(_threads(plan.threads)),
|
|
136
|
+
]
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
# Step 2: align
|
|
140
|
+
print("Step 2: Calculating ANI…")
|
|
141
|
+
run(
|
|
142
|
+
[
|
|
143
|
+
plan.vclust_bin,
|
|
144
|
+
"align",
|
|
145
|
+
"-i",
|
|
146
|
+
plan.input_contigs,
|
|
147
|
+
"-o",
|
|
148
|
+
plan.ani,
|
|
149
|
+
"--filter",
|
|
150
|
+
plan.fltr,
|
|
151
|
+
"--out-ani",
|
|
152
|
+
f"{cfg.ani_cutoff}",
|
|
153
|
+
"--out-qcov",
|
|
154
|
+
f"{cfg.qcov_cutoff}",
|
|
155
|
+
"--threads",
|
|
156
|
+
str(_threads(plan.threads)),
|
|
157
|
+
]
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
# Step 3: cluster
|
|
161
|
+
print(f"Step 3: Clustering with {plan.algorithm} (metric={plan.metric})…")
|
|
162
|
+
clustercmd = [
|
|
163
|
+
plan.vclust_bin,
|
|
164
|
+
"cluster",
|
|
165
|
+
"-i",
|
|
166
|
+
plan.ani,
|
|
167
|
+
"-o",
|
|
168
|
+
plan.output,
|
|
169
|
+
"--ids",
|
|
170
|
+
plan.ids,
|
|
171
|
+
"--algorithm",
|
|
172
|
+
plan.algorithm,
|
|
173
|
+
"--metric",
|
|
174
|
+
plan.metric,
|
|
175
|
+
"--out-repr",
|
|
176
|
+
]
|
|
177
|
+
clustercmd += ["--" + plan.metric, f"{plan.ani_cutoff}"]
|
|
178
|
+
if plan.qcov_cutoff is not None:
|
|
179
|
+
clustercmd += ["--qcov", f"{plan.qcov_cutoff}"]
|
|
180
|
+
run(clustercmd)
|
|
181
|
+
|
|
182
|
+
# Summary
|
|
183
|
+
print("Clustering complete. Summary:")
|
|
184
|
+
ngenomes, nclusters = _summarize_tsv(plan.output)
|
|
185
|
+
print(f"Total clusters: {nclusters} from {ngenomes} genomes.")
|
|
186
|
+
|
|
187
|
+
# Representatives
|
|
188
|
+
print("Extracting cluster representative IDs…")
|
|
189
|
+
_extract_cluster_ids(plan.output, plan.representatives_ids)
|
|
190
|
+
|
|
191
|
+
print("Extracting representative sequences with seqkit…")
|
|
192
|
+
run(
|
|
193
|
+
[
|
|
194
|
+
plan.seqkit_bin,
|
|
195
|
+
"grep",
|
|
196
|
+
"-f",
|
|
197
|
+
plan.representatives_ids,
|
|
198
|
+
str(plan.input_contigs),
|
|
199
|
+
"-o",
|
|
200
|
+
str(plan.representatives_fna),
|
|
201
|
+
]
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
return plan
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def _summarize_tsv(tsv: Path) -> tuple[int, int]:
|
|
208
|
+
seen_genomes: set[str] = set()
|
|
209
|
+
seen_clusters: set[str] = set()
|
|
210
|
+
with tsv.open() as fh:
|
|
211
|
+
first = True
|
|
212
|
+
for line in fh:
|
|
213
|
+
if first:
|
|
214
|
+
first = False
|
|
215
|
+
continue
|
|
216
|
+
parts = line.rstrip("\n").split("\t")
|
|
217
|
+
if len(parts) < 2:
|
|
218
|
+
continue
|
|
219
|
+
seen_genomes.add(parts[0])
|
|
220
|
+
seen_clusters.add(parts[1])
|
|
221
|
+
return len(seen_genomes), len(seen_clusters)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
def _extract_cluster_ids(tsv: Path, out_ids: Path) -> None:
|
|
225
|
+
with tsv.open() as fh, out_ids.open("w") as out:
|
|
226
|
+
first = True
|
|
227
|
+
for line in fh:
|
|
228
|
+
if first:
|
|
229
|
+
first = False
|
|
230
|
+
continue
|
|
231
|
+
parts = line.rstrip("\n").split("\t")
|
|
232
|
+
if len(parts) >= 2:
|
|
233
|
+
out.write(parts[1] + "\n")
|