energorna 0.1.0__tar.gz

energorna-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Jose Antonio Vilar Sánchez (QMetrika Labs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTICE — The MIT license above covers this SOURCE CODE. The underlying METHOD
+(mRNA nearest-neighbor thermodynamic fingerprinting for variant scoring) is
+covered by patent P202630522 (OEPM, Spain). Commercial use of the patented
+method may require a separate license. Research and academic use is unaffected.
+
+This software is for RESEARCH USE ONLY and is not a medical device.

energorna-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: energorna
+Version: 0.1.0
+Summary: Glass-box local periodicity-loss observable of the mRNA stacking profile for repeat-expansion disorders (DM1, Huntington, SCA1)
+Author-email: Jose Antonio Vilar Sanchez <qmetrika@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/josevilar-qbioai/energorna
+Project-URL: Repository, https://github.com/josevilar-qbioai/energorna
+Project-URL: Issues, https://github.com/josevilar-qbioai/energorna/issues
+Keywords: repeat expansion,myotonic dystrophy,huntington,SCA1,trinucleotide,age at onset,mRNA,thermodynamics,interruptions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# energorna
+
+[![CI](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml/badge.svg)](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/energorna.svg)](https://pypi.org/project/energorna/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Glass-box local periodicity-loss observable of the mRNA stacking-energy profile, for
+repeat-expansion disorders.** Numpy-only, no ViennaRNA / GPU / API. Part of the QMetrika
+Bio-IA thermodynamic engine (same Turner nearest-neighbor parameters as `ef-synonymous`).
+
+*[English](#english) · [Español](#español)*
+
+---
+
+## English
+
+### The idea
+
+In repeat-expansion diseases (myotonic dystrophy type 1, Huntington, SCA1, DM2…), age at
+onset is not set only by *how many* repeats there are, but by whether the repeat tract is
+**interrupted**. Interruptions (e.g. CCG in the CTG tract of DM1, CAA in the CAG tract of
+Huntington, CAT in SCA1) break the **periodicity** of the nearest-neighbor stacking energy
+profile Φ, disrupt the slipped-strand substrate that drives somatic instability, and
+**delay onset**.
+
+`energorna` computes a single glass-box observable — `periodicity_loss = 1 − ACF_period(Φ)`,
+the loss of autocorrelation (at the motif period) of the Turner stacking profile — that
+captures this. It **auto-calibrates the period** per motif (3 for trinucleotides, 4 for the
+CCTG tetranucleotide) and, unlike simply counting interruptions, is sensitive to their
+**type** and **position**.
+
+### Install
+
+```bash
+pip install energorna
+```
+
+### Use — CLI
+
+```bash
+# pure (CTG)40 vs an interrupted allele
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file allele.fasta --motif CAG
+```
+
+Output shows the observable next to the traditional baselines:
+
+```
+motif CTG (period 3) · 62 units · longest uninterrupted run 51
+  periodicity_loss      = 0.18xx   <- observable
+  periodicity_loss (3') = 0.19xx
+  n_interruptions       = 4        (count baseline)
+  fragmentation_index   = 0.09xx   (fragmentation baseline)
+```
+
+### Use — Python
+
+```python
+import energorna as ef
+
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detects the motif period)
+ef.periodicity_loss(seq, unit="CTG")        # global observable
+ef.periodicity_profile(seq, unit="CTG")     # (pos, loss) resolved 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # 3'-weighted
+ef.n_interruptions(seq, "CTG")              # count baseline (to compare)
+```
+
+### Why it matters (validation)
+
+Across three diseases, `periodicity_loss` (or its axis, the longest uninterrupted stretch)
+predicts age at onset **better than counting repeats**:
+
+| Disease | Data | Result |
+|---|---|---|
+| **DM1** | Pešović 2018, n=7 | periodicity vs onset residual **r=+0.81** (LOO robust, bootstrap CI [+0.59,+0.99], perm p=0.027) vs count +0.53; captures type (CCG≫CTC) & position |
+| **Huntington** | GeM-HD 2019 (published directions) | LOI < canonical < duplication — matches onset ordering |
+| **SCA1** | Menon 2013 Table S3, n=35 | longest uninterrupted stretch predicts onset **R²=0.64** vs 0.24 for total size (r=−0.80, p=5×10⁻⁵) |
+
+### Honest scope
+
+A **biologically motivated correlate**, not proven causality. Individual, interruption-typed
+cohorts at scale (OPTIMISTIC, Enroll-HD) are access-controlled; the claim is "better
+predictor than count on the available data, with a mechanistic hypothesis and falsifiable
+predictions" (correlation with measured somatic instability, UV melting, MSH3 binding).
+Research use only.
+
+---
+
+## Español
+
+### La idea
+
+En enfermedades de expansión de repeticiones (distrofia miotónica tipo 1, Huntington,
+SCA1, DM2…), la edad de inicio no la fija solo *cuántas* repeticiones hay, sino si el
+tracto está **interrumpido**. Las interrupciones (p. ej. CCG en el tracto CTG de DM1, CAA
+en el CAG de Huntington, CAT en SCA1) rompen la **periodicidad** del perfil de energía de
+apilamiento nearest-neighbor Φ, alteran el sustrato slipped-strand que dirige la
+inestabilidad somática y **retrasan el inicio**.
+
+`energorna` calcula un único observable glass-box — `periodicity_loss = 1 − ACF_periodo(Φ)`,
+la pérdida de autocorrelación (al periodo del motivo) del perfil de apilamiento Turner —
+que lo captura. **Auto-calibra el periodo** por motivo (3 en trinucleótidos, 4 en el
+tetranucleótido CCTG) y, a diferencia de contar interrupciones, es sensible a su **tipo**
+y **posición**.
+
+### Instalación
+
+```bash
+pip install energorna
+```
+
+### Uso — CLI
+
+```bash
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file alelo.fasta --motif CAG
+```
+
+### Uso — Python
+
+```python
+import energorna as ef
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detecta el periodo)
+ef.periodicity_loss(seq, unit="CTG")        # observable global
+ef.periodicity_profile(seq, unit="CTG")     # perfil (pos, pérdida) 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # ponderado 3'
+```
+
+### Por qué importa (validación)
+
+En tres enfermedades, `periodicity_loss` (o su eje, el tramo ininterrumpido más largo)
+predice la edad de inicio **mejor que contar repeticiones**: DM1 (Pešović n=7, r=+0,81),
+Huntington (direcciones publicadas, LOI<canónico<duplicación) y SCA1 (Menon 2013 n=35,
+R²=0,64 vs 0,24 del tamaño total). Ver la tabla en la sección en inglés.
+
+### Alcance honesto
+
+Es un **correlato biológicamente motivado**, no una causalidad demostrada. Los datos
+individuales tipados a escala son de acceso controlado; el claim es "mejor predictor que
+el conteo en los datos disponibles, con hipótesis mecanística y predicciones falsables".
+Uso solo para investigación (RUO).
+
+---
+
+### Citation / Cita
+
+Vilar Sánchez JA. *energoRNA: local periodicity loss of the mRNA stacking profile predicts
+age at onset in repeat-expansion disorders.* QMetrika Labs, 2026. Method covered by patent
+P202630522 (OEPM). Code under MIT.
+
+- Repo: https://github.com/josevilar-qbioai/energorna
+- ORCID: https://orcid.org/0009-0008-1057-4223

energorna-0.1.0/README.md

@@ -0,0 +1,154 @@
+# energorna
+
+[![CI](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml/badge.svg)](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/energorna.svg)](https://pypi.org/project/energorna/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Glass-box local periodicity-loss observable of the mRNA stacking-energy profile, for
+repeat-expansion disorders.** Numpy-only, no ViennaRNA / GPU / API. Part of the QMetrika
+Bio-IA thermodynamic engine (same Turner nearest-neighbor parameters as `ef-synonymous`).
+
+*[English](#english) · [Español](#español)*
+
+---
+
+## English
+
+### The idea
+
+In repeat-expansion diseases (myotonic dystrophy type 1, Huntington, SCA1, DM2…), age at
+onset is not set only by *how many* repeats there are, but by whether the repeat tract is
+**interrupted**. Interruptions (e.g. CCG in the CTG tract of DM1, CAA in the CAG tract of
+Huntington, CAT in SCA1) break the **periodicity** of the nearest-neighbor stacking energy
+profile Φ, disrupt the slipped-strand substrate that drives somatic instability, and
+**delay onset**.
+
+`energorna` computes a single glass-box observable — `periodicity_loss = 1 − ACF_period(Φ)`,
+the loss of autocorrelation (at the motif period) of the Turner stacking profile — that
+captures this. It **auto-calibrates the period** per motif (3 for trinucleotides, 4 for the
+CCTG tetranucleotide) and, unlike simply counting interruptions, is sensitive to their
+**type** and **position**.
+
+### Install
+
+```bash
+pip install energorna
+```
+
+### Use — CLI
+
+```bash
+# pure (CTG)40 vs an interrupted allele
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file allele.fasta --motif CAG
+```
+
+Output shows the observable next to the traditional baselines:
+
+```
+motif CTG (period 3) · 62 units · longest uninterrupted run 51
+  periodicity_loss      = 0.18xx   <- observable
+  periodicity_loss (3') = 0.19xx
+  n_interruptions       = 4        (count baseline)
+  fragmentation_index   = 0.09xx   (fragmentation baseline)
+```
+
+### Use — Python
+
+```python
+import energorna as ef
+
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detects the motif period)
+ef.periodicity_loss(seq, unit="CTG")        # global observable
+ef.periodicity_profile(seq, unit="CTG")     # (pos, loss) resolved 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # 3'-weighted
+ef.n_interruptions(seq, "CTG")              # count baseline (to compare)
+```
+
+### Why it matters (validation)
+
+Across three diseases, `periodicity_loss` (or its axis, the longest uninterrupted stretch)
+predicts age at onset **better than counting repeats**:
+
+| Disease | Data | Result |
+|---|---|---|
+| **DM1** | Pešović 2018, n=7 | periodicity vs onset residual **r=+0.81** (LOO robust, bootstrap CI [+0.59,+0.99], perm p=0.027) vs count +0.53; captures type (CCG≫CTC) & position |
+| **Huntington** | GeM-HD 2019 (published directions) | LOI < canonical < duplication — matches onset ordering |
+| **SCA1** | Menon 2013 Table S3, n=35 | longest uninterrupted stretch predicts onset **R²=0.64** vs 0.24 for total size (r=−0.80, p=5×10⁻⁵) |
+
+### Honest scope
+
+A **biologically motivated correlate**, not proven causality. Individual, interruption-typed
+cohorts at scale (OPTIMISTIC, Enroll-HD) are access-controlled; the claim is "better
+predictor than count on the available data, with a mechanistic hypothesis and falsifiable
+predictions" (correlation with measured somatic instability, UV melting, MSH3 binding).
+Research use only.
+
+---
+
+## Español
+
+### La idea
+
+En enfermedades de expansión de repeticiones (distrofia miotónica tipo 1, Huntington,
+SCA1, DM2…), la edad de inicio no la fija solo *cuántas* repeticiones hay, sino si el
+tracto está **interrumpido**. Las interrupciones (p. ej. CCG en el tracto CTG de DM1, CAA
+en el CAG de Huntington, CAT en SCA1) rompen la **periodicidad** del perfil de energía de
+apilamiento nearest-neighbor Φ, alteran el sustrato slipped-strand que dirige la
+inestabilidad somática y **retrasan el inicio**.
+
+`energorna` calcula un único observable glass-box — `periodicity_loss = 1 − ACF_periodo(Φ)`,
+la pérdida de autocorrelación (al periodo del motivo) del perfil de apilamiento Turner —
+que lo captura. **Auto-calibra el periodo** por motivo (3 en trinucleótidos, 4 en el
+tetranucleótido CCTG) y, a diferencia de contar interrupciones, es sensible a su **tipo**
+y **posición**.
+
+### Instalación
+
+```bash
+pip install energorna
+```
+
+### Uso — CLI
+
+```bash
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file alelo.fasta --motif CAG
+```
+
+### Uso — Python
+
+```python
+import energorna as ef
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detecta el periodo)
+ef.periodicity_loss(seq, unit="CTG")        # observable global
+ef.periodicity_profile(seq, unit="CTG")     # perfil (pos, pérdida) 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # ponderado 3'
+```
+
+### Por qué importa (validación)
+
+En tres enfermedades, `periodicity_loss` (o su eje, el tramo ininterrumpido más largo)
+predice la edad de inicio **mejor que contar repeticiones**: DM1 (Pešović n=7, r=+0,81),
+Huntington (direcciones publicadas, LOI<canónico<duplicación) y SCA1 (Menon 2013 n=35,
+R²=0,64 vs 0,24 del tamaño total). Ver la tabla en la sección en inglés.
+
+### Alcance honesto
+
+Es un **correlato biológicamente motivado**, no una causalidad demostrada. Los datos
+individuales tipados a escala son de acceso controlado; el claim es "mejor predictor que
+el conteo en los datos disponibles, con hipótesis mecanística y predicciones falsables".
+Uso solo para investigación (RUO).
+
+---
+
+### Citation / Cita
+
+Vilar Sánchez JA. *energoRNA: local periodicity loss of the mRNA stacking profile predicts
+age at onset in repeat-expansion disorders.* QMetrika Labs, 2026. Method covered by patent
+P202630522 (OEPM). Code under MIT.
+
+- Repo: https://github.com/josevilar-qbioai/energorna
+- ORCID: https://orcid.org/0009-0008-1057-4223

energorna-0.1.0/energorna/__init__.py

@@ -0,0 +1,23 @@
+"""energorna — glass-box local periodicity-loss observable for repeat-expansion disorders.
+
+Self-contained engine (numpy-only). Turner nearest-neighbor stacking parameters.
+The interruption that breaks the periodicity of the stacking profile Φ predicts age at
+onset better than counting repeats — validated across DM1, Huntington and SCA1.
+"""
+__version__ = "0.1.0"
+
+from .engine import (
+    stacking_profile,
+    calibrate_lag,
+    periodicity_loss,
+    periodicity_profile,
+    periodicity_loss_3prime,
+    n_interruptions,
+    fragmentation_index,
+    STACKING_TURNER,
+)
+
+__all__ = [
+    "stacking_profile", "calibrate_lag", "periodicity_loss", "periodicity_profile",
+    "periodicity_loss_3prime", "n_interruptions", "fragmentation_index", "STACKING_TURNER",
+]

energorna-0.1.0/energorna/cli.py

@@ -0,0 +1,88 @@
+"""
+energorna CLI — score the local periodicity loss of a repeat-expansion allele.
+
+Examples:
+    energorna score --seq CTGCTGCCGCTGCTG... --motif CTG
+    energorna score --seq-file allele.fasta --motif CAG --json
+    energorna score --repeat CTG --n 40 --json      # pure (CTG)40
+
+Numpy-only, glass-box. Prints periodicity_loss (the observable), its 3'-weighted
+variant, and the traditional count/fragmentation baselines for comparison.
+"""
+import argparse
+import json
+import re
+import sys
+
+from . import (periodicity_loss, periodicity_loss_3prime, periodicity_profile,
+               calibrate_lag, n_interruptions, fragmentation_index)
+
+
+def _read_seq(literal=None, path=None, repeat=None, n=None):
+    if repeat and n:
+        seq = repeat.upper() * int(n)
+    elif literal:
+        seq = literal
+    elif path:
+        seq = "".join(l.strip() for l in open(path) if not l.startswith(">"))
+    else:
+        return None
+    seq = re.sub(r"\s", "", seq).upper().replace("U", "T")
+    return seq if re.fullmatch(r"[ACGT]+", seq or "") else None
+
+
+def _longest_run(seq, motif):
+    units = [seq[i:i+len(motif)] for i in range(0, len(seq) - len(motif) + 1, len(motif))]
+    best = cur = 0
+    for u in units:
+        cur = cur + 1 if u == motif else 0
+        best = max(best, cur)
+    return best
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="energorna", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd")
+    s = sub.add_parser("score", help="score a repeat allele")
+    s.add_argument("--seq"); s.add_argument("--seq-file")
+    s.add_argument("--repeat"); s.add_argument("--n", type=int)
+    s.add_argument("--motif", default="CTG", help="repeat unit (default CTG)")
+    s.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    if args.cmd != "score":
+        ap.print_help(); return 1
+
+    seq = _read_seq(args.seq, args.seq_file, args.repeat, args.n)
+    if not seq:
+        print("error: provide a valid nucleotide sequence via --seq / --seq-file / --repeat+--n",
+              file=sys.stderr)
+        return 2
+    motif = args.motif.upper().replace("U", "T")
+
+    out = {
+        "motif": motif,
+        "motif_period": calibrate_lag(motif),
+        "n_units": len(seq) // len(motif),
+        "longest_uninterrupted_run": _longest_run(seq, motif),
+        "n_interruptions": n_interruptions(seq, motif),
+        "periodicity_loss": round(periodicity_loss(seq, unit=motif), 6),
+        "periodicity_loss_3prime": round(periodicity_loss_3prime(seq, unit=motif), 6),
+        "fragmentation_index": round(fragmentation_index(seq, motif), 6),
+    }
+
+    if args.json:
+        print(json.dumps(out, indent=2))
+    else:
+        print(f"motif {out['motif']} (period {out['motif_period']}) · "
+              f"{out['n_units']} units · longest uninterrupted run {out['longest_uninterrupted_run']}")
+        print(f"  periodicity_loss      = {out['periodicity_loss']:.4f}   <- observable")
+        print(f"  periodicity_loss (3') = {out['periodicity_loss_3prime']:.4f}")
+        print(f"  n_interruptions       = {out['n_interruptions']}   (count baseline)")
+        print(f"  fragmentation_index   = {out['fragmentation_index']:.4f}   (fragmentation baseline)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

energorna-0.1.0/energorna/engine.py

@@ -0,0 +1,118 @@
+"""
+energorna.engine — glass-box observable of local PERIODICITY LOSS in the nearest-neighbor
+stacking energy profile, for repeat-expansion disorders.
+
+Self-contained (numpy-only). No ViennaRNA / GPU / API / wet-lab. Every number is traceable.
+The central observable is the loss of autocorrelation (at lag = motif period) of the
+nearest-neighbor stacking free-energy profile (Turner RNA parameters).
+
+Public API:
+    stacking_profile(seq)                  -> per-position stacking profile Φ (kcal/mol)
+    calibrate_lag(unit)                    -> motif period (optimal ACF lag)
+    periodicity_loss(seq, unit|lag)        -> global scalar: 1 - ACF_period(Φ)
+    periodicity_profile(seq)               -> (relative_pos, local_loss) per window
+    periodicity_loss_3prime(seq)           -> 3'-weighted scalar
+    n_interruptions(seq, unit)             -> COUNT baseline (# interruptions)
+    fragmentation_index(seq, unit)         -> FRAGMENTATION baseline (1 - Σ run^α / n^α)
+
+Turner (RNA) nearest-neighbor stacking parameters; keys stored as DNA (T≡U).
+Source: Turner 2004 / NNDB.
+"""
+import numpy as np
+
+STACKING_TURNER = {
+    'AA': -0.93, 'AT': -1.10, 'AG': -2.08, 'AC': -2.24,
+    'TA': -1.33, 'TT': -0.93, 'TG': -2.35, 'TC': -2.11,
+    'GA': -2.35, 'GT': -2.24, 'GG': -3.26, 'GC': -3.42,
+    'CA': -2.11, 'CT': -2.08, 'CG': -2.36, 'CC': -3.26,
+}
+
+
+def stacking_profile(seq):
+    """Nearest-neighbor stacking energy profile (Turner), one value per position."""
+    s = seq.upper().replace('U', 'T')
+    n = len(s)
+    bonds = np.array([STACKING_TURNER.get(s[i:i+2], 0.0) for i in range(n - 1)])
+    prof = np.zeros(n)
+    if n == 1:
+        return prof
+    prof[0], prof[-1] = bonds[0], bonds[-1]
+    for i in range(1, n - 1):
+        prof[i] = (bonds[i-1] + bonds[i]) / 2
+    return prof
+
+
+def _acf(x, lag):
+    """Autocorrelation of x at a given lag."""
+    x = np.asarray(x, float)
+    if len(x) <= lag + 1 or x.std() == 0:
+        return 1.0
+    x = x - x.mean()
+    return float(np.corrcoef(x[:-lag], x[lag:])[0, 1])
+
+
+def calibrate_lag(unit, lo=2, hi=8):
+    """Motif period = lag (lo..hi) maximizing the ACF of the pure repeat.
+
+    Trinucleotides (CTG, CAG, CGG) -> 3; tetranucleotide (CCTG) -> 4.
+    """
+    prof = stacking_profile(unit * 40)
+    scores = {L: _acf(prof, L) for L in range(lo, hi + 1)}
+    return max(scores, key=lambda L: scores[L])
+
+
+def periodicity_loss(seq, unit=None, lag=None):
+    """Global scalar: 1 - ACF at lag=period. If `unit`, calibrate the lag; else lag=3."""
+    if lag is None:
+        lag = calibrate_lag(unit) if unit else 3
+    return 1 - _acf(stacking_profile(seq), lag)
+
+
+def periodicity_profile(seq, unit=None, lag=None, win=21, step=3):
+    """Position-resolved profile of the local periodicity loss.
+
+    Returns (pos, val): pos in [0,1] (0=5', 1=3'), val = 1 - ACF_period per window.
+    """
+    if lag is None:
+        lag = calibrate_lag(unit) if unit else 3
+    prof = stacking_profile(seq)
+    pos, val = [], []
+    for i in range(0, len(prof) - win, step):
+        pos.append((i + win / 2) / len(prof))
+        val.append(1 - _acf(prof[i:i+win], lag))
+    return np.array(pos), np.array(val)
+
+
+def periodicity_loss_3prime(seq, unit=None, lag=None, win=21, step=3):
+    """Periodicity loss weighted toward the 3' end (linear weight 0->1 from 5'->3')."""
+    pos, val = periodicity_profile(seq, unit, lag, win, step)
+    return float(np.average(val, weights=pos)) if len(pos) else 0.0
+
+
+# ── traditional baselines (for benchmarking) ──
+def _units(seq, k):
+    s = seq.upper().replace('U', 'T')
+    return [s[i:i+k] for i in range(0, len(s) - k + 1, k)]
+
+
+def n_interruptions(seq, unit='CTG'):
+    """Number of units that are NOT the pure motif (count baseline)."""
+    unit = unit.upper().replace('U', 'T')
+    return sum(1 for t in _units(seq, len(unit)) if t != unit)
+
+
+def fragmentation_index(seq, unit='CTG', alpha=1.6):
+    """1 - FI, where FI = Σ(perfect_run)^α / n^α (fragmentation baseline)."""
+    unit = unit.upper().replace('U', 'T')
+    trip = _units(seq, len(unit))
+    n = len(trip)
+    runs, cur = [], 0
+    for t in trip:
+        if t == unit:
+            cur += 1
+        elif cur:
+            runs.append(cur); cur = 0
+    if cur:
+        runs.append(cur)
+    fi = sum(r**alpha for r in runs) / (n**alpha) if n else 0.0
+    return 1 - fi

energorna-0.1.0/energorna.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: energorna
+Version: 0.1.0
+Summary: Glass-box local periodicity-loss observable of the mRNA stacking profile for repeat-expansion disorders (DM1, Huntington, SCA1)
+Author-email: Jose Antonio Vilar Sanchez <qmetrika@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/josevilar-qbioai/energorna
+Project-URL: Repository, https://github.com/josevilar-qbioai/energorna
+Project-URL: Issues, https://github.com/josevilar-qbioai/energorna/issues
+Keywords: repeat expansion,myotonic dystrophy,huntington,SCA1,trinucleotide,age at onset,mRNA,thermodynamics,interruptions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# energorna
+
+[![CI](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml/badge.svg)](https://github.com/josevilar-qbioai/energorna/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/energorna.svg)](https://pypi.org/project/energorna/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Glass-box local periodicity-loss observable of the mRNA stacking-energy profile, for
+repeat-expansion disorders.** Numpy-only, no ViennaRNA / GPU / API. Part of the QMetrika
+Bio-IA thermodynamic engine (same Turner nearest-neighbor parameters as `ef-synonymous`).
+
+*[English](#english) · [Español](#español)*
+
+---
+
+## English
+
+### The idea
+
+In repeat-expansion diseases (myotonic dystrophy type 1, Huntington, SCA1, DM2…), age at
+onset is not set only by *how many* repeats there are, but by whether the repeat tract is
+**interrupted**. Interruptions (e.g. CCG in the CTG tract of DM1, CAA in the CAG tract of
+Huntington, CAT in SCA1) break the **periodicity** of the nearest-neighbor stacking energy
+profile Φ, disrupt the slipped-strand substrate that drives somatic instability, and
+**delay onset**.
+
+`energorna` computes a single glass-box observable — `periodicity_loss = 1 − ACF_period(Φ)`,
+the loss of autocorrelation (at the motif period) of the Turner stacking profile — that
+captures this. It **auto-calibrates the period** per motif (3 for trinucleotides, 4 for the
+CCTG tetranucleotide) and, unlike simply counting interruptions, is sensitive to their
+**type** and **position**.
+
+### Install
+
+```bash
+pip install energorna
+```
+
+### Use — CLI
+
+```bash
+# pure (CTG)40 vs an interrupted allele
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file allele.fasta --motif CAG
+```
+
+Output shows the observable next to the traditional baselines:
+
+```
+motif CTG (period 3) · 62 units · longest uninterrupted run 51
+  periodicity_loss      = 0.18xx   <- observable
+  periodicity_loss (3') = 0.19xx
+  n_interruptions       = 4        (count baseline)
+  fragmentation_index   = 0.09xx   (fragmentation baseline)
+```
+
+### Use — Python
+
+```python
+import energorna as ef
+
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detects the motif period)
+ef.periodicity_loss(seq, unit="CTG")        # global observable
+ef.periodicity_profile(seq, unit="CTG")     # (pos, loss) resolved 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # 3'-weighted
+ef.n_interruptions(seq, "CTG")              # count baseline (to compare)
+```
+
+### Why it matters (validation)
+
+Across three diseases, `periodicity_loss` (or its axis, the longest uninterrupted stretch)
+predicts age at onset **better than counting repeats**:
+
+| Disease | Data | Result |
+|---|---|---|
+| **DM1** | Pešović 2018, n=7 | periodicity vs onset residual **r=+0.81** (LOO robust, bootstrap CI [+0.59,+0.99], perm p=0.027) vs count +0.53; captures type (CCG≫CTC) & position |
+| **Huntington** | GeM-HD 2019 (published directions) | LOI < canonical < duplication — matches onset ordering |
+| **SCA1** | Menon 2013 Table S3, n=35 | longest uninterrupted stretch predicts onset **R²=0.64** vs 0.24 for total size (r=−0.80, p=5×10⁻⁵) |
+
+### Honest scope
+
+A **biologically motivated correlate**, not proven causality. Individual, interruption-typed
+cohorts at scale (OPTIMISTIC, Enroll-HD) are access-controlled; the claim is "better
+predictor than count on the available data, with a mechanistic hypothesis and falsifiable
+predictions" (correlation with measured somatic instability, UV melting, MSH3 binding).
+Research use only.
+
+---
+
+## Español
+
+### La idea
+
+En enfermedades de expansión de repeticiones (distrofia miotónica tipo 1, Huntington,
+SCA1, DM2…), la edad de inicio no la fija solo *cuántas* repeticiones hay, sino si el
+tracto está **interrumpido**. Las interrupciones (p. ej. CCG en el tracto CTG de DM1, CAA
+en el CAG de Huntington, CAT en SCA1) rompen la **periodicidad** del perfil de energía de
+apilamiento nearest-neighbor Φ, alteran el sustrato slipped-strand que dirige la
+inestabilidad somática y **retrasan el inicio**.
+
+`energorna` calcula un único observable glass-box — `periodicity_loss = 1 − ACF_periodo(Φ)`,
+la pérdida de autocorrelación (al periodo del motivo) del perfil de apilamiento Turner —
+que lo captura. **Auto-calibra el periodo** por motivo (3 en trinucleótidos, 4 en el
+tetranucleótido CCTG) y, a diferencia de contar interrupciones, es sensible a su **tipo**
+y **posición**.
+
+### Instalación
+
+```bash
+pip install energorna
+```
+
+### Uso — CLI
+
+```bash
+energorna score --repeat CTG --n 40
+energorna score --seq CTGCTG...CCGCTG... --motif CTG --json
+energorna score --seq-file alelo.fasta --motif CAG
+```
+
+### Uso — Python
+
+```python
+import energorna as ef
+ef.calibrate_lag("CCTG")                    # -> 4 (auto-detecta el periodo)
+ef.periodicity_loss(seq, unit="CTG")        # observable global
+ef.periodicity_profile(seq, unit="CTG")     # perfil (pos, pérdida) 5'->3'
+ef.periodicity_loss_3prime(seq, unit="CTG") # ponderado 3'
+```
+
+### Por qué importa (validación)
+
+En tres enfermedades, `periodicity_loss` (o su eje, el tramo ininterrumpido más largo)
+predice la edad de inicio **mejor que contar repeticiones**: DM1 (Pešović n=7, r=+0,81),
+Huntington (direcciones publicadas, LOI<canónico<duplicación) y SCA1 (Menon 2013 n=35,
+R²=0,64 vs 0,24 del tamaño total). Ver la tabla en la sección en inglés.
+
+### Alcance honesto
+
+Es un **correlato biológicamente motivado**, no una causalidad demostrada. Los datos
+individuales tipados a escala son de acceso controlado; el claim es "mejor predictor que
+el conteo en los datos disponibles, con hipótesis mecanística y predicciones falsables".
+Uso solo para investigación (RUO).
+
+---
+
+### Citation / Cita
+
+Vilar Sánchez JA. *energoRNA: local periodicity loss of the mRNA stacking profile predicts
+age at onset in repeat-expansion disorders.* QMetrika Labs, 2026. Method covered by patent
+P202630522 (OEPM). Code under MIT.
+
+- Repo: https://github.com/josevilar-qbioai/energorna
+- ORCID: https://orcid.org/0009-0008-1057-4223

energorna-0.1.0/energorna.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+energorna/__init__.py
+energorna/cli.py
+energorna/engine.py
+energorna.egg-info/PKG-INFO
+energorna.egg-info/SOURCES.txt
+energorna.egg-info/dependency_links.txt
+energorna.egg-info/entry_points.txt
+energorna.egg-info/requires.txt
+energorna.egg-info/top_level.txt
+tests/test_ground_truth.py

energorna-0.1.0/energorna.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

energorna-0.1.0/energorna.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+energorna = energorna.cli:main

energorna-0.1.0/energorna.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.20

energorna-0.1.0/energorna.egg-info/top_level.txt

@@ -0,0 +1 @@
+energorna

energorna-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "energorna"
+version = "0.1.0"
+description = "Glass-box local periodicity-loss observable of the mRNA stacking profile for repeat-expansion disorders (DM1, Huntington, SCA1)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Jose Antonio Vilar Sanchez", email = "qmetrika@proton.me" }]
+keywords = ["repeat expansion", "myotonic dystrophy", "huntington", "SCA1", "trinucleotide", "age at onset", "mRNA", "thermodynamics", "interruptions"]
+dependencies = ["numpy>=1.20"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+[project.urls]
+Homepage = "https://github.com/josevilar-qbioai/energorna"
+Repository = "https://github.com/josevilar-qbioai/energorna"
+Issues = "https://github.com/josevilar-qbioai/energorna/issues"
+
+[project.scripts]
+energorna = "energorna.cli:main"
+
+[tool.setuptools]
+packages = ["energorna"]

energorna-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

energorna-0.1.0/tests/test_ground_truth.py

@@ -0,0 +1,68 @@
+"""
+Ground-truth tests for energorna. Values computed from the reference engine and
+reported in the manuscript / study (studies/energorna-dm1). numpy-only.
+"""
+import numpy as np
+import energorna as ef
+
+
+def test_calibrate_lag_period():
+    # ACF of the pure repeat peaks at the motif period
+    assert ef.calibrate_lag("CTG") == 3
+    assert ef.calibrate_lag("CAG") == 3
+    assert ef.calibrate_lag("CGG") == 3
+    assert ef.calibrate_lag("CCTG") == 4          # tetranucleotide (DM2)
+
+
+def test_periodicity_loss_pure_is_low():
+    assert abs(ef.periodicity_loss("CTG" * 40, unit="CTG") - 0.036937) < 1e-5
+
+
+def test_interruption_raises_loss():
+    pure = ef.periodicity_loss("CTG" * 60, unit="CTG")
+    intr = ef.periodicity_loss(_equispaced("CTG", "CCG", k=4), unit="CTG")
+    assert intr > pure + 0.1                       # an interruption breaks the pattern
+
+
+def test_huntington_ordering():
+    # LOI (uninterrupted) < canonical (1 CAA) < duplication (2 CAA) — matches onset direction
+    loi = ef.periodicity_loss("CAG" * 42, unit="CAG")
+    can = ef.periodicity_loss("CAG" * 40 + "CAACAG", unit="CAG")
+    dup = ef.periodicity_loss("CAG" * 38 + "CAACAGCAACAG", unit="CAG")
+    assert loi < can < dup
+    assert abs(loi - 0.036145) < 1e-5
+    assert abs(dup - 0.229976) < 1e-5
+
+
+def test_type_discrimination_ccg_gt_ctc():
+    # At fixed count/position, CCG (protective in DM1) disrupts Φ more than CTC
+    ccg = ef.periodicity_loss(_equispaced("CTG", "CCG", k=4), unit="CTG")
+    ctc = ef.periodicity_loss(_equispaced("CTG", "CTC", k=4), unit="CTG")
+    assert ccg > ctc
+    assert abs(ccg - 0.193759) < 1e-5
+
+
+def test_baselines():
+    seq = _equispaced("CTG", "CCG", k=4)
+    assert ef.n_interruptions(seq, "CTG") == 4
+    assert 0.0 < ef.fragmentation_index(seq, "CTG") < 1.0
+
+
+def test_profile_shape():
+    pos, val = ef.periodicity_profile("CTG" * 40 + "CCGCTG" * 4, unit="CTG")
+    assert len(pos) == len(val) and pos.min() >= 0 and pos.max() <= 1
+
+
+def _equispaced(motif, interr, k=4, n=60):
+    u = [motif] * n
+    for i in np.linspace(0, n - 1, k + 2).round().astype(int)[1:-1]:
+        u[int(i)] = interr
+    return "".join(u)
+
+
+if __name__ == "__main__":
+    for fn in [test_calibrate_lag_period, test_periodicity_loss_pure_is_low,
+               test_interruption_raises_loss, test_huntington_ordering,
+               test_type_discrimination_ccg_gt_ctc, test_baselines, test_profile_shape]:
+        fn(); print("ok:", fn.__name__)
+    print("ALL OK")