rsomics-annotation 0.1.0

Typed GFF3 and GTF validation, selection, conversion, and sequence extraction
Documentation
use std::io::{BufRead, Cursor, Write};

use clap::ValueEnum;
use noodles_gff as gff;
use noodles_gff::feature::record::{Phase, Strand};
use noodles_gtf as gtf;
use rsomics_common::{Context, Result, RsomicsError};
use rsomics_intervals::Interval;

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub(crate) enum Dialect {
    Gff3,
    Gtf,
}

pub(crate) enum AnnotationLine {
    Directive(gff::DirectiveBuf),
    Comment(Vec<u8>),
    Record(FeatureRecord),
}

pub(crate) struct FeatureRecord {
    inner: gff::feature::RecordBuf,
}

impl FeatureRecord {
    pub(crate) fn seqid(&self) -> &[u8] {
        self.inner.reference_sequence_name().as_ref()
    }

    pub(crate) fn ty(&self) -> &[u8] {
        self.inner.ty().as_ref()
    }

    pub(crate) fn start(&self) -> u64 {
        usize::from(self.inner.start()) as u64
    }

    pub(crate) fn end(&self) -> u64 {
        usize::from(self.inner.end()) as u64
    }

    pub(crate) fn strand(&self) -> Strand {
        self.inner.strand()
    }

    pub(crate) fn score(&self) -> Option<f32> {
        self.inner.score()
    }

    pub(crate) fn phase(&self) -> Option<Phase> {
        self.inner.phase()
    }

    pub(crate) fn attribute_values(&self, key: &[u8]) -> Option<Vec<&[u8]>> {
        self.inner
            .attributes()
            .get(key)
            .map(|value| value.iter().map(|item| item.as_ref()).collect())
    }

    pub(crate) fn interval(&self) -> Result<Interval> {
        let seqid = std::str::from_utf8(self.seqid()).map_err(|error| {
            RsomicsError::InvalidInput(format!(
                "reference sequence name is not UTF-8 and cannot be represented as BED: {error}"
            ))
        })?;
        Interval::new(seqid.to_owned(), self.start() - 1, self.end())
            .map_err(|error| RsomicsError::InvalidInput(error.to_string()))
    }

    pub(crate) fn bed_name(&self) -> &[u8] {
        self.attribute_values(b"ID")
            .and_then(|values| values.first().copied())
            .or_else(|| {
                self.attribute_values(b"Name")
                    .and_then(|values| values.first().copied())
            })
            .unwrap_or_else(|| self.ty())
    }
}

pub(crate) fn for_each_line<R, F>(mut input: R, dialect: Dialect, mut visit: F) -> Result<()>
where
    R: BufRead,
    F: FnMut(usize, AnnotationLine) -> Result<()>,
{
    let mut buffer = Vec::with_capacity(512);
    let mut line_number = 0;

    loop {
        buffer.clear();
        if input
            .read_until(b'\n', &mut buffer)
            .map_err(RsomicsError::Io)?
            == 0
        {
            break;
        }
        line_number += 1;
        while matches!(buffer.last(), Some(b'\n' | b'\r')) {
            buffer.pop();
        }
        if buffer.is_empty() {
            continue;
        }

        let line = match dialect {
            Dialect::Gff3 => parse_gff_line(&buffer, line_number)?,
            Dialect::Gtf => parse_gtf_line(&buffer, line_number)?,
        };
        visit(line_number, line)?;
    }

    Ok(())
}

fn parse_gff_line(bytes: &[u8], line_number: usize) -> Result<AnnotationLine> {
    let mut reader = gff::io::Reader::new(Cursor::new(bytes));
    let line = reader
        .line_bufs()
        .next()
        .transpose()
        .map_err(|error| invalid_line(line_number, error))?
        .ok_or_else(|| invalid_line(line_number, "empty GFF3 line"))?;

    match line {
        gff::LineBuf::Directive(directive) => {
            if directive.key() == gff::directive_buf::key::FASTA {
                return Err(invalid_line(line_number, "embedded FASTA is not supported"));
            }
            Ok(AnnotationLine::Directive(directive))
        }
        gff::LineBuf::Comment(comment) => Ok(AnnotationLine::Comment(comment.into())),
        gff::LineBuf::Record(record) => checked_record(record, line_number),
    }
}

