rsomics-count 0.1.0

Genomic feature counting and count-matrix normalization
Documentation
use std::collections::{HashMap, HashSet};
use std::fs::File;
use std::io::{BufRead, BufReader};
use std::path::Path;

use bstr::ByteSlice;
use flate2::read::MultiGzDecoder;
use noodles_gff as gff;
use noodles_gtf as gtf;
use rsomics_common::{Context, Result, RsomicsError};

use crate::model::{CountLevel, FeatureSet, PartInput, Strand};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AnnotationFormat {
    Gtf,
    Gff3,
    Saf,
}

#[derive(Clone, Debug)]
pub struct AnnotationOptions {
    pub format: AnnotationFormat,
    pub feature_types: Vec<String>,
    pub group_by: String,
    pub level: CountLevel,
}

pub(crate) fn load(path: &Path, options: &AnnotationOptions) -> Result<FeatureSet> {
    if options.feature_types.is_empty() {
        return Err(RsomicsError::ConfigError(
            "at least one annotation feature type is required".to_owned(),
        ));
    }
    if options.group_by.is_empty() {
        return Err(RsomicsError::ConfigError(
            "the grouping attribute cannot be empty".to_owned(),
        ));
    }
    let selected: HashSet<&str> = options.feature_types.iter().map(String::as_str).collect();
    let parts = match options.format {
        AnnotationFormat::Gtf => load_gtf(path, &selected, &options.group_by),
        AnnotationFormat::Gff3 => load_gff3(path, &selected, &options.group_by),
        AnnotationFormat::Saf => load_saf(path, &selected),
    }?;
    FeatureSet::build(parts, options.level)
        .rs_with_context(|| format!("loading annotation {}", path.display()))
}

fn load_gtf(path: &Path, selected: &HashSet<&str>, group_by: &str) -> Result<Vec<PartInput>> {
    let mut reader = gtf::io::Reader::new(open_text(path)?);
    let mut parts = Vec::new();
    for (record_index, result) in reader.record_bufs().enumerate() {
        let record = result.map_err(|error| annotation_error(path, record_index + 1, error))?;
        push_record(
            path,
            record_index + 1,
            &record,
            selected,
            group_by,
            &mut parts,
        )?;
    }
    Ok(parts)
}

fn load_gff3(path: &Path, selected: &HashSet<&str>, group_by: &str) -> Result<Vec<PartInput>> {
    let mut reader = gff::io::Reader::new(open_text(path)?);
    let mut parts = Vec::new();
    for (record_index, result) in reader.record_bufs().enumerate() {
        let record = result.map_err(|error| annotation_error(path, record_index + 1, error))?;
        push_record(
            path,
            record_index + 1,
            &record,
            selected,
            group_by,
            &mut parts,
        )?;
    }
    Ok(parts)
}

fn push_record(
    path: &Path,
    record_index: usize,
    record: &gff::feature::RecordBuf,
    selected: &HashSet<&str>,
    group_by: &str,
    parts: &mut Vec<PartInput>,
) -> Result<()> {
    let ty = record.ty().to_str().map_err(|error| {
        annotation_error(
            path,
            record_index,
            format!("feature type is not UTF-8: {error}"),
        )
    })?;
    if !selected.contains(ty) {
        return Ok(());
    }
    let raw_id = record
        .attributes()
        .get(group_by.as_bytes())
        .ok_or_else(|| {
            annotation_error(
                path,
                record_index,
                format!("missing grouping attribute {group_by:?}"),
            )
        })?;
    let id = raw_id.as_string().ok_or_else(|| {
        annotation_error(
            path,
            record_index,
            format!("grouping attribute {group_by:?} has multiple values"),
        )
    })?;
    let id = id.to_str().map_err(|error| {
        annotation_error(
            path,
            record_index,
            format!("grouping attribute {group_by:?} is not UTF-8: {error}"),
        )
    })?;
    if id.is_empty() {
        return Err(annotation_error(
            path,
            record_index,
            format!("grouping attribute {group_by:?} is empty"),
        ));
    }
    let chrom = record.reference_sequence_name().to_str().map_err(|error| {
        annotation_error(
            path,
            record_index,
            format!("reference sequence name is not UTF-8: {error}"),
        )
    })?;
    let strand = match record.strand() {
        gff::feature::record::Strand::Forward => Strand::Forward,
        gff::feature::record::Strand::Reverse => Strand::Reverse,
        gff::feature::record::Strand::None => Strand::Unknown,
        other => {
            return Err(annotation_error(
                path,
                record_index,
                format!("unsupported feature strand {other:?}"),
            ));
        }
    };
    parts.push(PartInput {
        id: id.to_owned(),
        chrom: chrom.to_owned(),
        start: usize::from(record.start()) as u64 - 1,
        end: usize::from(record.end()) as u64,
        strand,
    });
    Ok(())
}

