RiboMetric 1.3.0

A python command-line utility for the generation of comprehensive reports on the quality of ribosome profiling (Ribo-Seq) datasets

A python command-line utility for the generation of comprehensive reports on the quality of ribosome profiling (Ribo-Seq) datasets

• Free software: MIT license

• Documentation: https://RiboMetric.readthedocs.io.

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 output_RiboMetric_data.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_data.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.

Most RiboMetric metrics are normalised so that higher is better (e.g. periodicity_dominance, uniformity_entropy, prop_reads_CDS). A few are lower is better — duplicate_rate, multimapper_rate, rpf_multimapper_rate, alignment_multimapper_rate, soft_clip_rate_5prime, disome_proportion, stop_codon_readthrough_ratio and the raw terminal-bias divergences. evaluate knows these directions, 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. multimapper_rate is retained as an alias for the weighted RPF-level metric, while alignment_multimapper_rate is row-based.

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.

Deprecated metric keys

RiboMetric now publishes both consolidated and legacy metric names to ease upgrades:

• Consolidated: terminal_bias_kl_5prime, terminal_bias_kl_3prime, terminal_bias_maxabs_5prime, terminal_bias_maxabs_3prime, cds_coverage

• Legacy: terminal_nucleotide_bias_distribution_5_prime_metric, terminal_nucleotide_bias_distribution_3_prime_metric, terminal_nucleotide_bias_max_absolute_metric_5_prime_metric, terminal_nucleotide_bias_max_absolute_metric_3_prime_metric, CDS_coverage_metric

Plots and summary normalization accept both. We recommend migrating dashboards and downstream code to the consolidated names.

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.