roers

A Rust library and command-line tool for preparing augmented transcriptome references for quantification with alevin-fry and simpleaf.

Given a genome FASTA and a GTF/GFF3 annotation, roers writes a FASTA of spliced transcripts, optionally augmented with additional sequence, plus the transcript-to-gene (t2g) mapping the downstream tools need.

Augmentation types

Pick these with -a (comma-separated; short forms in parentheses):

With no -a, only spliced transcripts are written.

Installing

As a tool:

cargo install roers

As a library:

[dependencies]
roers = "0.5"

Using it as a library

The entire API is [AugRefOpts] and [make_ref]. AugRefOpts derives clap's Args, so it doubles as the CLI options struct:

use roers::{AugRefOpts, AugType};
use std::path::PathBuf;

# fn run(opts: AugRefOpts) -> anyhow::Result<()> {
roers::make_ref(opts)?;
# Ok(())
# }

Output

• <prefix>_ref.fa — the reference FASTA
• t2g.tsv or t2g_3col.tsv — the transcript-to-gene map (three columns, with a spliced/unspliced/ambiguous status, whenever augmentation is requested)
• gene_id_to_name.tsv — gene id to gene name
• <prefix>_make-ref.json — the exact options used, for provenance

Command-line help

build the (expanded) reference index

Usage: roers make-ref [OPTIONS] <GENOME> <GENES> <OUT_DIR>

Arguments:
  <GENOME>   The path to a genome fasta file
  <GENES>    The path to a gene annotation gtf/gff3 file
  <OUT_DIR>  The path to the output directory (will be created if it doesn't exist)

Options:
  -a, --aug-type <AUG_TYPE>
          Comma separated types of augmented sequences to include in the output FASTA file on
          top of spliced transcripts. Available options are `intronic` (or `i` for short),
          `gene-body` (or `g`), and `transcript-body` (or `t`)
      --dedup
          Indicates whether identical sequences will be deduplicated
  -p, --filename-prefix <FILENAME_PREFIX>
          The file name prefix of the generated output files [default: roers_ref]
      --no-transcript
          A flag of not including spliced transcripts in the output FASTA file. (usually there
          should be a good reason to do so)
      --gff3
          Denotes that the input annotation is a GFF3 (instead of GTF) file
  -h, --help
          Print help
  -V, --version
          Print version

Intronic Sequence Options:
  -r, --read-length <READ_LENGTH>
          The read length of the single-cell experiment being processed (determines flank size)
          [default: 91]
      --flank-trim-length <FLANK_TRIM_LENGTH>
          Determines the length of sequence subtracted from the read length to obtain the flank
          length [default: 5]
      --no-flanking-merge
          Indicates whether flank lengths will be considered when merging introns

Extra Spliced Sequence File:
      --extra-spliced <EXTRA_SPLICED>  The path to an extra spliced sequence fasta file

Extra Unspliced Sequence File:
      --extra-unspliced <EXTRA_UNSPLICED>  The path to an extra unspliced sequence fasta file

Related projects

• grangers — the annotation parsing and range algebra underneath roers.
• simpleaf — wraps roers as part of its end-to-end single-cell workflow.

License

BSD 3-Clause; see LICENSE.