Metadata-Version: 2.5
Name: pepkio-ligation-insert-ratio-calculator
Version: 0.1.0
Summary: Python client for Pepkio ligation-insert-ratio-calculator tool
Requires-Python: >=3.11
Requires-Dist: click>=8.4.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Pepkio Ligation Insert Ratio Calculator

Execute DNA ligation insert-to-vector molar ratio calculations, required insert mass conversions, and master mix volume formulations with overage via the Pepkio REST API from Python.

# What It Does

Optimizing DNA insert-to-vector molar ratios is critical for successful molecular cloning and T4 DNA ligase reactions. Manual molar calculations, mixed base-pair length units, and uncounted dead volumes in viscous glycerol buffer often cause cloning failures or pipetting shortfalls.

This package submits vector backbone specifications, insert fragment parameters, target molar ratios (such as 3:1, 5:1, or 10:1), and buffer preferences to the Pepkio Tools calculation engine. It computes required insert mass (in ng), precise pipetting volumes (in µL), total reaction master mix component breakdowns, and warnings for volume overfill or glycerol toxicity.

Programmatic runs require an active network connection and a Pepkio API key. Computations are processed via the remote API.

# Features

- **Stoichiometric Calculations**: Computes required insert DNA mass (ng) from vector length (bp/kb), insert length (bp/kb), vector mass, and target molar ratio.
- **Flexible Calculation Modes**: Supports fixed vector mass mode, insert-limited mode (maximizing vector mass based on available insert), and multi-insert batch processing.
- **Sticky & Blunt-End Presets**: Preset ratio recommendations tailored to cohesive/sticky ends (3:1 to 5:1) and blunt ends (5:1 to 10:1).
- **Master Mix & Buffer Recipes**: Calculates component volumes for DNA, 10X T4 DNA ligase buffer (10% reaction volume), ligase enzyme, and nuclease-free water.
- **Pipetting Overage Accounting**: Integrates volume overage options (+10% or +1 reaction equivalent) to prevent liquid shortfalls from viscous ligase storage buffers.
- **Validation & QC Warnings**: Automatically checks for reaction volume overspill, suboptimal molar ratios (<1:1 or >10:1), glycerol concentration limits (>5% v/v), and low DNA inputs.
- **CLI & Python API**: Includes synchronous Python bindings (`PepkioClient`) and a command-line interface (`pepkio-ligation-insert-ratio-calculator`).

# Installation

```bash
pip install pepkio-ligation-insert-ratio-calculator
```

Set a Pepkio API key with `tools:run` scope as an environment variable:

```bash
export PEPKIO_API_KEY="your-api-key"
```

