rsomics-annotation 0.1.0

Typed GFF3 and GTF validation, selection, conversion, and sequence extraction
Documentation
use std::collections::{HashMap, hash_map::Entry};
use std::io::BufRead;

use noodles_gff::feature::record::Strand;
use rsomics_common::{Result, RsomicsError};

use crate::annotation::{AnnotationLine, Dialect, FeatureRecord, for_each_line, invalid_line};

pub(crate) fn validate<R: BufRead>(input: R, dialect: Dialect) -> Result<()> {
    let mut validator = Validator::new(dialect);
    for_each_line(input, dialect, |line_number, line| {
        validator.observe(line_number, &line)
    })?;
    validator.finish()
}

pub(crate) struct Validator {
    dialect: Dialect,
    gff_version_line: Option<usize>,
    ids: HashMap<Vec<u8>, Signature>,
    parents: Vec<(usize, Vec<u8>)>,
}

#[derive(Eq, PartialEq)]
struct Signature {
    seqid: Vec<u8>,
    ty: Vec<u8>,
    strand: Strand,
}

impl Validator {
    pub(crate) fn new(dialect: Dialect) -> Self {
        Self {
            dialect,
            gff_version_line: None,
            ids: HashMap::new(),
            parents: Vec::new(),
        }
    }

    pub(crate) fn observe(&mut self, line_number: usize, line: &AnnotationLine) -> Result<()> {
        if self.dialect == Dialect::Gff3
            && self.gff_version_line.is_none()
            && !matches!(
                line,
                AnnotationLine::Directive(directive)
                    if directive.key() == noodles_gff::directive_buf::key::GFF_VERSION
            )
        {
            return Err(invalid_line(
                line_number,
                "gff-version directive must be the first non-empty line",
            ));
        }

        match line {
            AnnotationLine::Directive(directive) => {
                if directive.key() == noodles_gff::directive_buf::key::GFF_VERSION {
                    if self.gff_version_line.replace(line_number).is_some() {
                        return Err(invalid_line(line_number, "duplicate gff-version directive"));
                    }
                    if !is_gff3_version(directive.value()) {
                        return Err(invalid_line(
                            line_number,
                            "gff-version directive must declare version 3",
                        ));
                    }
                }
                Ok(())
            }
            AnnotationLine::Comment(_) => Ok(()),
            AnnotationLine::Record(record) => self.observe_record(line_number, record),
        }
    }

    fn observe_record(&mut self, line_number: usize, record: &FeatureRecord) -> Result<()> {
        if record.seqid().is_empty() || record.seqid() == b"." {
            return Err(invalid_line(
                line_number,
                "feature requires a reference sequence name",
            ));
        }
        if record.ty().is_empty() || record.ty() == b"." {
            return Err(invalid_line(line_number, "feature requires a type"));
        }
        if record.score().is_some_and(|score| !score.is_finite()) {
            return Err(invalid_line(line_number, "feature score must be finite"));
        }

        let is_cds = record.ty().eq_ignore_ascii_case(b"CDS");
        let is_codon = record.ty().eq_ignore_ascii_case(b"start_codon")
            || record.ty().eq_ignore_ascii_case(b"stop_codon");
        if is_cds && record.phase().is_none() {
            return Err(invalid_line(line_number, "CDS feature is missing phase"));
        }
        let phase_is_valid = match self.dialect {
            Dialect::Gff3 => is_cds,
            Dialect::Gtf => is_cds || is_codon,
        };
        if !phase_is_valid && record.phase().is_some() {
            return Err(invalid_line(
                line_number,
                "phase is not valid for this feature type",
            ));
        }

        match self.dialect {
            Dialect::Gff3 => self.observe_gff3(line_number, record),
            Dialect::Gtf => self.observe_gtf(line_number, record),
        }
    }

    fn observe_gff3(&mut self, line_number: usize, record: &FeatureRecord) -> Result<()> {
        if let Some(values) = record.attribute_values(b"ID") {
            if values.len() != 1 || values[0].is_empty() {
                return Err(invalid_line(
                    line_number,
                    "ID must have exactly one non-empty value",
                ));
            }
            let id = values[0].to_vec();
            let signature = Signature {
                seqid: record.seqid().to_vec(),
                ty: record.ty().to_vec(),
                strand: record.strand(),
            };
            match self.ids.entry(id.clone()) {
                Entry::Vacant(entry) => {
                    entry.insert(signature);
                }
                Entry::Occupied(entry) if entry.get() != &signature => {
                    return Err(invalid_line(
                        line_number,
                        format!("ID {:?} is reused by incompatible features", display(&id)),
                    ));
                }
                Entry::Occupied(_) => {}
            }
        }

        if let Some(values) = record.attribute_values(b"Parent") {
            for parent in values {
                if parent.is_empty() {
                    return Err(invalid_line(line_number, "Parent value cannot be empty"));
                }
                self.parents.push((line_number, parent.to_vec()));
            }
        }
        Ok(())
    }

