1use std::collections::{HashMap, HashSet};
2use std::fs::File;
3use std::io::{BufRead, BufReader};
4use std::path::Path;
5
6use bstr::ByteSlice;
7use flate2::read::MultiGzDecoder;
8use noodles_gff as gff;
9use noodles_gtf as gtf;
10use rsomics_common::{Context, Result, RsomicsError};
11
12use crate::model::{CountLevel, FeatureSet, PartInput, Strand};
13
14#[derive(Clone, Copy, Debug, Eq, PartialEq)]
15pub enum AnnotationFormat {
16 Gtf,
17 Gff3,
18 Saf,
19}
20
21#[derive(Clone, Debug)]
22pub struct AnnotationOptions {
23 pub format: AnnotationFormat,
24 pub feature_types: Vec<String>,
25 pub group_by: String,
26 pub level: CountLevel,
27}
28
29pub(crate) fn load(path: &Path, options: &AnnotationOptions) -> Result<FeatureSet> {
30 if options.feature_types.is_empty() {
31 return Err(RsomicsError::ConfigError(
32 "at least one annotation feature type is required".to_owned(),
33 ));
34 }
35 if options.group_by.is_empty() {
36 return Err(RsomicsError::ConfigError(
37 "the grouping attribute cannot be empty".to_owned(),
38 ));
39 }
40 let selected: HashSet<&str> = options.feature_types.iter().map(String::as_str).collect();
41 let parts = match options.format {
42 AnnotationFormat::Gtf => load_gtf(path, &selected, &options.group_by),
43 AnnotationFormat::Gff3 => load_gff3(path, &selected, &options.group_by),
44 AnnotationFormat::Saf => load_saf(path, &selected),
45 }?;
46 FeatureSet::build(parts, options.level)
47 .rs_with_context(|| format!("loading annotation {}", path.display()))
48}
49
50fn load_gtf(path: &Path, selected: &HashSet<&str>, group_by: &str) -> Result<Vec<PartInput>> {
51 let mut reader = gtf::io::Reader::new(open_text(path)?);
52 let mut parts = Vec::new();
53 for (record_index, result) in reader.record_bufs().enumerate() {
54 let record = result.map_err(|error| annotation_error(path, record_index + 1, error))?;
55 push_record(
56 path,
57 record_index + 1,
58 &record,
59 selected,
60 group_by,
61 &mut parts,
62 )?;
63 }
64 Ok(parts)
65}
66
67fn load_gff3(path: &Path, selected: &HashSet<&str>, group_by: &str) -> Result<Vec<PartInput>> {
68 let mut reader = gff::io::Reader::new(open_text(path)?);
69 let mut parts = Vec::new();
70 for (record_index, result) in reader.record_bufs().enumerate() {
71 let record = result.map_err(|error| annotation_error(path, record_index + 1, error))?;
72 push_record(
73 path,
74 record_index + 1,
75 &record,
76 selected,
77 group_by,
78 &mut parts,
79 )?;
80 }
81 Ok(parts)
82}
83
84fn push_record(
85 path: &Path,
86 record_index: usize,
87 record: &gff::feature::RecordBuf,
88 selected: &HashSet<&str>,
89 group_by: &str,
90 parts: &mut Vec<PartInput>,
91) -> Result<()> {
92 let ty = record.ty().to_str().map_err(|error| {
93 annotation_error(
94 path,
95 record_index,
96 format!("feature type is not UTF-8: {error}"),
97 )
98 })?;
99 if !selected.contains(ty) {
100 return Ok(());
101 }
102 let raw_id = record
103 .attributes()
104 .get(group_by.as_bytes())
105 .ok_or_else(|| {
106 annotation_error(
107 path,
108 record_index,
109 format!("missing grouping attribute {group_by:?}"),
110 )
111 })?;
112 let id = raw_id.as_string().ok_or_else(|| {
113 annotation_error(
114 path,
115 record_index,
116 format!("grouping attribute {group_by:?} has multiple values"),
117 )
118 })?;
119 let id = id.to_str().map_err(|error| {
120 annotation_error(
121 path,
122 record_index,
123 format!("grouping attribute {group_by:?} is not UTF-8: {error}"),
124 )
125 })?;
126 if id.is_empty() {
127 return Err(annotation_error(
128 path,
129 record_index,
130 format!("grouping attribute {group_by:?} is empty"),
131 ));
132 }
133 let chrom = record.reference_sequence_name().to_str().map_err(|error| {
134 annotation_error(
135 path,
136 record_index,
137 format!("reference sequence name is not UTF-8: {error}"),
138 )
139 })?;
140 let strand = match record.strand() {
141 gff::feature::record::Strand::Forward => Strand::Forward,
142 gff::feature::record::Strand::Reverse => Strand::Reverse,
143 gff::feature::record::Strand::None => Strand::Unknown,
144 other => {
145 return Err(annotation_error(
146 path,
147 record_index,
148 format!("unsupported feature strand {other:?}"),
149 ));
150 }
151 };
152 parts.push(PartInput {
153 id: id.to_owned(),
154 chrom: chrom.to_owned(),
155 start: usize::from(record.start()) as u64 - 1,
156 end: usize::from(record.end()) as u64,
157 strand,
158 });
159 Ok(())
160}
161
162fn load_saf(path: &Path, selected: &HashSet<&str>) -> Result<Vec<PartInput>> {
163 if selected.len() != 1 || !selected.contains("exon") {
164 return Err(RsomicsError::ConfigError(
165 "--feature-type is not applicable to SAF annotations".to_owned(),
166 ));
167 }
168 let reader = open_text(path)?;
169 let mut lines = reader.lines().enumerate();
170 let (header_line, header) = loop {
171 let Some((index, result)) = lines.next() else {
172 return Err(RsomicsError::InvalidInput(format!(
173 "{}: empty SAF annotation",
174 path.display()
175 )));
176 };
177 let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
178 if !line.trim().is_empty() && !line.starts_with('#') {
179 break (index + 1, line);
180 }
181 };
182 if header.split('\t').collect::<Vec<_>>() != ["GeneID", "Chr", "Start", "End", "Strand"] {
183 return Err(annotation_error(
184 path,
185 header_line,
186 "expected SAF header GeneID, Chr, Start, End, Strand",
187 ));
188 }
189
190 let mut parts = Vec::new();
191 for (index, result) in lines {
192 let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
193 if line.trim().is_empty() || line.starts_with('#') {
194 continue;
195 }
196 let line_number = index + 1;
197 let fields: Vec<&str> = line.split('\t').collect();
198 if fields.len() != 5 {
199 return Err(annotation_error(
200 path,
201 line_number,
202 format!("expected 5 SAF columns, found {}", fields.len()),
203 ));
204 }
205 if fields[0].is_empty() || fields[1].is_empty() {
206 return Err(annotation_error(
207 path,
208 line_number,
209 "SAF GeneID and Chr must be nonempty",
210 ));
211 }
212 let start: u64 = fields[2].parse().map_err(|_| {
213 annotation_error(
214 path,
215 line_number,
216 format!("invalid SAF start {:?}", fields[2]),
217 )
218 })?;
219 let end: u64 = fields[3].parse().map_err(|_| {
220 annotation_error(
221 path,
222 line_number,
223 format!("invalid SAF end {:?}", fields[3]),
224 )
225 })?;
226 if start == 0 || start > end {
227 return Err(annotation_error(
228 path,
229 line_number,
230 format!("invalid one-based SAF interval {start}..={end}"),
231 ));
232 }
233 parts.push(PartInput {
234 id: fields[0].to_owned(),
235 chrom: fields[1].to_owned(),
236 start: start - 1,
237 end,
238 strand: Strand::parse(fields[4])?,
239 });
240 }
241 Ok(parts)
242}
243
244pub(crate) fn load_aliases(path: Option<&Path>) -> Result<HashMap<String, String>> {
245 let Some(path) = path else {
246 return Ok(HashMap::new());
247 };
248 let reader = open_text(path)?;
249 let mut aliases = HashMap::new();
250 for (index, result) in reader.lines().enumerate() {
251 let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
252 if line.trim().is_empty() || line.starts_with('#') {
253 continue;
254 }
255 let fields: Vec<_> = line.split(',').map(str::trim).collect();
256 if fields.len() != 2 || fields.iter().any(|field| field.is_empty()) {
257 return Err(annotation_error(
258 path,
259 index + 1,
260 "expected annotation,input chromosome alias pair",
261 ));
262 }
263 match aliases.insert(fields[1].to_owned(), fields[0].to_owned()) {
264 Some(previous) if previous != fields[0] => {
265 return Err(annotation_error(
266 path,
267 index + 1,
268 format!("input chromosome {:?} has conflicting aliases", fields[1]),
269 ));
270 }
271 _ => {}
272 }
273 }
274 Ok(aliases)
275}
276
277fn open_text(path: &Path) -> Result<Box<dyn BufRead>> {
278 let file =
279 File::open(path).rs_with_context(|| format!("opening annotation {}", path.display()))?;
280 let mut buffered = BufReader::new(file);
281 let gzip = buffered
282 .fill_buf()
283 .rs_with_context(|| format!("reading annotation {}", path.display()))?
284 .starts_with(&[0x1f, 0x8b]);
285 if gzip {
286 Ok(Box::new(BufReader::new(MultiGzDecoder::new(buffered))))
287 } else {
288 Ok(Box::new(buffered))
289 }
290}
291
292fn annotation_error(path: &Path, record: usize, error: impl std::fmt::Display) -> RsomicsError {
293 RsomicsError::InvalidInput(format!("{} record {record}: {error}", path.display()))
294}
295
296#[cfg(test)]
297mod tests {
298 use std::io::Write;
299
300 use super::*;
301
302 fn options(format: AnnotationFormat) -> AnnotationOptions {
303 AnnotationOptions {
304 format,
305 feature_types: vec!["exon".to_owned()],
306 group_by: "gene_id".to_owned(),
307 level: CountLevel::MetaFeature,
308 }
309 }
310
311 #[test]
312 fn strict_saf_builds_union_lengths() {
313 let mut file = tempfile::NamedTempFile::new().unwrap();
314 writeln!(file, "GeneID\tChr\tStart\tEnd\tStrand").unwrap();
315 writeln!(file, "g\tchr1\t101\t150\t+").unwrap();
316 writeln!(file, "g\tchr1\t141\t200\t+").unwrap();
317 let features = load(file.path(), &options(AnnotationFormat::Saf)).unwrap();
318 assert_eq!(features.rows()[0].length(), 100);
319 }
320
321 #[test]
322 fn malformed_saf_fails() {
323 let mut file = tempfile::NamedTempFile::new().unwrap();
324 writeln!(file, "GeneID\tChr\tStart\tEnd\tStrand").unwrap();
325 writeln!(file, "g\tchr1\t0\t10\t+").unwrap();
326 assert!(load(file.path(), &options(AnnotationFormat::Saf)).is_err());
327 }
328
329 #[test]
330 fn aliases_map_input_names_to_annotation_names() {
331 let mut file = tempfile::NamedTempFile::new().unwrap();
332 writeln!(file, "chr1,1").unwrap();
333 assert_eq!(load_aliases(Some(file.path())).unwrap()["1"], "chr1");
334 }
335
336 #[test]
337 fn selected_records_require_the_grouping_attribute() {
338 let mut file = tempfile::NamedTempFile::new().unwrap();
339 writeln!(
340 file,
341 "chr1\ttest\texon\t101\t120\t.\t+\t.\ttranscript_id \"t\";"
342 )
343 .unwrap();
344 assert!(load(file.path(), &options(AnnotationFormat::Gtf)).is_err());
345 }
346
347 #[test]
348 fn multiple_feature_types_share_the_declared_group() {
349 let mut file = tempfile::NamedTempFile::new().unwrap();
350 writeln!(file, "chr1\ttest\texon\t101\t120\t.\t+\t.\tgene_id \"g\";").unwrap();
351 writeln!(file, "chr1\ttest\tCDS\t121\t140\t.\t+\t0\tgene_id \"g\";").unwrap();
352 let features = load(
353 file.path(),
354 &AnnotationOptions {
355 feature_types: vec!["exon".to_owned(), "CDS".to_owned()],
356 ..options(AnnotationFormat::Gtf)
357 },
358 )
359 .unwrap();
360 assert_eq!(features.rows().len(), 1);
361 assert_eq!(features.rows()[0].length(), 40);
362 }
363}