Skip to main content

rsomics_count/
annotation.rs

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}