Coverage for binette/cds.py: 100%

103 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 13:33 +0000

1import concurrent.futures as cf 

2import gzip 

3import logging 

4import multiprocessing.pool 

5from collections import Counter, defaultdict 

6from collections.abc import Iterator 

7from pathlib import Path 

8from typing import Any 

9 

10import numpy as np 

11import pyfastx 

12import pyrodigal 

13 

14from binette.checkpoint import atomic_replace, partial_path 

15 

16logger = logging.getLogger(__name__) 

17 

18 

19def get_contig_from_cds_name(cds_name: str) -> str: 

20 """ 

21 Extract the contig name from a CDS name. 

22 

23 :param cds_name: The name of the CDS. 

24 :type cds_name: str 

25 :return: The name of the contig. 

26 :rtype: str 

27 """ 

28 return "_".join(cds_name.split("_")[:-1]) 

29 

30 

31def predict( 

32 contigs_iterator: Iterator, outfaa: str, threads: int = 1 

33) -> tuple[dict[str, list[str]], dict[str, int | None]]: 

34 """ 

35 Predict open reading frames with Pyrodigal. 

36 

37 :param contigs_iterator: An iterator of contig sequences. 

38 :param outfaa: The output file path for predicted protein sequences (in FASTA format). 

39 :param threads: Number of CPU threads to use (default is 1). 

40 

41 :return: A dictionary mapping contig names to predicted genes and a dictionary mapping contig names to coding lengths. 

42 """ 

43 

44 orf_finder = pyrodigal.GeneFinder(meta="meta") 

45 

46 logger.info(f"Predicting CDS sequences with Pyrodigal using {threads} threads") 

47 

48 with multiprocessing.pool.ThreadPool(processes=threads) as pool: 

49 contig_and_genes = pool.starmap( 

50 predict_genes, 

51 ((orf_finder.find_genes, name, seq) for name, seq in contigs_iterator), 

52 ) 

53 

54 write_faa(outfaa, contig_and_genes) 

55 

56 contig_to_genes = { 

57 contig_id: [gene.translate() for gene in pyrodigal_genes] 

58 for contig_id, pyrodigal_genes in contig_and_genes 

59 } 

60 

61 contig_to_coding_length = { 

62 contig_id: get_contig_coding_len(pyrodigal_genes, len(pyrodigal_genes.sequence)) 

63 for contig_id, pyrodigal_genes in contig_and_genes 

64 } 

65 

66 return contig_to_genes, contig_to_coding_length 

67 

68 

69def get_contig_coding_len( 

70 genes: list[pyrodigal.Gene], contig_length: int 

71) -> int | None: 

72 """ 

73 Compute the coding length of a contig. Use a mask to account for overlapping genes. 

74 

75 :param genes: A list of gene annotations for the contig. 

76 :param contig_length: The length of the contig in base pairs. 

77 :return: The coding length as a float, or None if contig_length is zero. 

78 """ 

79 if contig_length == 0: 

80 return None 

81 conding_base_mask = np.zeros(contig_length) 

82 for g in genes: 

83 conding_base_mask[g.begin - 1 : g.end] = 1 

84 return np.sum(conding_base_mask) 

85 

86 

87def predict_genes(find_genes, name, seq) -> tuple[str, pyrodigal.Genes]: 

88 return (name, find_genes(seq)) 

89 

90 

91def write_faa(outfaa: str, contig_to_genes: list[tuple[str, pyrodigal.Genes]]) -> None: 

92 """ 

93 Write predicted protein sequences to a FASTA file. 

94 

95 :param outfaa: The output file path for predicted protein sequences (in FASTA format). 

96 :param contig_to_genes: A dictionary mapping contig names to predicted genes. 

97 

98 """ 

99 logger.info("Writing predicted protein sequences") 

100 tmp_faa = partial_path(Path(outfaa)) 

101 with gzip.open(tmp_faa, "wt") as fl: 

102 for contig_id, genes in contig_to_genes: 

103 genes.write_translations(fl, contig_id) 

