rust-annovar 0.1.0.beta.1

data/src/io.rs

@@ -0,0 +1,217 @@
+use crate::model::Variant;
+use anyhow::{Context, Result, bail};
+use flate2::read::MultiGzDecoder;
+use std::fs::File;
+use std::io::{self, BufRead, BufReader, BufWriter, Read, Write};
+use std::path::Path;
+
+pub fn open_reader(path: &Path) -> Result<Box<dyn BufRead>> {
+    if path == Path::new("-") {
+        return Ok(Box::new(BufReader::new(io::stdin())));
+    }
+    let file = File::open(path).with_context(|| format!("cannot open {}", path.display()))?;
+    if path.extension().is_some_and(|ext| ext == "gz") {
+        Ok(Box::new(BufReader::new(MultiGzDecoder::new(file))))
+    } else {
+        Ok(Box::new(BufReader::new(file)))
+    }
+}
+
+pub fn open_writer(path: &Path) -> Result<Box<dyn Write>> {
+    if path == Path::new("-") {
+        Ok(Box::new(BufWriter::new(io::stdout())))
+    } else {
+        Ok(Box::new(BufWriter::new(File::create(path).with_context(
+            || format!("cannot create {}", path.display()),
+        )?)))
+    }
+}
+
+pub fn read_avinput(path: &Path) -> Result<Vec<Variant>> {
+    let reader = open_reader(path)?;
+    let mut variants = Vec::new();
+    for (line_no, line) in reader.lines().enumerate() {
+        let line = line.with_context(|| format!("failed reading line {}", line_no + 1))?;
+        if line.trim().is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let (fields, remainder) = split_avinput_fields(&line);
+        if fields.len() < 5 {
+            bail!(
+                "{}:{}: expected at least five AVinput columns",
+                path.display(),
+                line_no + 1
+            );
+        }
+        let av_start: u64 = fields[1]
+            .parse()
+            .with_context(|| format!("invalid start at line {}", line_no + 1))?;
+        let av_end: u64 = fields[2]
+            .parse()
+            .with_context(|| format!("invalid end at line {}", line_no + 1))?;
+        let reference = allele_from_avinput(fields[3]);
+        let alternate = allele_from_avinput(fields[4]);
+        let (start, end) = if reference.is_empty() {
+            (av_start, av_start)
+        } else {
+            if av_start == 0 {
+                bail!("AVinput coordinates are one-based at line {}", line_no + 1);
+            }
+            (av_start - 1, av_end)
+        };
+        let mut variant = Variant::new(fields[0], start, end, reference, alternate)?;
+        variant.output_chrom = fields[0].to_string();
+        variant.extra = remainder
+            .filter(|value| !value.is_empty())
+            .map(|value| value.split('\t').map(str::to_string).collect())
+            .unwrap_or_default();
+        variant.source_line = line_no + 1;
+        variants.push(variant);
+    }
+    Ok(variants)
+}
+
+pub fn read_vcf(path: &Path) -> Result<VcfDocument> {
+    let mut reader = open_reader(path)?;
+    let mut text = String::new();
+    reader.read_to_string(&mut text)?;
+    let mut headers = Vec::new();
+    let mut records = Vec::new();
+    let mut variants = Vec::new();
+    for (line_no, line) in text.lines().enumerate() {
+        if line.starts_with('#') {
+            headers.push(line.to_string());
+            continue;
+        }
+        if line.trim().is_empty() {
+            continue;
+        }
+        let fields: Vec<String> = line.split('\t').map(str::to_string).collect();
+        if fields.len() < 8 {
+            bail!(
+                "{}:{}: VCF requires at least eight columns",
+                path.display(),
+                line_no + 1
+            );
+        }
+        let pos: u64 = fields[1]
+            .parse()
+            .with_context(|| format!("invalid VCF POS at line {}", line_no + 1))?;
+        if pos == 0 {
+            bail!("VCF POS is one-based at line {}", line_no + 1);
+        }
+        let reference = fields[3].to_ascii_uppercase();
+        let alts: Vec<&str> = fields[4].split(',').collect();
+        let record_index = records.len();
+        for (allele_index, alt) in alts.iter().enumerate() {
+            if alt.starts_with('<')
+                || *alt == "*"
+                || *alt == "."
+                || alt.contains('[')
+                || alt.contains(']')
+            {
+                continue;
+            }
+            let (start, end, normalized_ref, normalized_alt) =
+                normalize_vcf_alleles(pos - 1, &reference, alt);
+            let mut variant = Variant::new(&fields[0], start, end, normalized_ref, normalized_alt)?;
+            variant.source_line = line_no + 1;
+            variant.source_record = Some(record_index);
+            variant.allele_index = allele_index;
+            variants.push(variant);
+        }
+        records.push(fields);
+    }
+    Ok(VcfDocument {
+        headers,
+        records,
+        variants,
+    })
+}
+
+/// Trim identical suffixes and prefixes while preserving at least one side of
+/// the event. Left alignment against a reference genome is intentionally a
+/// separate operation.
+pub fn normalize_vcf_alleles(
+    mut start: u64,
+    reference: &str,
+    alternate: &str,
+) -> (u64, u64, String, String) {
+    let mut r = reference.as_bytes().to_vec();
+    let mut a = alternate.as_bytes().to_vec();
+    while r.len() > 1 && a.len() > 1 && r.last() == a.last() {
+        r.pop();
+        a.pop();
+    }
+    while r.len() > 1 && a.len() > 1 && r.first() == a.first() {
+        r.remove(0);
+        a.remove(0);
+        start += 1;
+    }
+    if r.len() == 1 && a.len() > 1 && r[0] == a[0] {
+        start += 1;
+        a.remove(0);
+        r.clear();
+    } else if a.len() == 1 && r.len() > 1 && a[0] == r[0] {
+        start += 1;
+        r.remove(0);
+        a.clear();
+    }
+    let end = start + r.len() as u64;
+    (
+        start,
+        end,
+        String::from_utf8(r).unwrap(),
+        String::from_utf8(a).unwrap(),
+    )
+}
+
+pub fn write_avinput(variants: &[Variant], path: &Path, include_info: bool) -> Result<()> {
+    let mut writer = open_writer(path)?;
+    for variant in variants {
+        let mut fields = variant.avinput_fields().to_vec();
+        if include_info {
+            fields.extend(variant.extra.clone());
+        }
+        writeln!(writer, "{}", fields.join("\t"))?;
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone)]
+pub struct VcfDocument {
+    pub headers: Vec<String>,
+    pub records: Vec<Vec<String>>,
+    pub variants: Vec<Variant>,
+}
+
+fn allele_from_avinput(value: &str) -> String {
+    if value == "-" {
+        String::new()
+    } else {
+        value.to_ascii_uppercase()
+    }
+}
+
+fn split_avinput_fields(line: &str) -> (Vec<&str>, Option<&str>) {
+    let bytes = line.as_bytes();
+    let mut fields = Vec::with_capacity(5);
+    let mut cursor = 0usize;
+    while fields.len() < 5 {
+        while cursor < bytes.len() && bytes[cursor].is_ascii_whitespace() {
+            cursor += 1;
+        }
+        if cursor == bytes.len() {
+            break;
+        }
+        let start = cursor;
+        while cursor < bytes.len() && !bytes[cursor].is_ascii_whitespace() {
+            cursor += 1;
+        }
+        fields.push(&line[start..cursor]);
+    }
+    while cursor < bytes.len() && bytes[cursor].is_ascii_whitespace() {
+        cursor += 1;
+    }
+    (fields, (cursor < line.len()).then(|| &line[cursor..]))
+}