fn load_saf(path: &Path, selected: &HashSet<&str>) -> Result<Vec<PartInput>> {
    if selected.len() != 1 || !selected.contains("exon") {
        return Err(RsomicsError::ConfigError(
            "--feature-type is not applicable to SAF annotations".to_owned(),
        ));
    }
    let reader = open_text(path)?;
    let mut lines = reader.lines().enumerate();
    let (header_line, header) = loop {
        let Some((index, result)) = lines.next() else {
            return Err(RsomicsError::InvalidInput(format!(
                "{}: empty SAF annotation",
                path.display()
            )));
        };
        let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
        if !line.trim().is_empty() && !line.starts_with('#') {
            break (index + 1, line);
        }
    };
    if header.split('\t').collect::<Vec<_>>() != ["GeneID", "Chr", "Start", "End", "Strand"] {
        return Err(annotation_error(
            path,
            header_line,
            "expected SAF header GeneID, Chr, Start, End, Strand",
        ));
    }

    let mut parts = Vec::new();
    for (index, result) in lines {
        let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
        if line.trim().is_empty() || line.starts_with('#') {
            continue;
        }
        let line_number = index + 1;
        let fields: Vec<&str> = line.split('\t').collect();
        if fields.len() != 5 {
            return Err(annotation_error(
                path,
                line_number,
                format!("expected 5 SAF columns, found {}", fields.len()),
            ));
        }
        if fields[0].is_empty() || fields[1].is_empty() {
            return Err(annotation_error(
                path,
                line_number,
                "SAF GeneID and Chr must be nonempty",
            ));
        }
        let start: u64 = fields[2].parse().map_err(|_| {
            annotation_error(
                path,
                line_number,
                format!("invalid SAF start {:?}", fields[2]),
            )
        })?;
        let end: u64 = fields[3].parse().map_err(|_| {
            annotation_error(
                path,
                line_number,
                format!("invalid SAF end {:?}", fields[3]),
            )
        })?;
        if start == 0 || start > end {
            return Err(annotation_error(
                path,
                line_number,
                format!("invalid one-based SAF interval {start}..={end}"),
            ));
        }
        parts.push(PartInput {
            id: fields[0].to_owned(),
            chrom: fields[1].to_owned(),
            start: start - 1,
            end,
            strand: Strand::parse(fields[4])?,
        });
    }
    Ok(parts)
}

pub(crate) fn load_aliases(path: Option<&Path>) -> Result<HashMap<String, String>> {
    let Some(path) = path else {
        return Ok(HashMap::new());
    };
    let reader = open_text(path)?;
    let mut aliases = HashMap::new();
    for (index, result) in reader.lines().enumerate() {
        let line = result.rs_with_context(|| format!("reading {}", path.display()))?;
        if line.trim().is_empty() || line.starts_with('#') {
            continue;
        }
        let fields: Vec<_> = line.split(',').map(str::trim).collect();
        if fields.len() != 2 || fields.iter().any(|field| field.is_empty()) {
            return Err(annotation_error(
                path,
                index + 1,
                "expected annotation,input chromosome alias pair",
            ));
        }
        match aliases.insert(fields[1].to_owned(), fields[0].to_owned()) {
            Some(previous) if previous != fields[0] => {
                return Err(annotation_error(
                    path,
                    index + 1,
                    format!("input chromosome {:?} has conflicting aliases", fields[1]),
                ));
            }
            _ => {}
        }
    }
    Ok(aliases)
}

