Metadata-Version: 2.4
Name: ogs-bio-tm
Version: 0.2.0
Summary: OGS-Bio-Tm: A Calibrated Dual-Frame Thermodynamic Engine and Python Library for Automated TaqMan Non-MGB Real-Time PCR Assay Design
Author: Tuan Minh Huynh
Author-email: Quan Tran Kim <quan.kim@aih.com.vn>
Maintainer-email: Quan Tran Kim <kimtranquan@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/kimtranquan/ogs-bio-tm
Project-URL: Repository, https://github.com/kimtranquan/ogs-bio-tm.git
Project-URL: Issues, https://github.com/kimtranquan/ogs-bio-tm/issues
Project-URL: Documentation, https://github.com/kimtranquan/ogs-bio-tm#readme
Keywords: bioinformatics,real-time-pcr,taqman,non-mgb-probe,melting-temperature,thermodynamics,nearest-neighbor,primer-express,assay-design
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# OGS-Bio-Tm (v0.2.0)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-brightgreen.svg)](https://www.python.org/)
[![Code Style: PEP8](https://img.shields.io/badge/code%20style-PEP8-orange.svg)](https://peps.python.org/pep-0008/)

**OGS-Bio-Tm** is an open-source, zero-dependency Python library providing a **Calibrated Dual-Frame Thermodynamic Engine** specifically engineered for high-throughput **TaqMan Non-MGB (Standard Dual-Labeled Hydrolysis Probe)** Real-Time PCR assay design and legacy protocol migration.

Developed as the core computational engine of the **Open Gen Solution (OGS)** bioinformatics platform at the **University of Medicine and Pharmacy at Ho Chi Minh City (UMP)**, `ogs-bio-tm v0.2.0` bridges the longstanding gap between legacy industry-standard commercial software (**Applied Biosystems Primer Express 3.0**) and modern empirical physical nucleic acid thermodynamics (**SantaLucia 1998** and **Owczarzy 2004/2008**).

---

## Key Architectural Innovations in v0.2.0

1. **Analytical De-obfuscation of Primer Express 3.0 (`mode="pe_legacy"`)**
   Rather than relying on black-box heuristics, `ogs-bio-tm` analytically resolves the exact mathematical identity linking the proprietary Primer Express 3.0 Non-MGB calculation engine to the classical Nearest-Neighbor formulation of **Breslauer et al. (1986)** and **Rychlik et al. (1990)**:
   - **Effective Entropy Offset:** `dS_const = -51.39 cal/(K*mol) = dS_init (-10.8) + R * ln(C_eff / 4)` at an effective reference strand concentration `C_eff = 5.39 nM`.
   - **Monovalent Salt Term:** `Salt_const = -21.7 °C = 16.6 * log10([Na+_eff])` at `[Na+_eff] = 49.3 mM`.
   - **IEEE-754 / Banker's Rounding Synchronization:** A calibrated Kelvin offset of `273.2 K` (`273.15 + 0.05 K`) paired with exact decimal round-half-to-even (`ROUND_HALF_EVEN`) achieves **0.00 °C Mean Absolute Error (MAE)** across thousands of Primer Express 3.0 reference primer and TaqMan Non-MGB probe designs.

2. **Empirical Physical Reference Frame (`mode="physical_nn"`)**
   Implements the unified Nearest-Neighbor parameters of **SantaLucia (1998)** coupled with the GC-dependent monovalent (`Na+`) and divalent (`Mg2+`, `dNTP` chelation) ion corrections of **Owczarzy et al. (2004, 2008)**, validated against UV-melting gold-standard duplex datasets.

3. **Smooth Sigmoid Length Transition (`length_mode="smooth_transition"`)**
   Eliminates the artificial step discontinuity at the `50 bp` boundary between oligonucleotide Nearest-Neighbor modeling and macroscopic amplicon `%GC` modeling via a continuous logistic interpolation across the `45-60 bp` transition window.

4. **Strict Input Validation & IUPAC Degenerate Base Resolution**
   Enforces deterministic `ValueError` exception handling for malformed or non-DNA sequences while optionally supporting thermodynamic averaging across all 15 IUPAC nucleotide codes (`allow_iupac=True`).

---

## Installation

Install from PyPI:

```bash
pip install ogs-bio-tm
```

Or install directly from the source repository for development and unit testing:

```bash
git clone https://github.com/kimtranquan/ogs-bio-tm.git
cd ogs-bio-tm
pip install -e ".[dev]"
pytest
```

---

## Quick Start Usage

### 1. Dual-Frame Melting Temperature (Tm) Calculation

```python
from ogs_bio_tm.calculator import PrimerExpressNonMGB

calc = PrimerExpressNonMGB()

# TaqMan Non-MGB Probe (28 bp) targeting Mycoplasma pneumoniae 23S rRNA
probe_seq = "ACCTCGATGTCGACTCATCTCATCCTCG"

# Frame 1: Exact Primer Express 3.0 Legacy Compatibility (69.1 °C -> 69 °C in PE table)
tm_pe = calc.calculate_tm(probe_seq, mode="pe_legacy")
print(f"PE 3.0 Legacy Tm: {tm_pe} °C")

# Frame 2: Physical Nearest-Neighbor (SantaLucia 1998 + Owczarzy 2008 Mg2+/dNTP correction)
tm_phys = calc.calculate_tm(
    probe_seq,
    conc_oligo_nm=250.0,
    conc_na_mm=50.0,
    conc_mg_mm=3.0,
    conc_dntp_mm=0.8,
    mode="physical_nn",
)
print(f"Physical Empirical Tm: {tm_phys} °C")
```

### 2. Smooth Sigmoid Transition Across the 45-60 bp Window

```python
long_oligo = "CAGGCTGATACTGCCCAAGAGTTCATATCGTTTGGCACCTCGATGTCGACTCAT"  # 54 bp

res_smooth = calc.evaluate_sequence(
    long_oligo,
    mode="physical_nn",
    length_mode="smooth_transition",
)
print(f"Length: {res_smooth.length} bp | Regime: {res_smooth.length_regime}")
print(f"Sigmoid Weight (alpha): {res_smooth.transition_weight_alpha} | Tm: {res_smooth.tm_celsius} °C")
```

### 3. Automated TaqMan Non-MGB Trio Quality Control

```python
trio_report = calc.design_taqman_non_mgb_trio(
    fwd_seq="AGAGTTCATATCGACGGCAGTGT",
    rev_seq="GCCGAACCCTTCGAACCT",
    probe_seq="ACCTCGATGTCGACTCATCTCATCCTCG",
)
print(trio_report)
```

---

## Citation

If you use `ogs-bio-tm` in your research or diagnostic assay design pipeline, please cite:

> Kim, Q.T.; Huynh, T.M. OGS-Bio-Tm v0.2.0: A Calibrated Dual-Frame Thermodynamic Engine for Automated TaqMan Non-MGB Assay Design. *Biology* **2026**, *Submitted*.

---

## License

This project is licensed under the **MIT License**.