    fn observe_gtf(&self, line_number: usize, record: &FeatureRecord) -> Result<()> {
        if !has_nonempty_attribute(record, b"gene_id") {
            return Err(invalid_line(line_number, "GTF feature is missing gene_id"));
        }
        let ty = record.ty();
        if !ty.eq_ignore_ascii_case(b"gene") && !has_nonempty_attribute(record, b"transcript_id") {
            return Err(invalid_line(
                line_number,
                "GTF transcript feature is missing transcript_id",
            ));
        }
        Ok(())
    }

    pub(crate) fn finish(self) -> Result<()> {
        if self.dialect == Dialect::Gff3 && self.gff_version_line.is_none() {
            return Err(RsomicsError::InvalidInput(
                "GFF3 input is missing the ##gff-version directive".to_owned(),
            ));
        }
        for (line_number, parent) in self.parents {
            if !self.ids.contains_key(&parent) {
                return Err(invalid_line(
                    line_number,
                    format!("Parent {:?} does not resolve to an ID", display(&parent)),
                ));
            }
        }
        Ok(())
    }
}

fn has_nonempty_attribute(record: &FeatureRecord, key: &[u8]) -> bool {
    record
        .attribute_values(key)
        .is_some_and(|values| values.iter().any(|value| !value.is_empty()))
}

fn display(value: &[u8]) -> String {
    String::from_utf8_lossy(value).into_owned()
}

fn is_gff3_version(value: Option<&noodles_gff::directive_buf::Value>) -> bool {
    match value {
        Some(noodles_gff::directive_buf::Value::GffVersion(version)) => version.major() == 3,
        Some(noodles_gff::directive_buf::Value::String(version)) => {
            std::str::from_utf8(version.as_ref())
                .ok()
                .and_then(|value| {
                    value
                        .parse::<noodles_gff::directive_buf::value::GffVersion>()
                        .ok()
                })
                .is_some_and(|version| version.major() == 3)
        }
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn unresolved_parent_fails() {
        let input = b"##gff-version 3\nchr1\tsrc\texon\t1\t2\t.\t+\t.\tParent=t1\n";
        let error = validate(&input[..], Dialect::Gff3).unwrap_err();
        assert!(error.to_string().contains("does not resolve"), "{error}");
    }

    #[test]
    fn gff_version_must_precede_comments_and_records() {
        let input =
            b"# generated elsewhere\n##gff-version 3\nchr1\tsrc\tgene\t1\t2\t.\t+\t.\tID=g1\n";
        let error = validate(&input[..], Dialect::Gff3).unwrap_err();
        assert!(
            error.to_string().contains("first non-empty line"),
            "{error}"
        );
    }

    #[test]
    fn gtf_requires_transcript_id_for_exons() {
        let input = b"chr1\tsrc\texon\t1\t2\t.\t+\t.\tgene_id \"g1\";\n";
        let error = validate(&input[..], Dialect::Gtf).unwrap_err();
        assert!(error.to_string().contains("transcript_id"), "{error}");
    }

    #[test]
    fn phased_cds_is_valid() {
        let input =
            b"##gff-version 3\nchr1\tsrc\tmRNA\t1\t3\t.\t+\t.\tID=t1\nchr1\tsrc\tCDS\t1\t3\t.\t+\t0\tParent=t1\n";
        validate(&input[..], Dialect::Gff3).unwrap();
    }

    #[test]
    fn discontinuous_id_with_consistent_identity_is_valid() {
        let input = b"##gff-version 3\n\
            chr1\tsrc\tmatch\t1\t3\t.\t+\t.\tID=m1\n\
            chr1\tsrc\tmatch\t8\t10\t.\t+\t.\tID=m1\n";
        validate(&input[..], Dialect::Gff3).unwrap();
    }

    #[test]
    fn incompatible_duplicate_id_fails() {
        let input = b"##gff-version 3\n\
            chr1\tsrc\tgene\t1\t3\t.\t+\t.\tID=x\n\
            chr1\tsrc\tmRNA\t1\t3\t.\t+\t.\tID=x\n";
        let error = validate(&input[..], Dialect::Gff3).unwrap_err();
        assert!(error.to_string().contains("incompatible"), "{error}");
    }

    #[test]
    fn multiple_parents_resolve() {
        let input = b"##gff-version 3\n\
            chr1\tsrc\tmRNA\t1\t3\t.\t+\t.\tID=t1\n\
            chr1\tsrc\tmRNA\t1\t3\t.\t+\t.\tID=t2\n\
            chr1\tsrc\texon\t1\t3\t.\t+\t.\tParent=t1,t2\n";
        validate(&input[..], Dialect::Gff3).unwrap();
    }

    #[test]
    fn non_cds_phase_fails() {
        let input = b"##gff-version 3\nchr1\tsrc\texon\t1\t3\t.\t+\t0\tID=e1\n";
        let error = validate(&input[..], Dialect::Gff3).unwrap_err();
        assert!(error.to_string().contains("not valid"), "{error}");
    }

    #[test]
    fn gtf_stop_codon_frame_is_valid() {
        let input =
            b"chr1\tsrc\tstop_codon\t1\t3\t.\t+\t0\tgene_id \"g1\"; transcript_id \"t1\";\n";
        validate(&input[..], Dialect::Gtf).unwrap();
    }
}