fn open_text(path: &Path) -> Result<Box<dyn BufRead>> {
    let file =
        File::open(path).rs_with_context(|| format!("opening annotation {}", path.display()))?;
    let mut buffered = BufReader::new(file);
    let gzip = buffered
        .fill_buf()
        .rs_with_context(|| format!("reading annotation {}", path.display()))?
        .starts_with(&[0x1f, 0x8b]);
    if gzip {
        Ok(Box::new(BufReader::new(MultiGzDecoder::new(buffered))))
    } else {
        Ok(Box::new(buffered))
    }
}

fn annotation_error(path: &Path, record: usize, error: impl std::fmt::Display) -> RsomicsError {
    RsomicsError::InvalidInput(format!("{} record {record}: {error}", path.display()))
}

#[cfg(test)]
mod tests {
    use std::io::Write;

    use super::*;

    fn options(format: AnnotationFormat) -> AnnotationOptions {
        AnnotationOptions {
            format,
            feature_types: vec!["exon".to_owned()],
            group_by: "gene_id".to_owned(),
            level: CountLevel::MetaFeature,
        }
    }

    #[test]
    fn strict_saf_builds_union_lengths() {
        let mut file = tempfile::NamedTempFile::new().unwrap();
        writeln!(file, "GeneID\tChr\tStart\tEnd\tStrand").unwrap();
        writeln!(file, "g\tchr1\t101\t150\t+").unwrap();
        writeln!(file, "g\tchr1\t141\t200\t+").unwrap();
        let features = load(file.path(), &options(AnnotationFormat::Saf)).unwrap();
        assert_eq!(features.rows()[0].length(), 100);
    }

    #[test]
    fn malformed_saf_fails() {
        let mut file = tempfile::NamedTempFile::new().unwrap();
        writeln!(file, "GeneID\tChr\tStart\tEnd\tStrand").unwrap();
        writeln!(file, "g\tchr1\t0\t10\t+").unwrap();
        assert!(load(file.path(), &options(AnnotationFormat::Saf)).is_err());
    }

    #[test]
    fn aliases_map_input_names_to_annotation_names() {
        let mut file = tempfile::NamedTempFile::new().unwrap();
        writeln!(file, "chr1,1").unwrap();
        assert_eq!(load_aliases(Some(file.path())).unwrap()["1"], "chr1");
    }

    #[test]
    fn selected_records_require_the_grouping_attribute() {
        let mut file = tempfile::NamedTempFile::new().unwrap();
        writeln!(
            file,
            "chr1\ttest\texon\t101\t120\t.\t+\t.\ttranscript_id \"t\";"
        )
        .unwrap();
        assert!(load(file.path(), &options(AnnotationFormat::Gtf)).is_err());
    }

    #[test]
    fn multiple_feature_types_share_the_declared_group() {
        let mut file = tempfile::NamedTempFile::new().unwrap();
        writeln!(file, "chr1\ttest\texon\t101\t120\t.\t+\t.\tgene_id \"g\";").unwrap();
        writeln!(file, "chr1\ttest\tCDS\t121\t140\t.\t+\t0\tgene_id \"g\";").unwrap();
        let features = load(
            file.path(),
            &AnnotationOptions {
                feature_types: vec!["exon".to_owned(), "CDS".to_owned()],
                ..options(AnnotationFormat::Gtf)
            },
        )
        .unwrap();
        assert_eq!(features.rows().len(), 1);
        assert_eq!(features.rows()[0].length(), 40);
    }
}