roers 0.5.0

A tool to prepare augmented annotations for single-cell RNA-seq analysis.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# roers

[![crates.io](https://img.shields.io/crates/v/roers.svg)](https://crates.io/crates/roers)

A Rust library and command-line tool for preparing *augmented* transcriptome
references for quantification with [`alevin-fry`](https://alevin-fry.readthedocs.io/en/latest/)
and [`simpleaf`](https://github.com/COMBINE-lab/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):

| Type | Short | What it adds |
|---|---|---|
| `intronic` | `i` | Merged intronic sequence per gene, with read-length-aware flanks. Spliced + intronic is the *splici* reference used for USA-mode quantification. |
| `gene-body` | `g` | The full genomic span of each gene, introns included. |
| `transcript-body` | `t` | The full genomic span of each transcript, introns included. Emitted with a `-T` suffix on the transcript id. |

With no `-a`, only spliced transcripts are written.

## Installing

As a tool:

```bash
cargo install roers
```

As a library:

```toml
[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:

```rust
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

```bash
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](https://github.com/COMBINE-lab/grangers) — the annotation parsing and
  range algebra underneath `roers`.
- [simpleaf](https://github.com/COMBINE-lab/simpleaf) — wraps `roers` as part of
  its end-to-end single-cell workflow.

## License

BSD 3-Clause; see [LICENSE](LICENSE).