fn parse_gtf_line(bytes: &[u8], line_number: usize) -> Result<AnnotationLine> {
    let mut reader = gtf::io::Reader::new(Cursor::new(bytes));
    let line = reader
        .line_bufs()
        .next()
        .transpose()
        .map_err(|error| invalid_line(line_number, error))?
        .ok_or_else(|| invalid_line(line_number, "empty GTF line"))?;

    match line {
        gtf::LineBuf::Comment(comment) => Ok(AnnotationLine::Comment(comment.into())),
        gtf::LineBuf::Record(record) => checked_record(record, line_number),
    }
}

fn checked_record(record: gff::feature::RecordBuf, line_number: usize) -> Result<AnnotationLine> {
    let start = usize::from(record.start());
    let end = usize::from(record.end());
    if start > end {
        return Err(invalid_line(
            line_number,
            format!("feature start {start} exceeds end {end}"),
        ));
    }
    Ok(AnnotationLine::Record(FeatureRecord { inner: record }))
}

pub(crate) struct AnnotationWriter<'a> {
    dialect: Dialect,
    output: &'a mut dyn Write,
}

impl<'a> AnnotationWriter<'a> {
    pub(crate) fn new(dialect: Dialect, output: &'a mut dyn Write) -> Self {
        Self { dialect, output }
    }

    pub(crate) fn write(&mut self, line: &AnnotationLine) -> Result<()> {
        match (self.dialect, line) {
            (Dialect::Gff3, AnnotationLine::Directive(directive)) => {
                gff::io::Writer::new(&mut self.output)
                    .write_line(&gff::LineBuf::Directive(directive.clone()))
            }
            (Dialect::Gff3, AnnotationLine::Comment(comment)) => {
                gff::io::Writer::new(&mut self.output)
                    .write_line(&gff::LineBuf::Comment(comment.clone().into()))
            }
            (Dialect::Gff3, AnnotationLine::Record(record)) => {
                gff::io::Writer::new(&mut self.output).write_record(&record.inner)
            }
            (Dialect::Gtf, AnnotationLine::Comment(comment)) => {
                gtf::io::Writer::new(&mut self.output)
                    .write_line(&gtf::LineBuf::Comment(comment.clone().into()))
            }
            (Dialect::Gtf, AnnotationLine::Record(record)) => {
                gtf::io::Writer::new(&mut self.output).write_record(&record.inner)
            }
            (Dialect::Gtf, AnnotationLine::Directive(_)) => {
                return Err(RsomicsError::InvalidInput(
                    "GFF3 directive encountered in GTF output".to_owned(),
                ));
            }
        }
        .rs_context("writing annotation output")
    }
}

pub(crate) fn invalid_line(line_number: usize, error: impl std::fmt::Display) -> RsomicsError {
    RsomicsError::InvalidInput(format!("line {line_number}: {error}"))
}

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

    #[test]
    fn one_base_feature_converts_to_half_open_interval() {
        let mut interval = None;
        for_each_line(
            &b"chr1\tsrc\tgene\t1\t1\t.\t+\t.\tID=g1\n"[..],
            Dialect::Gff3,
            |_, line| {
                if let AnnotationLine::Record(record) = line {
                    interval = Some(record.interval()?);
                }
                Ok(())
            },
        )
        .unwrap();
        let interval = interval.unwrap();
        assert_eq!(interval.chrom(), "chr1");
        assert_eq!((interval.start(), interval.end()), (0, 1));
    }

    #[test]
    fn inverted_coordinates_fail_with_line_number() {
        let error = for_each_line(
            &b"chr1\tsrc\tgene\t2\t1\t.\t+\t.\tID=g1\n"[..],
            Dialect::Gff3,
            |_, _| Ok(()),
        )
        .unwrap_err();
        let message = error.to_string();
        assert!(message.contains("line 1"), "{message}");
        assert!(message.contains("exceeds end"), "{message}");
    }

    #[test]
    fn blank_lines_are_ignored() {
        let mut records = 0;
        for_each_line(
            &b"\n\r\nchr1\tsrc\tgene\t1\t2\t.\t+\t.\tID=g1\n"[..],
            Dialect::Gff3,
            |_, line| {
                records += usize::from(matches!(line, AnnotationLine::Record(_)));
                Ok(())
            },
        )
        .unwrap();
        assert_eq!(records, 1);
    }
}