rsomics-annotation 0.1.0

Typed GFF3 and GTF validation, selection, conversion, and sequence extraction
Documentation
use std::path::{Path, PathBuf};
use std::process;

use clap::{ArgGroup, Args, Parser, Subcommand};
use rsomics_common::{
    OutputArgs, Result, RsomicsError, ToolMeta, reject_output_alias, run as run_tool,
};

use crate::annotation::Dialect;
use crate::io::{open_input, with_named_outputs, with_output};
use crate::view::{AttributePredicate, Region, Selection};

const META: ToolMeta = ToolMeta {
    name: "rsomics-annotation",
    version: env!("CARGO_PKG_VERSION"),
};

#[derive(Debug, Parser)]
#[command(
    name = "rsomics-annotation",
    version,
    about = "Typed GFF3 and GTF operations",
    arg_required_else_help = true
)]
struct Cli {
    #[command(flatten)]
    output: OutputArgs,

    #[command(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    /// Validate record syntax, coordinates, phase, and hierarchy identifiers
    Validate(InputArgs),
    /// Select annotation records by type, attribute, or genomic range
    View(ViewArgs),
    /// Convert feature coordinates to BED6
    ToBed(ToBedArgs),
    /// Extract spliced transcript, coding, or protein FASTA
    Extract(ExtractArgs),
}

#[derive(Debug, Args)]
#[command(next_help_heading = "Input")]
struct InputArgs {
    /// Input annotation; omit or use - for standard input
    #[arg(value_name = "GFF_OR_GTF")]
    input: Option<PathBuf>,

    /// Input annotation dialect
    #[arg(short, long, value_enum)]
    format: Dialect,
}

#[derive(Debug, Args)]
struct ViewArgs {
    #[command(flatten)]
    input: InputArgs,

    /// Output annotation; omit or use - for standard output
    #[arg(short, long, value_name = "GFF_OR_GTF", help_heading = "Output")]
    output: Option<PathBuf>,

    /// Keep this feature type; repeat to keep multiple types
    #[arg(long = "type", value_name = "TYPE", help_heading = "Selection")]
    types: Vec<String>,

    /// Require KEY or KEY=VALUE; repeat to combine predicates
    #[arg(long, value_name = "KEY[=VALUE]", help_heading = "Selection")]
    attribute: Vec<String>,

    /// Keep features overlapping a 1-based inclusive SEQID:START-END range
    #[arg(long, value_name = "REGION", help_heading = "Selection")]
    region: Option<String>,

    /// Require full containment in --region
    #[arg(long, requires = "region", help_heading = "Selection")]
    contained: bool,

    /// Emit at most this many matching records
    #[arg(long, value_name = "N", help_heading = "Selection")]
    head: Option<usize>,
}

#[derive(Debug, Args)]
struct ToBedArgs {
    #[command(flatten)]
    input: InputArgs,

    /// Output BED6; omit or use - for standard output
    #[arg(short, long, value_name = "BED", help_heading = "Output")]
    output: Option<PathBuf>,

    /// Convert only this feature type; repeat to keep multiple types
    #[arg(long = "type", value_name = "TYPE", help_heading = "Selection")]
    types: Vec<String>,
}

#[derive(Debug, Args)]
#[command(group(
    ArgGroup::new("fasta_outputs")
        .required(true)
        .multiple(true)
        .args(["transcripts", "coding", "proteins"])
))]
struct ExtractArgs {
    #[command(flatten)]
    input: InputArgs,

    /// Genome FASTA, optionally accompanied by .fai
    #[arg(short = 'g', long, value_name = "FASTA")]
    genome: PathBuf,

    /// Write spliced transcript FASTA
    #[arg(short = 'w', long, value_name = "FASTA", help_heading = "Output")]
    transcripts: Option<PathBuf>,

    /// Write spliced coding nucleotide FASTA
    #[arg(
        short = 'x',
        long = "cds",
        value_name = "FASTA",
        help_heading = "Output"
    )]
    coding: Option<PathBuf>,

    /// Write translated protein FASTA
    #[arg(
        short = 'y',
        long = "protein",
        value_name = "FASTA",
        help_heading = "Output"
    )]
    proteins: Option<PathBuf>,

    /// Omit CDS=start-end from transcript FASTA names
    #[arg(long, help_heading = "Output")]
    omit_cds_range: bool,

    /// Use * rather than . for retained internal stop codons
    #[arg(short = 'S', long, help_heading = "Output")]
    star_stop: bool,
}

#[must_use]
pub(crate) fn run() -> process::ExitCode {
    let cli = rsomics_help::parse::<Cli>();
    let output = cli.output.clone();
    run_tool(&output, META, || execute(cli))
}