Keys can be generated in your [Pepkio API key settings](https://www.pepkio.com/account/api-keys).

# Quick Example

```python
from pepkio_ligation_insert_ratio_calculator import PepkioClient

with PepkioClient() as client:
    # 3:1 sticky-end ligation of a 1.2 kb insert into a 5.0 kb vector backbone
    ligation_input = {
        "ligation_type": "sticky_end",
        "calc_mode": "fixed_vector_mass",
        "vector_size": 5000,
        "vector_size_unit": "bp",
        "vector_concentration": 50,
        "vector_conc_unit": "ng_uL",
        "vector_mass": 50,
        "vector_mass_unit": "ng",
        "reaction_volume_ul": 20,
        "ligase_volume_ul": 1,
        "buffer_fraction": 0.1,
        "overage_mode": "percent_10",
        "inserts": [
            {
                "id": "ins1",
                "name": "GFP_Amplicon",
                "size": 1200,
                "size_unit": "bp",
                "concentration": 25,
                "conc_unit": "ng_uL",
                "molar_ratio": 3,
            }
        ],
    }

    result = client.run(ligation_input)

    if result.result:
        for row in result.result.get("rows", []):
            print(f"Insert: {row['name']}")
            print(f"Required Mass: {row['insert_mass_ng']} ng")
            print(f"Insert Volume: {row['insert_volume_ul']} µL")
            print(f"Water Volume: {row['water_volume_ul']} µL")

        mm = result.result.get("master_mix", {})
        print(f"Master Mix Total Volume: {mm.get('total_master_mix_vol_ul')} µL")
```

Command-Line Interface (CLI):

```bash
# List example inputs from manifest
pepkio-ligation-insert-ratio-calculator manifest --examples

# Run predefined example
pepkio-ligation-insert-ratio-calculator run --example sticky_3to1_batch
```

# Typical Use Cases

- **Standard Restriction-Ligation Subcloning**: Calculate exact insert mass and microliters needed for sticky-end ligations at a 3:1 molar ratio into linearized vector backbones.
- **Blunt-End Ligation Optimization**: Set higher insert-to-vector molar ratios (5:1 to 10:1) for blunt restriction fragments or proofreading PCR amplicons.
- **Insert-Limited Reaction Design**: Determine maximum permissible vector backbone mass when insert DNA yield is low or hard to isolate.
- **Multi-Fragment Ligation Setup**: Balance stoichiometry across multiple insert fragments simultaneously to ensure equal molar representation.
- **Cloning Master Mix Preparation**: Formulate pooled reaction mixtures with +10% dead-volume overage for multi-sample pipetting or 96-well plate cloning workflows.

# Scientific Background

T4 DNA ligase catalyzes phosphodiester bond formation between 5'-phosphate and 3'-hydroxyl DNA ends. The fundamental equation relating insert mass to vector mass based on molar stoichiometry is:

$$\text{Insert Mass (ng)} = \text{Vector Mass (ng)} \times \left(\frac{\text{Insert Length (bp)}}{\text{Vector Length (bp)}}\right) \times \text{Molar Ratio}$$

Because cohesive (sticky) ends feature complementary single-stranded overhangs that temporarily anneal via hydrogen bonding, lower molar ratios (3:1 to 5:1) are effective. Blunt ends lack overhang stabilization, requiring higher molar ratios (5:1 to 10:1) and elevated enzyme concentrations to promote intermolecular ligation over vector recircularization.

Commercial ligase is stored in 50% (v/v) glycerol buffer. Glycerol concentrations above 5% (v/v) in the final ligation reaction inhibit ligase activity and induce star activity during restriction-ligation protocols.

# Web Application

For researchers who prefer a graphical interface, an interactive web version is available.

Web Application: https://www.pepkio.com/tools/ligation-insert-ratio-calculator

The web application includes real-time ratio sliders, visual component volume breakdowns, exportable bench worksheets (PDF/CSV), and persistent shareable permalinks for electronic lab notebooks.

# Documentation and Resources

GitHub Repository: https://github.com/pepkio/pepkio-ligation-insert-ratio-calculator

Web Application: https://www.pepkio.com/tools/ligation-insert-ratio-calculator

# About Pepkio

Pepkio (https://www.pepkio.com/) develops software tools and bioinformatics solutions for life science researchers, including laboratory calculators and analysis services (https://www.pepkio.com/cro).

# Keywords

ligation insert ratio calculator, DNA ligation molar ratio, insert to vector ratio, T4 DNA ligase calculator, plasmid ligation calculator, insert mass calculator, molecular cloning stoichiometry, sticky end ligation, blunt end ligation, vector insert ratio, DNA molarity calculator, ligation master mix, molar ratio cloning, T4 ligase buffer volume, 10X ligase buffer, ligation reaction setup, plasmid backbone ratio, recombinant DNA cloning, insert volume calculator, vector mass calculator, insert limited ligation, restriction subcloning, dead volume overage, glycerol concentration threshold, picomole DNA calculator, calculate insert mass from vector mass and length, DNA ligation molar ratio formula, sticky end vs blunt end ligation ratio, how to calculate T4 DNA ligase reaction master mix, insert to vector ratio for 3 to 1 cloning, calculate DNA volume for ligation reaction, prevent vector self ligation background, ligation master mix calculation with dead volume, multi insert ligation stoichiometry calculator, insert limited ligation vector mass calculation, DNA concentration ng per ul to picomole converter, glycerol toxicity limit T4 DNA ligase, dephosphorylated vector ligation ratio calculation, Python package for ligation insert ratio, CLI tool for DNA ligation calculations, REST API for molecular cloning calculators, electronic lab notebook ligation protocol permalink
