Installation

To install RiboMetric:

$ pip install ribometric

For PDF export support (adds ~30 dependencies):

$ pip install "ribometric[pdf]"

Usage

Create annotation files from gff files:

$ RiboMetric prepare -g gff_file.gff

Use the annotation file to run RiboMetric on a bam file:

$ RiboMetric run -b bam_file.bam -a annotation_RiboMetric.tsv

View results interactively in your terminal:

$ RiboMetric view bam_file_RiboMetric.json

By default, RiboMetric calculates standard Ribo-Seq QC metrics. To enable optional (theoretical) metrics:

$ RiboMetric run -b bam_file.bam -a annotation_RiboMetric.tsv --enable-optional-metrics

Or enable specific metrics:

$ RiboMetric run -b bam_file.bam -a annotation_RiboMetric.tsv --enable-metric periodicity_fourier

For more information on how to use RiboMetric, see the documentation or use --help

Improved outputs for pipelines and review:

# One-line summary, QC status, comparison, and detailed metrics
$ RiboMetric run -b bam.bam -a annotation.tsv --improved-outputs

Or pick specific ones:

$ RiboMetric run -b bam.bam -a annotation.tsv \
    --summary-tsv --qc-status --comparison-csv --metrics-table

Gate a pipeline on QC thresholds (exits 0/1/2 for PASS/WARN/FAIL):

$ RiboMetric evaluate -i sample_RiboMetric.json -e thresholds.yml

The thresholds YAML lists per-metric pass and warn values:

thresholds:
  periodicity_dominance: {pass: 0.7, warn: 0.5}
  prop_reads_CDS:        {pass: 0.7, warn: 0.5}

If -e is omitted, built-in defaults are used. Use -o to save the evaluation as JSON. Accepts either a RiboMetric JSON or a metrics-table CSV.

A result keeps measurements and judgements apart. results["metrics"] holds raw measurements in their natural units and natural direction: a rate goes up as the library gets worse, and its key says so (duplicate_rate, terminal_bias_kl_5prime in bits). results["scores"] holds 0–1 scores that are always higher-is-better and are named for the good property (fragment_uniqueness_score, periodicity_dominance_score). The full contract is in docs/METRIC_NAMING.md.

evaluate thresholds apply to raw metrics, and evaluate takes each metric’s direction from the metric registry, so a high duplicate rate fails rather than passes. To force a direction for a custom metric, add direction: lower (or higher) alongside its pass/warn values in the thresholds YAML:

thresholds:
  duplicate_rate: {pass: 0.3, warn: 0.5, direction: lower}

Enable the RUST metric (requires a transcriptome FASTA, gzip supported):

$ RiboMetric run -b sample.bam -a annotation.tsv \
    -f transcriptome.fa.gz \
    --enable-metric rust_mean_kl_divergence

For BAMs with no stored sequences, skip sequence-based metrics to avoid errors:

$ RiboMetric run -b no_seq.bam -a annotation.tsv --skip-sequence-metrics

Multimapper metrics use NH:i:N when the tag is present. Otherwise they fall back to the STAR convention where MAPQ=255 is unique and MAPQ<255 is multi-mapping. rpf_multimapper_rate is weighted at the RPF level, while alignment_multimapper_rate is row-based. (The pre-2.0 multimapper_rate alias is no longer a metric; it survives only in alignment_stats.)

Control multimapper handling for frame-sensitive calculations:

# Default: use NH=1 when available, otherwise STAR MAPQ=255
$ RiboMetric run -b star.bam -a annotation.tsv --multimap-filter unique_only
# Pre-1.1 behaviour: use all primary reads
$ RiboMetric run -b star.bam -a annotation.tsv --multimap-filter none

Features

RiboMetric calculates comprehensive quality metrics for Ribo-Seq data:

Default Metrics (Standard Ribo-Seq QC):

• Read length distribution (IQR, CV, max proportion, bimodality)

• Terminal nucleotide bias (5′ and 3′ ligation bias detection)

• 3-nt periodicity (frame dominance and information content)

• Metagene uniformity (entropy-based)

• CDS coverage and regional distribution (5′UTR, CDS, 3′UTR)

• Alignment quality — duplicate rate, multimapper rate, 5′ soft-clip rate

• Di-some detection — bimodality coefficient + disome proportion (50–70 nt reads)

• Codon-level translation — stop-codon readthrough ratio, start-codon enrichment ratio

• Recommended read lengths — which lengths carry clean 3-nt periodicity (and their P-site offsets) for downstream ORF/P-site analysis; tune with --min-periodicity

• Gene-body coverage ramp — 5′→3′ A-site density across relative CDS position (translation ramp / 3′ drop-off)

• Library complexity — analytic saturation curve (“was this sequenced deeply enough?”)

• Library-type classification — elongation / initiation / low-quality call with supporting evidence

• FLOSS read-length heterogeneity — fraction of transcripts with aberrant footprint-length profiles (library homogeneity QC)

FASTA-dependent (computed automatically when ``–fasta`` is supplied):

• A-site codon dwell-times / pause sites — per-codon occupancy and pausing summary (proline, CGA)

Optional Metrics (require explicit ``–enable-metric``):

• RUST mean KL divergence — codon-specific A-site accumulation (requires --fasta)

• Alternative periodicity methods (autocorrelation, Fourier transform, Trips-Viz)

• Alternative uniformity methods (autocorrelation, Theil index, Gini index)

• Additional read length metrics (normality test)

Use --enable-optional-metrics to calculate all optional metrics, or --enable-metric <name> for specific ones.

Output Formats

RiboMetric provides multiple output formats for different use cases:

For Pipeline Integration:

• Summary TSV - One-line summary per sample for quick QC decisions

• QC Status JSON - Machine-readable pass/warn/fail with thresholds

• Comparison CSV - Wide format for multi-sample comparison

For Sample Review:

• Interactive TUI - Terminal-based viewer for exploring metrics (RiboMetric view)

• Interactive HTML - Professional reports with executive summary and searchable metrics

• PDF - Archivable reports for documentation

• Metrics Table CSV - Detailed metrics with read-length breakdowns

See REPORTING_GUIDE.md for complete documentation and examples.

Upgrading to 2.0: renamed metric keys

2.0 renames or removes 25 metric keys, and eight of them changed value as well as name. For example terminal_bias_maxabs_5prime held 1 − max deviation; terminal_bias_max_deviation_5prime now holds the deviation itself. The full mapping is in docs/METRIC_NAMING.md.

For one minor cycle every pre-2.0 spelling is still written under results["metrics_legacy"], with its pre-2.0 value, so pipelines can migrate key by key; it is removed in 2.1. Cohort tables and --expected policies that name the renamed keys must be regenerated rather than search-and-replaced, because the values changed.

Requirements

• Transcriptomic alignments in coordinate-sorted BAM format

• GFF3/GTF annotations (Ensembl recommended)

• samtools >= 1.10 available on PATH (used for idxstats and indexing)

Testing

RiboMetric has a comprehensive test suite. The quickest way to run it is via pixi (all dependencies, including test extras, are resolved automatically):

$ pixi run test

Or with a standard virtual environment:

$ pip install -e ".[dev]"
$ pytest

Credits

This project was worked on by Lukas Wierdsma during his Internship at the UCC for Bioinformatics, Howest in 2023.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.