Metadata-Version: 2.4
Name: ribometric
Version: 1.5.0
Summary: A python command-line utility for the generation of comprehensive reports on the quality of ribosome profiling (Ribo-Seq) datasets
Home-page: https://github.com/JackCurragh/RiboMetric
Author: Jack Tierney
Author-email: jackcurragh@gmail.com
License: MIT license
Keywords: RiboMetric
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10,<3.13
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: biopython>=1.81
Requires-Dist: gffpandas>=1.2.0
Requires-Dist: Jinja2>=3.0
Requires-Dist: kaleido>=1.0.0
Requires-Dist: numpy<2,>=1.24
Requires-Dist: oxbow>=0.3.0
Requires-Dist: pandas<2.3,>=2.0
Requires-Dist: plotly>=5.14
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: pysam>=0.21.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.3.3
Requires-Dist: scipy>=1.10
Requires-Dist: textual>=0.47.0
Provides-Extra: pdf
Requires-Dist: xhtml2pdf>=0.2.11; extra == "pdf"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: coverage>=7.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: myst-parser>=2.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: bump2version>=1.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

================
RiboMetric
================


.. image:: https://img.shields.io/pypi/v/RiboMetric.svg
        :target: https://pypi.python.org/pypi/RiboMetric
        :alt: PyPI version

.. image:: https://readthedocs.org/projects/RiboMetric/badge/?version=latest
        :target: https://RiboMetric.readthedocs.io/en/latest/?version=latest
        :alt: Documentation Status

.. image:: https://github.com/JackCurragh/RiboMetric/workflows/Build%20and%20Deploy%20Package/badge.svg
        :target: https://github.com/JackCurragh/RiboMetric/actions
        :alt: Build Status

.. image:: https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue
        :target: https://www.python.org/downloads/
        :alt: Python Version

.. image:: https://img.shields.io/github/license/JackCurragh/RiboMetric
        :target: https://github.com/JackCurragh/RiboMetric/blob/main/LICENSE
        :alt: License


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:

.. code-block:: console

    $ pip install ribometric

For PDF export support (adds ~30 dependencies):

.. code-block:: console

    $ pip install "ribometric[pdf]"

Usage
------------

Create annotation files from gff files:

.. code-block:: console

    $ RiboMetric prepare -g gff_file.gff

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

.. code-block:: console

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

View results interactively in your terminal:

.. code-block:: console

    $ RiboMetric view bam_file_RiboMetric.json

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

.. code-block:: console

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

Or enable specific metrics:

.. code-block:: console

    $ 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 :code:`--help`

Improved outputs for pipelines and review:

.. code-block:: console

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

Or pick specific ones:

.. code-block:: console

    $ 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):

.. code-block:: console

    $ 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 <https://github.com/JackCurragh/RiboMetric/blob/main/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):

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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:

.. code-block:: console

    # 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

.. _documentation: https://ribometric.readthedocs.io/en/latest/?version=latest

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 <https://github.com/JackCurragh/RiboMetric/blob/main/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.

.. _REPORTING_GUIDE.md: docs/REPORTING_GUIDE.md

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 <https://pixi.sh>`_ (all dependencies, including test extras, are
resolved automatically):

.. code-block:: console

    $ pixi run test

Or with a standard virtual environment:

.. code-block:: console

    $ 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.

.. _`Lukas Wierdsma`: https://github.com/Lukas-Wierdsma
.. _`Internship at the UCC`: https://github.com/Lukas-Wierdsma/Internship-UCC-2023/wiki

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