104 atomic_replace(tmp_faa, Path(outfaa)) 

105 

106 

107def is_nucleic_acid(sequence: str) -> bool: 

108 """ 

109 Determines whether the given sequence is a DNA or RNA sequence. 

110 

111 :param sequence: The sequence to check. 

112 :return: True if the sequence is a DNA or RNA sequence, False otherwise. 

113 """ 

114 # Define nucleotidic bases (DNA and RNA) 

115 nucleotidic_bases = set("ATCGNUatcgnu") 

116 

117 # Check if all characters in the sequence are valid nucleotidic bases (DNA or RNA) 

118 if all(base in nucleotidic_bases for base in sequence): 

119 return True 

120 

121 # If any character is invalid, return False 

122 return False 

123 

124 

125def parse_faa_file(faa_file: str) -> dict[str, list[str]]: 

126 """ 

127 Parse a FASTA file containing protein sequences and organize them by contig. 

128 

129 :param faa_file: Path to the input FASTA file. 

130 :return: A dictionary mapping contig names to lists of protein sequences. 

131 :raises ValueError: If the file contains nucleotidic sequences instead of protein sequences. 

132 """ 

133 contig_to_genes = defaultdict(list) 

134 checked_sequences = [] 

135 

136 # Iterate through the FASTA file and parse sequences 

137 for name, seq in pyfastx.Fastx(faa_file): 

138 contig = get_contig_from_cds_name(name) 

139 contig_to_genes[contig].append(seq) 

140 

141 # Concatenate up to the first 20 sequences for validation 

142 if len(checked_sequences) < 20: 

143 checked_sequences.append(seq) 

144 

145 # Concatenate all checked sequences for a more reliable nucleic acid check 

146 concatenated_seq = "".join(checked_sequences) 

147 

148 # Check if the concatenated sequence appears to be nucleic acid 

149 if is_nucleic_acid(concatenated_seq): 

150 raise ValueError( 

151 f"The file '{faa_file}' appears to contain nucleotide sequences. " 

152 "Ensure that the file contains valid protein sequences in FASTA format." 

153 ) 

154 

155 return dict(contig_to_genes) 

156 

157 

158def get_aa_composition(genes: list[str]) -> Counter: 

159 """ 

160 Calculate the amino acid composition of a list of protein sequences. 

161 

162 :param genes: A list of protein sequences. 

163 :return: A Counter object representing the amino acid composition. 

164 """ 

165 aa_counter = Counter() 

166 for gene in genes: 

167 aa_counter += Counter(gene) 

168 # remove * from Counter 

169 aa_counter.pop("*", None) 

170 return aa_counter 

171 

172 

173def get_contig_cds_metadata_flat( 

174 contig_to_genes: dict[str, list[str]], 

175) -> tuple[dict[str, int], dict[str, Counter], dict[str, int]]: 

176 """ 

177 Calculate metadata for contigs, including CDS count, amino acid composition, and total amino acid length. 

178 

179 :param contig_to_genes: A dictionary mapping contig names to lists of protein sequences. 

180 :return: A tuple containing dictionaries for CDS count, amino acid composition, and total amino acid length. 

181 """ 

182 contig_to_cds_count = { 

183 contig: len(genes) for contig, genes in contig_to_genes.items() 

184 } 

185 

186 contig_to_aa_counter = { 

187 contig: get_aa_composition(genes) for contig, genes in contig_to_genes.items() 

188 } 

189 logger.info("Calculating amino acid composition") 

190 

191 contig_to_aa_length = { 

192 contig: sum(counter.values()) 

193 for contig, counter in contig_to_aa_counter.items() 

194 } 

195 logger.info("Calculating total amino acid length") 

196 

197 return contig_to_cds_count, contig_to_aa_counter, contig_to_aa_length 

198 

199 

200def get_contig_cds_metadata( 

201 contig_to_genes: dict[int, Any | list[Any]], threads: int 

202) -> dict[str, dict]: 

