Coverage for binette/diamond.py: 100%

66 statements  

« 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 

8 

9import pandas as pd 

10from checkm2 import keggData 

11 

12from binette.checkpoint import atomic_replace, partial_path 

13 

14logger = logging.getLogger(__name__) 

15 

16 

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 """ 

22 

23 def __init__(self, message: str, exit_code: int = 1): 

24 super().__init__(message) 

25 self.exit_code = exit_code 

26 

27 

28def get_checkm2_db() -> str: 

29 """ 

30 Get the path to the CheckM2 database. 

31 

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") 

37 

38 checkm2_database_raw = subprocess.run( 

39 ["checkm2", "database", "--current"], text=True, stderr=subprocess.PIPE 

40 ) 

41 

42 if checkm2_database_raw.returncode != 0: 

43 raise DiamondError( 

44 f"Something went wrong with checkm2:\n=======\n{checkm2_database_raw.stderr}========" 

45 ) 

46 

47 reg_result = re.search("INFO: (/.*.dmnd)", checkm2_database_raw.stderr) 

48 

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 ) 

53 

54 return reg_result.group(1) 

55 

56 

57def check_tool_exists(tool_name: str): 

58 """ 

59 Check if a specified tool is on the system's PATH. 

60 

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.") 

67 

68 

69def resolve_checkm2_db(checkm2_db: Path | None) -> Path: 

70 """ 

71 Return the path of the CheckM2 diamond database to use. 

72 

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 

81 

82 

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. 

87 

88 :param low_mem: Use low memory mode if True. 

89 """ 

90 return 0.5 if low_mem else 2 

91 

92 

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. 

107 

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") 

121 

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) 

126 

127 blocksize = get_block_size(low_mem) 

128 

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 ) 

141 

142 logger.info("Running diamond") 

143 logger.info(f"Command: {cmd}") 

144 

145 run = subprocess.run(cmd, shell=True) 

146 

147 if run.returncode != 0: 

148 raise DiamondError( 

149 f"An error occurred while running DIAMOND. Check log file '{log}'" 

150 ) 

151 

152 atomic_replace(tmp_output, final_output) 

153 logger.info("Finished running DIAMOND") 

154 

155 

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. 

159 

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 ) 

167 

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 ) 

174 

175 diamond_results_df[["Ref100_hit", "Kegg_annotation"]] = diamond_results_df[ 

176 "annotation" 

177 ].str.split("~", n=1, expand=True) 

178 

179 KeggCalc = keggData.KeggCalculator() 

180 defaultKOs = KeggCalc.return_default_values_from_category("KO_Genes") 

181 

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 ) 

188 

189 contig_to_kegg_counter = ( 

190 diamond_results_df.groupby("contig") 

191 .agg({"Kegg_annotation": Counter}) 

192 .reset_index() 

193 ) 

194 

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 ) 

202 

203 return contig_to_kegg_counter 

204 

205 

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. 

210 

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