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 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.
@@ -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,4 @@
1
+ from __future__ import annotations
2
+
3
+ __all__ = ["__version__"]
4
+ __version__ = "0.1.0"
@@ -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
@@ -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")