203 """ 

204 Calculate metadata for contigs in parallel, including CDS count, amino acid composition, and total amino acid length. 

205 

206 :param contig_to_genes: A dictionary mapping contig names to lists of protein sequences. 

207 :param threads: Number of CPU threads to use. 

208 :return: A tuple containing dictionaries for CDS count, amino acid composition, and total amino acid length. 

209 """ 

210 contig_to_cds_count = { 

211 contig: len(genes) for contig, genes in contig_to_genes.items() 

212 } 

213 

214 contig_to_future = {} 

215 logger.info(f"Collecting contig amino acid composition using {threads} threads") 

216 with cf.ProcessPoolExecutor(max_workers=threads) as tpe: 

217 for contig, genes in contig_to_genes.items(): 

218 contig_to_future[contig] = tpe.submit(get_aa_composition, genes) 

219 

220 contig_to_aa_counter = { 

221 contig: future.result() for contig, future in contig_to_future.items() 

222 } 

223 logger.info("Calculating amino acid composition in parallel") 

224 

225 contig_to_aa_length = { 

226 contig: sum(counter.values()) 

227 for contig, counter in contig_to_aa_counter.items() 

228 } 

229 logger.info("Calculating total amino acid length in parallel") 

230 

231 contig_info = { 

232 "contig_to_cds_count": contig_to_cds_count, 

233 "contig_to_aa_counter": contig_to_aa_counter, 

234 "contig_to_aa_length": contig_to_aa_length, 

235 } 

236 

237 return contig_info 

238 

239 

240def filter_faa_file( 

241 contigs_to_keep: set[str], 

242 input_faa_file: Path, 

243 filtered_faa_file: Path, 

244): 

245 """ 

246 Filters a FASTA file containing protein sequences to only include sequences 

247 from contigs present in the provided set of contigs (`contigs_to_keep`). 

248 

249 This function processes the input FASTA file, identifies protein sequences 

250 originating from contigs listed in `contigs_to_keep`, and writes the filtered 

251 sequences to a new FASTA file. The output file supports optional `.gz` compression. 

252 

253 :param contigs_to_keep: A set of contig names to retain in the output FASTA file. 

254 :param input_faa_file: Path to the input FASTA file containing protein sequences. 

255 :param filtered_faa_file: Path to the output FASTA file for filtered sequences. 

256 If the filename ends with `.gz`, the output will be compressed. 

257 """ 

258 # Determine whether the output file should be compressed 

259 proper_open = gzip.open if str(filtered_faa_file).endswith(".gz") else open 

260 

261 # Initialize tracking sets for metrics 

262 contigs_with_genes = set() 

263 contigs_parsed = set() 

264 

265 # Process the input FASTA file and filter sequences based on contigs_to_keep 

266 tmp_faa_file = partial_path(Path(filtered_faa_file)) 

267 with proper_open(tmp_faa_file, "wt") as fl: 

268 for name, seq in pyfastx.Fastx(str(input_faa_file)): 

269 contig = get_contig_from_cds_name(name) 

270 contigs_parsed.add(contig) 

271 if contig in contigs_to_keep: 

272 contigs_with_genes.add(contig) 

273 fl.write(f">{name}\n{seq}\n") 

274 atomic_replace(tmp_faa_file, Path(filtered_faa_file)) 

275 

276 # Calculate metrics 

277 total_contigs = len(contigs_to_keep) 

278 contigs_with_no_genes = total_contigs - len(contigs_with_genes) 

279 contigs_not_in_keep_list = len(contigs_parsed - set(contigs_to_keep)) 

280 

281 # Log the computed metrics 

282 logger.info(f"Processing protein sequences from '{input_faa_file}'") 

283 logger.info( 

284 f"Filtered '{input_faa_file}' to retain genes from {total_contigs} contigs that are included in the input bins" 

285 ) 

286 logger.debug( 

287 f"Found {contigs_with_no_genes}/{total_contigs} contigs ({contigs_with_no_genes / total_contigs:.2%}) with no genes" 

288 ) 

289 logger.debug( 

290 f"{contigs_not_in_keep_list} contigs from the input FASTA file are not in the keep list" 

291 )