Coverage for binette/diamond.py: 100%
66 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 13:33 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 13:33 +0000
1import inspect
2import logging
3import re
4import shutil
5import subprocess
6from collections import Counter
7from pathlib import Path
9import pandas as pd
10from checkm2 import keggData
12from binette.checkpoint import atomic_replace, partial_path
14logger = logging.getLogger(__name__)
17class DiamondError(Exception):
18 """
19 Error when locating the CheckM2 DIAMOND database, running DIAMOND or reading
20 its results. `exit_code` is the exit status Binette ends with.
21 """
23 def __init__(self, message: str, exit_code: int = 1):
24 super().__init__(message)
25 self.exit_code = exit_code
28def get_checkm2_db() -> str:
29 """
30 Get the path to the CheckM2 database.
32 :return: The path to the CheckM2 database.
33 :raises DiamondError: If checkm2 is missing or does not return a database path.
34 """
35 if shutil.which("checkm2") is None:
36 raise DiamondError("Make sure checkm2 is on your system path")
38 checkm2_database_raw = subprocess.run(
39 ["checkm2", "database", "--current"], text=True, stderr=subprocess.PIPE
40 )
42 if checkm2_database_raw.returncode != 0:
43 raise DiamondError(
44 f"Something went wrong with checkm2:\n=======\n{checkm2_database_raw.stderr}========"
45 )
47 reg_result = re.search("INFO: (/.*.dmnd)", checkm2_database_raw.stderr)
49 if reg_result is None:
50 raise DiamondError(
51 f"Something went wrong when retrieving checkm2 db path:\n{checkm2_database_raw.stderr}"
52 )
54 return reg_result.group(1)
57def check_tool_exists(tool_name: str):
58 """
59 Check if a specified tool is on the system's PATH.
61 :param tool_name: The name of the tool to check for.
62 :type tool_name: str
63 :raises DiamondError: If the tool is not found on the system's PATH.
64 """
65 if shutil.which(tool_name) is None:
66 raise DiamondError(f"The '{tool_name}' tool is not found on your system PATH.")
69def resolve_checkm2_db(checkm2_db: Path | None) -> Path:
70 """
71 Return the path of the CheckM2 diamond database to use.
73 :param checkm2_db: Database given by the user, or None to use the one set via `checkm2 database`.
74 :raises FileNotFoundError: If the given database does not exist.
75 """
76 if checkm2_db is None:
77 return Path(get_checkm2_db())
78 if not checkm2_db.exists():
79 raise FileNotFoundError(checkm2_db)
80 return checkm2_db
83def get_block_size(low_mem: bool) -> float:
84 """
85 DIAMOND block size used by Binette. It changes memory usage and can also
86 slightly change alignment results.
88 :param low_mem: Use low memory mode if True.
89 """
90 return 0.5 if low_mem else 2
93def run(
94 faa_file: str,
95 output: str,
96 db: str,
97 log: str,
98 threads: int = 1,
99 query_cover: int = 80,
100 subject_cover: int = 80,
101 percent_id: int = 30,
102 evalue: float = 1e-05,
103 low_mem: bool = False,
104):
105 """
106 Run Diamond with specified parameters.
108 :param faa_file: Path to the input protein sequence file (FASTA format).
109 :param output: Path to the Diamond output file.
110 :param db: Path to the Diamond database.
111 :param log: Path to the log file.
112 :param threads: Number of CPU threads to use (default is 1).
113 :param query_cover: Minimum query coverage percentage (default is 80).
114 :param subject_cover: Minimum subject coverage percentage (default is 80).
115 :param percent_id: Minimum percent identity (default is 30).
116 :param evalue: Maximum e-value threshold (default is 1e-05).
117 :param low_mem: Use low memory mode if True (default is False).
118 :raises DiamondError: If DIAMOND fails.
119 """
120 check_tool_exists("diamond")
122 # DIAMOND writes to a temporary file which is moved to its final location
123 # only on success, so an interrupted job never leaves a truncated result file.
124 final_output = Path(output)
125 tmp_output = partial_path(final_output)
127 blocksize = get_block_size(low_mem)
129 cmd = (
130 "diamond blastp --outfmt 6 --max-target-seqs 1 "
131 f"--query {faa_file} "
132 f"-o {tmp_output} "
133 f"--threads {threads} "
134 f"--db {db} "
135 f"--compress 1 "
136 f"--query-cover {query_cover} "
137 f"--subject-cover {subject_cover} "
138 f"--id {percent_id} "
139 f"--evalue {evalue} --block-size {blocksize} 2> {log}"
140 )
142 logger.info("Running diamond")
143 logger.info(f"Command: {cmd}")
145 run = subprocess.run(cmd, shell=True)
147 if run.returncode != 0:
148 raise DiamondError(
149 f"An error occurred while running DIAMOND. Check log file '{log}'"
150 )
152 atomic_replace(tmp_output, final_output)
153 logger.info("Finished running DIAMOND")
156def get_contig_to_kegg_id(diamond_result_file: str) -> dict:
157 """
158 Get a dictionary mapping contig IDs to KEGG annotations from a Diamond result file.
160 :param diamond_result_file: Path to the Diamond result file.
161 :return: A dictionary mapping contig IDs to KEGG annotations.
162 :raises DiamondError: If the result file is empty (exit code 3).
163 """
164 diamond_results_df = pd.read_csv(
165 diamond_result_file, sep="\t", usecols=[0, 1], names=["ProteinID", "annotation"]
166 )
168 if diamond_results_df.empty:
169 raise DiamondError(
170 f"DIAMOND result file '{diamond_result_file}' is empty. "
171 "This can happen with low-quality assemblies where DIAMOND produces no hits.",
172 exit_code=3,
173 )
175 diamond_results_df[["Ref100_hit", "Kegg_annotation"]] = diamond_results_df[
176 "annotation"
177 ].str.split("~", n=1, expand=True)
179 KeggCalc = keggData.KeggCalculator()
180 defaultKOs = KeggCalc.return_default_values_from_category("KO_Genes")
182 diamond_results_df = diamond_results_df.loc[
183 diamond_results_df["Kegg_annotation"].isin(defaultKOs.keys())
184 ]
185 diamond_results_df["contig"] = (
186 diamond_results_df["ProteinID"].str.split("_", n=-1).str[:-1].str.join("_")
187 )
189 contig_to_kegg_counter = (
190 diamond_results_df.groupby("contig")
191 .agg({"Kegg_annotation": Counter})
192 .reset_index()
193 )
195 contig_to_kegg_counter = dict(
196 zip(
197 contig_to_kegg_counter["contig"],
198 contig_to_kegg_counter["Kegg_annotation"],
199 strict=False,
200 )
201 )
203 return contig_to_kegg_counter
206def result_parameters(low_mem: bool) -> dict:
207 """
208 DIAMOND parameters that can change its results. Threads do not, but the block
209 size set by --low_mem does.
211 :param low_mem: Whether DIAMOND low memory mode is used.
212 """
213 params = inspect.signature(run).parameters
214 result_params = {
215 name: params[name].default
216 for name in ("query_cover", "subject_cover", "percent_id", "evalue")
217 }
218 result_params["block_size"] = get_block_size(low_mem)
219 return result_params