data/src/lib.rs

@@ -0,0 +1,12 @@
+//! Core annotation engine for `RustAnnovar`.
+//!
+//! Coordinates are always represented internally as zero-based half-open
+//! intervals. Parsers and writers are responsible for conversion at the edge.
+
+pub mod database;
+pub mod gene;
+pub mod io;
+pub mod model;
+pub mod pipeline;
+
+pub use model::{Annotation, AnnotationKind, Variant};

data/src/main.rs

@@ -0,0 +1,376 @@
+use anyhow::{Context, Result, bail};
+use clap::{Args, Parser, Subcommand, ValueEnum};
+use rust_annovar::database::IndexManifest;
+use rust_annovar::io::{read_avinput, read_vcf, write_avinput};
+use rust_annovar::pipeline::{
+    Operation, annotate_table, resolve_protocols, write_annotated_vcf, write_table,
+};
+use sha2::{Digest, Sha256};
+use std::fs;
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+
+#[derive(Parser)]
+#[command(
+    version,
+    about = "Fast genomic variant annotation with ANNOVAR-compatible databases"
+)]
+struct Cli {
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[derive(Subcommand)]
+enum Command {
+    /// Convert VCF to ANNOVAR's five-column input format.
+    Convert(ConvertArgs),
+    /// Run one annotation database.
+    Annotate(AnnotateArgs),
+    /// Combine multiple gene, region, and filter annotations.
+    Table(TableArgs),
+    /// Manage and validate local database metadata.
+    Db(DbArgs),
+    /// Extract reference sequence for AVinput intervals.
+    Sequence(SequenceArgs),
+    /// Report coding consequences (a gene annotation convenience command).
+    CodingChange(AnnotateArgs),
+    /// Select rows from a multi-annotation table using a simple predicate.
+    Reduce(ReduceArgs),
+}
+
+#[derive(Args)]
+struct ConvertArgs {
+    input: PathBuf,
+    #[arg(short, long, default_value = "-")]
+    output: PathBuf,
+    #[arg(long)]
+    include_info: bool,
+}
+
+#[derive(Clone, ValueEnum)]
+enum OpArg {
+    Gene,
+    Region,
+    Filter,
+}
+impl From<OpArg> for Operation {
+    fn from(value: OpArg) -> Self {
+        match value {
+            OpArg::Gene => Self::Gene,
+            OpArg::Region => Self::Region,
+            OpArg::Filter => Self::Filter,
+        }
+    }
+}
+
+#[derive(Args)]
+struct AnnotateArgs {
+    input: PathBuf,
+    database: PathBuf,
+    #[arg(short, long)]
+    output: PathBuf,
+    #[arg(long, value_enum, default_value = "filter")]
+    operation: OpArg,
+    #[arg(long, default_value = "annotation")]
+    protocol: String,
+    #[arg(long)]
+    fasta: Option<PathBuf>,
+    #[arg(long)]
+    vcf_input: bool,
+    #[arg(long, default_value = ".")]
+    nastring: String,
+}
+
+#[derive(Args)]
+struct TableArgs {
+    input: PathBuf,
+    db_dir: PathBuf,
+    #[arg(long)]
+    build: String,
+    #[arg(long, value_delimiter = ',')]
+    protocol: Vec<String>,
+    #[arg(long, value_delimiter = ',')]
+    operation: Vec<String>,
+    #[arg(short, long)]
+    output: PathBuf,
+    #[arg(long)]
+    vcf_input: bool,
+    #[arg(long)]
+    csv: bool,
+    #[arg(long)]
+    vcf_output: Option<PathBuf>,
+    #[arg(long, default_value = ".")]
+    nastring: String,
+}
+
+#[derive(Args)]
+struct DbArgs {
+    #[command(subcommand)]
+    command: DbCommand,
+}
+#[derive(Subcommand)]
+enum DbCommand {
+    Index {
+        database: PathBuf,
+        #[arg(long, default_value = "generic")]
+        kind: String,
+        #[arg(short, long)]
+        output: Option<PathBuf>,
+    },
+    Check {
+        index: PathBuf,
+    },
+    List {
+        db_dir: PathBuf,
+        #[arg(long)]
+        build: Option<String>,
+    },
+    /// Download a public database atomically, with optional SHA-256 verification.
+    Download {
+        url: String,
+        output: PathBuf,
+        #[arg(long)]
+        sha256: Option<String>,
+    },
+}
+
+#[derive(Args)]
+struct SequenceArgs {
+    input: PathBuf,
+    fasta: PathBuf,
+    #[arg(short, long)]
+    output: PathBuf,
+}
+
+#[derive(Args)]
+struct ReduceArgs {
+    input: PathBuf,
+    #[arg(short, long)]
+    output: PathBuf,
+    #[arg(long)]
+    column: String,
+    #[arg(long)]
+    equals: String,
+}
+
+fn main() {
+    if let Err(error) = run() {
+        eprintln!("error: {error:#}");
+        std::process::exit(2);
+    }
+}
+
+fn run() -> Result<()> {
+    match Cli::parse().command {
+        Command::Convert(args) => {
+            let document = read_vcf(&args.input)?;
+            write_avinput(&document.variants, &args.output, args.include_info)?;
+        }
+        Command::Annotate(args) => run_annotate(args, None)?,
+        Command::CodingChange(mut args) => {
+            args.operation = OpArg::Gene;
+            run_annotate(args, None)?;
+        }
+        Command::Table(args) => run_table(args)?,
+        Command::Db(args) => run_db(args.command)?,
+        Command::Sequence(args) => run_sequence(args)?,
+        Command::Reduce(args) => run_reduce(args)?,
+    }
+    Ok(())
+}
+
+fn run_annotate(args: AnnotateArgs, _reserved: Option<()>) -> Result<()> {
+    let operation = Operation::from(args.operation);
+    let document = args.vcf_input.then(|| read_vcf(&args.input)).transpose()?;
+    let variants = if let Some(doc) = &document {
+        doc.variants.clone()
+    } else {
+        read_avinput(&args.input)?
+    };
+    let protocol = rust_annovar::pipeline::Protocol {
+        name: args.protocol,
+        operation,
+        database: args.database,
+        fasta: args.fasta,
+    };
+    let result = annotate_table(&variants, &[protocol], &args.nastring)?;
+    write_table(&result, &args.output, false)
+}
+
+fn run_table(args: TableArgs) -> Result<()> {
+    let operations = args
+        .operation
+        .iter()
+        .map(|value| Operation::parse(value))
+        .collect::<Result<Vec<_>>>()?;
+    let protocols = resolve_protocols(&args.db_dir, &args.build, &args.protocol, &operations)?;
+    let document = args.vcf_input.then(|| read_vcf(&args.input)).transpose()?;
+    let variants = if let Some(doc) = &document {
+        doc.variants.clone()
+    } else {
+        read_avinput(&args.input)?
+    };
+    let result = annotate_table(&variants, &protocols, &args.nastring)?;
+    write_table(&result, &args.output, args.csv)?;
+    if let (Some(document), Some(vcf_output)) = (&document, args.vcf_output) {
+        write_annotated_vcf(document, &result, &protocols, &vcf_output, &args.nastring)?;
+    }
+    Ok(())
+}
+
+fn run_db(command: DbCommand) -> Result<()> {
+    match command {
+        DbCommand::Index {
+            database,
+            kind,
+            output,
+        } => {
+            let output = output.unwrap_or_else(|| database.with_extension("fai.json"));
+            IndexManifest::build(&database, &kind)?.write(&output)?;
+            println!("{}", output.display());
+        }
+        DbCommand::Check { index } => {
+            let manifest: IndexManifest = serde_json::from_reader(fs::File::open(&index)?)?;
+            if !manifest.is_current()? {
+                bail!("stale index: {}", index.display());
+            }
+            println!("current");
+        }
+        DbCommand::List { db_dir, build } => {
+            let prefix = build.map(|v| format!("{v}_"));
+            let mut entries = fs::read_dir(db_dir)?
+                .filter_map(Result::ok)
+                .map(|e| e.path())
+                .filter(|path| {
+                    path.extension().is_some_and(|ext| ext == "txt")
+                        && prefix.as_ref().is_none_or(|p| {
+                            path.file_name()
+                                .unwrap_or_default()
+                                .to_string_lossy()
+                                .starts_with(p)
+                        })
+                })
+                .collect::<Vec<_>>();
+            entries.sort();
+            for path in entries {
+                println!("{}", path.display());
+            }
+        }
+        DbCommand::Download {
+            url,
+            output,
+            sha256,
+        } => download_database(&url, &output, sha256.as_deref())?,
+    }
+    Ok(())
+}
+
+fn download_database(url: &str, output: &Path, expected_sha256: Option<&str>) -> Result<()> {
+    let parent = output.parent().unwrap_or_else(|| Path::new("."));
+    fs::create_dir_all(parent)?;
+    let temp = output.with_extension("download.tmp");
+    let result = (|| -> Result<()> {
+        let response = ureq::get(url)
+            .call()
+            .with_context(|| format!("failed to download {url}"))?;
+        let mut reader = response.into_reader();
+        let mut writer = fs::File::create(&temp)?;
+        let mut hasher = Sha256::new();
+        let mut buffer = [0u8; 64 * 1024];
+        loop {
+            let size = reader.read(&mut buffer)?;
+            if size == 0 {
+                break;
+            }
+            writer.write_all(&buffer[..size])?;
+            hasher.update(&buffer[..size]);
+        }
+        writer.sync_all()?;
+        let actual = format!("{:x}", hasher.finalize());
+        if let Some(expected) = expected_sha256
+            && !actual.eq_ignore_ascii_case(expected)
+        {
+            bail!("SHA-256 mismatch: expected {expected}, got {actual}");
+        }
+        fs::rename(&temp, output)?;
+        println!("{actual}  {}", output.display());
+        Ok(())
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(&temp);
+    }
+    result
+}
+
+fn run_sequence(args: SequenceArgs) -> Result<()> {
+    let genome = read_fasta_genome(&args.fasta)?;
+    let variants = read_avinput(&args.input)?;
+    let mut output = String::new();
+    for (index, variant) in variants.iter().enumerate() {
+        let sequence = genome
+            .get(&variant.chrom)
+            .context("chromosome missing from FASTA")?;
+        let end = usize::try_from(variant.end)?;
+        let start = usize::try_from(variant.start)?;
+        if end > sequence.len() {
+            bail!("variant {} exceeds chromosome length", index + 1);
+        }
+        output.push_str(&format!(
+            ">variant_{} {}:{}-{}\n{}\n",
+            index + 1,
+            variant.chrom,
+            variant.start + 1,
+            variant.end,
+            String::from_utf8_lossy(&sequence[start..end])
+        ));
+    }
+    fs::write(args.output, output)?;
+    Ok(())
+}
+
+fn read_fasta_genome(path: &Path) -> Result<std::collections::HashMap<String, Vec<u8>>> {
+    use std::io::BufRead;
+    let mut map = std::collections::HashMap::new();
+    let mut id = None::<String>;
+    let mut seq = Vec::new();
+    for line in rust_annovar::io::open_reader(path)?.lines() {
+        let line = line?;
+        if let Some(header) = line.strip_prefix('>') {
+            if let Some(previous) = id.replace(rust_annovar::model::normalize_chrom(
+                header
+                    .split_whitespace()
+                    .next()
+                    .context("empty FASTA header")?,
+            )) {
+                map.insert(previous, std::mem::take(&mut seq));
+            }
+        } else {
+            seq.extend(line.trim().as_bytes().iter().map(u8::to_ascii_uppercase));
+        }
+    }
+    if let Some(id) = id {
+        map.insert(id, seq);
+    }
+    Ok(map)
+}
+
+fn run_reduce(args: ReduceArgs) -> Result<()> {
+    let content = fs::read_to_string(&args.input)?;
+    let mut lines = content.lines();
+    let header = lines.next().context("empty table")?;
+    let headers: Vec<&str> = header.split('\t').collect();
+    let column = headers
+        .iter()
+        .position(|name| *name == args.column)
+        .with_context(|| format!("unknown column {}", args.column))?;
+    let mut output = String::from(header);
+    output.push('\n');
+    for line in lines {
+        if line.split('\t').nth(column) == Some(args.equals.as_str()) {
+            output.push_str(line);
+            output.push('\n');
+        }
+    }
+    fs::write(args.output, output)?;
+    Ok(())
+}