fn execute(cli: Cli) -> Result<()> {
    match cli.command {
        Command::Validate(args) => {
            let input = open_input(args.input.as_deref())?;
            crate::validate::validate(input, args.format)
        }
        Command::View(args) => {
            require_named_json_output(cli.output.json, args.output.as_deref())?;
            if let Some(output) = args.output.as_deref() {
                reject_output_alias(output, args.input.input.as_deref())?;
            }
            let input = open_input(args.input.input.as_deref())?;
            let selection = Selection {
                types: args.types.into_iter().map(String::into_bytes).collect(),
                attributes: args
                    .attribute
                    .iter()
                    .map(|value| AttributePredicate::parse(value))
                    .collect::<Result<_>>()?,
                region: args.region.as_deref().map(Region::parse).transpose()?,
                contained: args.contained,
                head: args.head,
            };
            with_output(args.output.as_deref(), |output| {
                crate::view::view(input, output, args.input.format, &selection)
            })
        }
        Command::ToBed(args) => {
            require_named_json_output(cli.output.json, args.output.as_deref())?;
            if let Some(output) = args.output.as_deref() {
                reject_output_alias(output, args.input.input.as_deref())?;
            }
            let input = open_input(args.input.input.as_deref())?;
            let types: Vec<Vec<u8>> = args.types.into_iter().map(String::into_bytes).collect();
            with_output(args.output.as_deref(), |output| {
                crate::bed::to_bed(input, output, args.input.format, &types)
            })
        }
        Command::Extract(args) => {
            reject_extract_aliases(&args)?;
            let input = open_input(args.input.input.as_deref())?;
            let paths: Vec<&Path> = [
                args.transcripts.as_deref(),
                args.coding.as_deref(),
                args.proteins.as_deref(),
            ]
            .into_iter()
            .flatten()
            .collect();
            with_named_outputs(&paths, |staged| {
                let mut writers = staged.iter_mut();
                let transcripts = args
                    .transcripts
                    .as_ref()
                    .and_then(|_| writers.next())
                    .map(|output| output as &mut dyn std::io::Write);
                let coding = args
                    .coding
                    .as_ref()
                    .and_then(|_| writers.next())
                    .map(|output| output as &mut dyn std::io::Write);
                let proteins = args
                    .proteins
                    .as_ref()
                    .and_then(|_| writers.next())
                    .map(|output| output as &mut dyn std::io::Write);
                let mut outputs = crate::extract::Outputs {
                    transcripts,
                    coding,
                    proteins,
                };
                crate::extract::extract(
                    input,
                    args.input.format,
                    &args.genome,
                    &crate::extract::Options {
                        omit_coding_range: args.omit_cds_range,
                        star_stop: args.star_stop,
                    },
                    &mut outputs,
                )
            })
        }
    }
}

fn reject_extract_aliases(args: &ExtractArgs) -> Result<()> {
    let outputs: Vec<&Path> = [
        args.transcripts.as_deref(),
        args.coding.as_deref(),
        args.proteins.as_deref(),
    ]
    .into_iter()
    .flatten()
    .collect();
    if outputs.iter().any(|path| *path == Path::new("-")) {
        return Err(RsomicsError::ConfigError(
            "extract FASTA outputs must be named files".to_owned(),
        ));
    }
    for (index, output) in outputs.iter().enumerate() {
        let inputs = args
            .input
            .input
            .as_deref()
            .into_iter()
            .chain(std::iter::once(args.genome.as_path()))
            .chain(outputs[..index].iter().copied());
        reject_output_alias(output, inputs)?;
    }
    Ok(())
}

fn require_named_json_output(json: bool, output: Option<&Path>) -> Result<()> {
    if json && output.is_none_or(|path| path == Path::new("-")) {
        return Err(RsomicsError::ConfigError(
            "--json requires a named --output file so JSON cannot mix with annotation data"
                .to_owned(),
        ));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use clap::CommandFactory;

    use super::*;

    #[test]
    fn command_tree_is_valid() {
        Cli::command().debug_assert();
    }

    #[test]
    fn global_options_are_limited_to_shared_output() {
        let error = Cli::try_parse_from(["rsomics-annotation", "--help"]).unwrap_err();
        let help = error.to_string();
        assert!(help.contains("Global options:"), "{help}");
        assert!(help.contains("--json"), "{help}");
        for absent in ["--threads", "--seed", "--quiet", "--verbose"] {
            assert!(!help.contains(absent), "{help}");
        }
    }

    #[test]
    fn contained_requires_region() {
        let error = Cli::try_parse_from([
            "rsomics-annotation",
            "view",
            "--format",
            "gff3",
            "--contained",
        ])
        .unwrap_err();
        assert_eq!(
            error.kind(),
            clap::error::ErrorKind::MissingRequiredArgument
        );
    }
}