biolabcalc 0.2.0__tar.gz

biolabcalc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioLabCalc Contributors
+
+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.

biolabcalc-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src/biolabcalc *.py *.html
+recursive-include tests *.py

biolabcalc-0.2.0/PKG-INFO

@@ -0,0 +1,610 @@
+Metadata-Version: 2.4
+Name: biolabcalc
+Version: 0.2.0
+Summary: A multifaceted Python library and Excel extension for daily molecular biology research, PCR stoichiometry, IVT yields, protein quantification, and primer design.
+Author: BioLabCalc Contributors
+License: MIT License
+        
+        Copyright (c) 2026 BioLabCalc Contributors
+        
+        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.
+        
+Keywords: bioinformatics,molecular-biology,pcr,transcription,in-vitro-transcription,primer-design,protein-quantification,excel,openpyxl,stoichiometry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: Pillow>=9.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# BioLabCalc 🧬🔬
+
+[![CI](https://github.com/your-username/biolabcalc/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/biolabcalc/actions)
+[![Python Version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/biolabcalc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+> A multifaceted Python library and built-in Excel extension for daily wet-lab molecular biology calculations, reaction optimization, in vitro transcription stoichiometry, PCR kinetics, protein quantification, thermodynamic primer design, fluorophore modifications, gel migration ladders, standardized solution recipes, and *E. coli* growth modeling.
+
+---
+
+## 📖 Table of Contents
+
+- [Overview](#-overview)
+- [Key Features](#-key-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Modules & API Reference](#-core-modules--api-reference)
+  - [1. Standardized Solution Prep & NanoDrop Predictor (`spectroscopy`)](#1-standardized-solution-prep--nanodrop-predictor)
+  - [2. Fluorophore Modifications & Degree of Labeling (`fluorescence`)](#2-fluorophore-modifications--degree-of-labeling-dol)
+  - [3. Gel Migration & Molecular Weight Ladders (`gels`)](#3-gel-migration--molecular-weight-ladders)
+  - [4. E. coli Growth & Plasmid/Protein Yields (`ecoli_growth`)](#4-e-coli-growth-kinetics--expression-optimization)
+  - [5. PCR Kinetics, Optimization & Master Mix (`pcr`)](#5-pcr-kinetics--protocol-optimization)
+  - [6. In Vitro Transcription Stoichiometry (`transcription`)](#6-in-vitro-transcription-ivt-stoichiometry)
+  - [7. Molecular Weight & Conversions (`molecular_weight`)](#7-molecular-weight--stoichiometry)
+  - [8. Protein Quantification (`protein`)](#8-protein-quantification--yield-analysis)
+  - [9. Primer Design & SantaLucia Thermodynamics (`primers`)](#9-primer-creator--thermodynamics)
+  - [10. Interactive Drag-and-Drop Gel Annotator & MW Calculator (`interactive_gel`)](#10-interactive-drag-and-drop-gel-annotator--mw-calculator)
+  - [11. Gel Labeling Add-on & Image Annotator (`gel_annotator`)](#11-gel-labeling-add-on--image-annotator)
+  - [12. Molecular Cloning, Digestion & Assembly (`cloning`)](#12-molecular-cloning-digestion--assembly)
+  - [13. Laboratory Buffer & Stock Recipes (`buffers`)](#13-laboratory-buffer--stock-recipes)
+  - [14. Nucleic Acid Precipitation & Desalting (`precipitation`)](#14-nucleic-acid-precipitation--desalting)
+  - [15. Built-in Excel Extension (`excel_extension`)](#15-built-in-excel-extension)
+  - [16. Standard Laboratory Protocols Compendium (`protocols`)](#16-standard-laboratory-protocols-compendium-protocols)
+- [Command-Line Interface (CLI)](#-command-line-interface-cli)
+- [Interactive Excel Workbook Structure](#-interactive-excel-workbook-structure)
+- [Scientific Formulations](#-scientific-formulations)
+- [Running Tests](#-running-tests)
+- [Legal & Compliance Notice](#-legal--compliance-notice)
+- [License](#-license)
+
+---
+
+## 🌟 Overview
+
+Bench biologists and bioinformaticians constantly encounter repetitive yet critical quantitative tasks:
+* **Preparing standardized solutions** (e.g., *"How do I make 4 µM ssRNA in 500 µL, and what exact ng/µL concentration and A260 absorbance should I see on the NanoDrop?"*).
+* **Fluorophore labeling & modifications** (mass shifts, spectral parameters, and Degree of Labeling [DOL] efficiency for FAM, Cy3, Cy5, Alexa Fluor, ATTO dyes, and quenchers).
+* **Gel electrophoresis simulation & ladder alignment** (mapping DNA/protein band sizes to 1 kb, 100 bp, or prestained protein ladders and calculating relative migration distances $R_f$).
+* **E. coli expression scheduling & yield prediction** (calculating doubling times, hours from inoculation to induction OD₆₀₀, and theoretical plasmid or recombinant protein yields).
+* **Reaction optimization & troubleshooting** (evaluating in vitro transcription NTP consumption, PCR dNTP limits, touchdown profiles, and Pace et al. $A_{280}$ extinction coefficients).
+
+**BioLabCalc** combines a clean Python scientific API, an instant terminal CLI tool, and a built-in Excel extension (`openpyxl`) that generates publication-grade, interactive laboratory notebooks containing live formulas.
+
+---
+
+## 🚀 Key Features
+
+<<<<<<< HEAD
+* **Standardized Solution & NanoDrop Predictor**: Computes required mass (µg, ng) and moles (nmol, pmol) for target solutions (e.g., 4 µM in 500 µL), generates pipetting dilution recipes, and predicts exact NanoDrop readings ($A_{260}$, $A_{260}/A_{280}$, and ng/µL).
+* **Fluorophore Modification & Degree of Labeling (DOL)**: Database of fluorophores (FAM, Cy3, Cy5, Alexa Fluor 488/546/594/647, Texas Red, TAMRA, ROX, ATTO 488/647N, BHQ quenchers) with exact MW additions, correction factors ($CF_{260}$, $CF_{280}$), and dye-to-biomolecule DOL calculations.
+* **Gel Migration & Ladder Simulation**: Simulates band positions for 1 kb DNA, 100 bp DNA, low-range oligo, and prestained protein ladders using logarithmic relative mobility ($R_f = a - b \cdot \log_{10}(\text{size})$) with ASCII lane diagrams.
+* **E. coli Growth & Yield Modeling**: Computes doubling times across LB, 2xYT, TB, and M9 media at 18–37°C, projects hours to reach induction OD₆₀₀ (0.6–0.8), and predicts theoretical plasmid DNA yields (pUC, pET, pBR322) and recombinant protein yields.
+=======
+* **Standardized Solution & NanoDrop Predictor**: Computes required mass (µg, ng) and moles (nmol, pmol) for target solutions (e.g., $4\,\mu	ext{M}$ in $500\,\mu	ext{L}$), generates pipetting dilution recipes, and predicts exact NanoDrop readings ($A_{260}$, $A_{260}/A_{280}$, and $ext{ng}/\mu ext{L}$).
+* **Fluorophore Modification & Degree of Labeling (DOL)**: Database of fluorophores (FAM, Cy3, Cy5, Alexa Fluor 488/546/594/647, Texas Red, TAMRA, ROX, ATTO 488/647N, BHQ quenchers) with exact MW additions, correction factors ($CF_{260}, CF_{280}$), and dye-to-biomolecule DOL calculations.
+* **Gel Migration & Ladder Simulation**: Simulates band positions for 1 kb DNA, 100 bp DNA, low-range oligo, and prestained protein ladders using logarithmic relative mobility \(R_f = a - b \log_{10}(\text{size})\) with ASCII lane diagrams.
+* **E. coli Growth & Yield Modeling**: Computes doubling times across LB, 2xYT, TB, and M9 media at 18–37°C, projects hours to reach induction $OD_{600}$ (0.6–0.8), and predicts theoretical plasmid DNA yields (pUC, pET, pBR322) and recombinant protein yields.
+>>>>>>> f7f5ae9e04728df3fb69686c2540d31b317c5da6
+* **PCR Protocol Optimization**: Computes polymerase-specific annealing temperatures ($T_a$), elongation times (Taq vs. Q5/Phusion vs. Kapa), generates touchdown PCR schedules, and suggests GC enhancers (DMSO, Betaine) for difficult templates.
+* **IVT Stoichiometry**: Tracks per-NTP usage, residual concentrations, incorporation efficiency, inorganic pyrophosphate ($PP_i$) precipitation risks, and transcript turnover ratios.
+* **Exact Molecular Weights**: Sequence-level average and monoisotopic weights for ssDNA, dsDNA, circular plasmids, RNA (5'-ppp, 5'-P, 5'-OH), and polypeptides.
+* **Built-in Excel Extension**: Generates formatted, 7-tab interactive workbooks (`.xlsx`) with live formulas for lab bench use.
+
+---
+
+## 📦 Installation
+
+### From PyPI (Recommended)
+```bash
+pip install biolabcalc
+```
+
+### From GitHub (Source / Development)
+```bash
+git clone https://github.com/your-username/biolabcalc.git
+cd biolabcalc
+pip install -e ".[dev]"
+```
+
+---
+
+## ⚡ Quick Start
+
+### ⏱️ 5-Minute Benchtop Cookbook (Everyday Lab Calculations)
+
+BioLabCalc answers everyday wet-lab calculations via the command line, Python API, or the interactive wizard:
+
+| Daily Laboratory Task | CLI Command / Python Code | Expected Output / Result |
+| :--- | :--- | :--- |
+| **Dilute Stock Solution** | `biolabcalc dilute -c1 "100 mM" -c2 "25 mM" -v2 "16 mL"` | Pipette 4.0 mL stock + 12.0 mL diluent |
+| **Neutralize 100 mM NTPs (pH 7.5)** | `biolabcalc ntp-ph -v 4.0 -c 100 -V 16 -C 25 -f disodium_salt` | Add 108.5 µL of 5 M NaOH, QS to 16 mL |
+| **Scale 10X PBS Recipe (500 mL)** | `biolabcalc buffer -b 10X_PBS -v 500` | 40.0 g NaCl, 1.0 g KCl, 7.2 g Na2HPO4, 1.2 g KH2PO4 |
+| **Plan EcoRI + BamHI Double Digest** | `biolabcalc digest -m 1.0 -v 50 -e1 EcoRI -e2 BamHI -c 200` | 5 µL 10X rCutSmart, 5 µL DNA, 1 µL each enzyme, 38 µL water |
+| **Check Overhang Compatibility** | `python -c "import biolabcalc as blc; print(blc.are_overhangs_compatible("BamHI", "BglII"))"` | Compatible cohesive ends (GATC) |
+| **Precipitate Low-Yield RNA** | `biolabcalc precipitate -v 100 -t rna -a ethanol -s naoac` | Add 10 µL 3M NaOAc, 1 µL GlycoBlue, 300 µL 100% EtOH |
+| **Interactive Guided Wizard** | `biolabcalc wizard` | Step-by-step prompted menu for bench calculations |
+| **View Standard Wet-Lab Protocol** | `biolabcalc protocol -n t7_ivt_transcription` | Complete bench protocol with safety, tables, and troubleshooting |
+
+```python
+import biolabcalc.easy as easy
+
+# 1. Quick C1*V1 = C2*V2 dilution
+res = easy.dilute(c1="100 mM", c2="25 mM", v2="16 mL")
+print(f"Pipette {res[v1]/1000} mL stock + {res[diluent_needed]/1000} mL water")
+
+# 2. Scale 10X PBS buffer to 500 mL
+pbs = easy.buffer("10X_PBS", volume="500 mL")
+
+# 3. Quick primer check
+p_info = easy.primer("ATGCCGTCCAGGCTGCTG", primer_conc="400 nM")
+print(f"Tm: {p_info.tm_celsius}°C, GC: {p_info.gc_percent}%")
+```
+
+
+```python
+import biolabcalc as blc
+
+# 1. Standardized Solution & NanoDrop Predictor: 4 µM ssRNA in 500 µL
+sol = blc.prepare_standard_solution(
+    target_molarity_um=4.0,
+    target_volume_ul=500.0,
+    seq_type="rna",
+    rna_length_nt=36,
+)
+print(f"Required Mass: {sol.required_mass_ug:.2f} µg ({sol.required_moles_nmol:.2f} nmol)")
+print(f"NanoDrop Expected Conc: {sol.expected_nanodrop_ng_ul:.2f} ng/µL")
+print(f"NanoDrop Expected A260: {sol.expected_nanodrop_a260_1cm:.3f} AU (A260/A280 ~ {sol.expected_a260_a280_ratio})")
+
+# 2. Fluorophore Modification & Degree of Labeling (DOL)
+dna = blc.calculate_dna_mw("ATGCCGTCCAGGCTGCTGGTC")
+labeled = blc.apply_fluorophore_modification(dna, ["FAM"])
+print(f"FAM-labeled DNA MW: {labeled.total_modified_mw:,.2f} Da (+{labeled.total_added_mw} Da)")
+
+dol = blc.calculate_degree_of_labeling(
+    absorbance_max_dye=0.75,
+    absorbance_280=1.10,
+    fluorophore_name="FAM",
+    protein_extinction_coeff=45000,
+)
+print(f"Degree of Labeling: {dol.degree_of_labeling:.2f} ({dol.interpretation})")
+
+# 3. Gel Electrophoresis Migration Simulation
+sim = blc.simulate_gel([750, 2200, 4500], ladder_key="1kb_dna")
+print(sim.ascii_visualization)
+
+# 4. E. coli Growth & Induction Scheduling
+growth = blc.calculate_ecoli_growth(initial_od600=0.05, target_od600=0.65, temperature_celsius=37.0, media="LB")
+print(f"Time to Induction OD: {growth.formatted_time} ({growth.num_doublings} doublings)")
+
+# 5. Generate Multi-Tab Interactive Excel Lab Notebook
+blc.generate_lab_notebook_template("BioLab_Interactive_Notebook.xlsx")
+```
+
+---
+
+## 🔬 Core Modules & API Reference
+
+### 1. Standardized Solution Prep & NanoDrop Predictor
+```python
+from biolabcalc.spectroscopy import prepare_standard_solution
+
+res = prepare_standard_solution(
+    target_molarity_um=4.0,
+    target_volume_ul=500.0,
+    seq_type="rna",
+    rna_length_nt=36,
+    stock_conc_ng_ul=500.0,  # Optional: provides pipetting dilution recipe
+)
+```
+**Output Highlights:**
+<<<<<<< HEAD
+- `required_mass_ug`: Total mass needed: 23.02 µg.
+- `required_moles_nmol`: Total moles: 2.000 nmol.
+- `expected_nanodrop_ng_ul`: Target concentration reading: 46.03 ng/µL.
+- `expected_nanodrop_a260_1cm`: Normalized $A_{260}$ reading: 1.151 AU.
+- `expected_nanodrop_a260_1mm`: Physical pedestal reading: 0.1151 AU.
+=======
+- `required_mass_ug`: Total mass needed ($23.02\,\mu	ext{g}$).
+- `required_moles_nmol`: Total moles ($2.000	ext{ nmol}$).
+- `expected_nanodrop_ng_ul`: Target concentration reading (\(46.03\,\text{ng}/\mu\text{L}\)).
+- `expected_nanodrop_a260_1cm`: Normalized \(A_{260}\) reading (\(1.151\,\text{AU}\)).
+- `expected_nanodrop_a260_1mm`: Physical pedestal reading (\(0.1151\,\text{AU}\)).
+>>>>>>> f7f5ae9e04728df3fb69686c2540d31b317c5da6
+- `preparation_instructions`: Exact pipetting instructions for bench technicians.
+
+### 2. Fluorophore Modifications & Degree of Labeling (DOL)
+```python
+from biolabcalc.fluorescence import apply_fluorophore_modification, calculate_degree_of_labeling
+
+# Add fluorophores/quenchers to DNA, RNA, or protein
+mod_res = apply_fluorophore_modification(base_dna_mw, ["FAM", "BHQ1"])
+
+# Quantify labeling efficiency from spectrophotometer readings
+dol = calculate_degree_of_labeling(
+    absorbance_max_dye=0.65,
+    absorbance_260=1.25,
+    fluorophore_name="FAM",
+    oligo_extinction_coeff=360000,
+)
+```
+
+### 3. Gel Migration & Molecular Weight Ladders
+```python
+from biolabcalc.gels import simulate_gel
+
+# LADDER OPTIONS: "1kb_dna", "100bp_dna", "low_range_ssdna", "protein_broad_range"
+sim = simulate_gel(sample_sizes=[450, 1200, 3000], ladder_key="1kb_dna")
+print(sim.ascii_visualization)
+```
+
+### 4. E. coli Growth Kinetics & Expression Optimization
+```python
+from biolabcalc.ecoli_growth import calculate_ecoli_growth, estimate_plasmid_yield, optimize_protein_induction
+
+# Time to induction OD600
+growth = calculate_ecoli_growth(initial_od600=0.05, target_od600=0.65, temperature_celsius=37.0, media="LB")
+
+# Estimate plasmid prep yield from culture
+plasmid = estimate_plasmid_yield(culture_volume_ml=5.0, final_od600=3.0, plasmid_type="pUC")
+
+# Recombinant protein yield and induction condition advisor
+prot = optimize_protein_induction(protein_mw_da=45000, culture_volume_ml=1000.0, final_od600=4.0)
+```
+
+### 5. PCR Kinetics & Protocol Optimization
+```python
+from biolabcalc.pcr import calculate_pcr_kinetics, optimize_pcr_protocol, build_master_mix
+
+# Protocol optimization: annealing temp, extension time, touchdown schedule, additives
+protocol = optimize_pcr_protocol(primer_fwd_tm=60.5, primer_rev_tm=60.0, amplicon_len_bp=800, polymerase="q5")
+
+# Master mix pipetting table for N samples with 10% excess
+master_mix = build_master_mix(num_reactions=24, excess_percent=10.0)
+```
+
+---
+
+### 16. Standard Laboratory Protocols Compendium (`protocols`)
+
+BioLabCalc includes a built-in catalog of 10 fully verified, easy-to-understand wet-lab molecular biology and biochemistry protocols. Each protocol provides comprehensive reagent formulation tables, materials lists, safety warnings, pro tips, time/temperature parameters, troubleshooting matrices, and literature citations. The complete consolidated manual is compiled in [`PROTOCOLS.md`](PROTOCOLS.md).
+
+#### Built-in Protocols:
+1. **`ntp_neutralization`**: 25 mM Neutralized NTP Mix Preparation (pH 7.5) with NaOH titration and logic checks.
+2. **`t7_ivt_transcription`**: High-Yield T7 In Vitro Transcription of RNA with DNase I degradation.
+3. **`ecoli_transformation`**: Heat-Shock Transformation of Chemically Competent *E. coli* (DH5α / BL21).
+4. **`alkaline_lysis_miniprep`**: Alkaline Lysis Plasmid DNA Miniprep with silica spin column binding.
+5. **`agarose_gel_electrophoresis`**: Submarine Agarose Gel Casting, Loading, and Imaging for DNA/RNA.
+6. **`denaturing_urea_page`**: 7–8 M Urea-PAGE for Single-Nucleotide Resolution of Small RNAs and Aptamers.
+7. **`ethanol_precipitation`**: Ethanol & Isopropanol Nucleic Acid Precipitation and Desalting.
+8. **`gibson_assembly`**: Gibson Isothermal Assembly for 2–3 Overlapping DNA Fragments.
+9. **`restriction_double_digest`**: Restriction Endonuclease Double Digest with rSAP Dephosphorylation.
+10. **`bradford_protein_assay`**: Bradford / BCA Colorimetric Protein Assay with BSA Standard Curve.
+
+#### Python API:
+```python
+from biolabcalc.protocols import list_protocols, get_protocol, export_all_protocols_markdown
+
+# List all protocols or filter by category
+protocols = list_protocols(category="RNA")
+
+# Inspect a specific protocol
+proto = get_protocol("t7_ivt_transcription")
+print(f"{proto.title}: {proto.estimated_time}")
+
+# Export consolidated markdown manual
+export_all_protocols_markdown("PROTOCOLS.md")
+```
+
+#### CLI:
+```bash
+# List all protocols in the catalog
+biolabcalc protocol --list
+
+# Filter by category (e.g. RNA, Cloning, Electrophoresis)
+biolabcalc protocol --category RNA
+
+# Display full step-by-step instructions at the terminal
+biolabcalc protocol -n ntp_neutralization
+
+# Export complete PROTOCOLS.md manual
+biolabcalc protocol --export PROTOCOLS.md
+```
+
+---
+
+## 💻 Command-Line Interface (CLI)
+
+```bash
+# NanoDrop & Standardized Solution (e.g. 4 uM ssRNA in 500 uL)
+biolabcalc nanodrop -u 4.0 -v 500 -t rna --length 36
+
+# Fluorophore modification & spectral info
+biolabcalc fluo -s ATGCCGTCCAGGCTGCTGGTC -d FAM
+
+# Gel electrophoresis ladder simulation
+biolabcalc gel -s 750 2200 4500 --ladder 1kb_dna
+
+# PCR protocol optimization
+biolabcalc pcr-opt --fwd-tm 60.5 --rev-tm 60.0 -l 800 -p q5 --gc 52.0
+
+# E. coli growth & plasmid yield
+biolabcalc ecoli --init-od 0.05 --target-od 0.65 --temp 37 --media LB --vol-ml 1000
+
+# Annotate gel images, label lanes, and callout molecular weights
+biolabcalc annotate-gel \
+    --lanes "Ladder,Ctrl,Clone1,Clone2,Digest" \
+    --ladder 1kb_dna \
+    --ladder-lane 1 \
+    --bands "3:850:Amplicon,4:850:Amplicon,5:3500:Vector" \
+    --title "Colony PCR Screening" \
+    --output "annotated_gel.png" \
+    --excel "Experiment_Report.xlsx"
+
+# Restriction enzyme digestion setup
+biolabcalc digest --dna-ug 2.0 -e1 EcoRI -e2 BamHI --dna-conc 250
+
+# DNA ligation molar ratio calculator (3:1 insert:vector)
+biolabcalc ligate --vec-bp 4500 --ins-bp 1200 --vec-ng 50 --ratio 3.0
+
+# Gibson Assembly / NEBuilder HiFi calculator
+biolabcalc gibson --vec-bp 5000 --ins-bp 850 1500 --vec-ng 100
+
+# Buffer recipe calculator (500 mL of 50X TAE)
+biolabcalc buffer -b 50X_TAE -v 500
+
+# Ethanol precipitation of nucleic acids
+biolabcalc precipitate -v 100 -t dna -a ethanol -s naoac
+
+# Launch interactive drag-and-drop gel tool in web browser
+biolabcalc interactive-gel --port 8501
+
+# Save standalone HTML application to share with lab members
+biolabcalc interactive-gel --save-html "Interactive_Gel_Tool.html"
+
+# Generate full interactive Excel lab notebook
+biolabcalc excel-template -o "BioLab_Calculator.xlsx"
+```
+
+---
+
+## 📊 Interactive Excel Workbook Structure
+
+The generated workbook (`biolabcalc excel-template`) contains 7 specialized, styled sheets with live formulas:
+
+1. **`IVT_Stoichiometry`**: Live IVT yield, per-NTP consumption (ATP, CTP, GTP, UTP), residual concentrations, pyrophosphate byproduct, and transcript turnover.
+2. **`PCR_Optimization`**: Multi-sample master mix formulation table with dynamic excess multipliers and qPCR standard curve efficiency solver (`=10^(-1/slope)-1`).
+3. **`Protein_Quantification`**: Direct $A_{280}$ Beer-Lambert calculator and BCA/Bradford standard curve regression (`SLOPE()`, `INTERCEPT()`) with unknown sample interpolation.
+4. **`Primer_Design_Log`**: Formatted log for tracking primer names, sequences, $T_m$, GC%, 3' GC clamps, and amplicon lengths.
+5. **`Solution_Prep_NanoDrop`**: Input target molarity and volume; auto-calculates required mass/moles, stock dilution pipetting volumes, and predicted NanoDrop readings ($A_{260}$, $A_{260}/A_{280}$, $	ext{ng}/\mu	ext{L}$).
+6. **`Fluorophore_Modifications`**: Spectral property lookup and live Degree of Labeling (DOL) calculator.
+7. **`Ecoli_Growth_Optimization`**: Inoculation-to-induction timeline calculator, doubling time tables, and plasmid/recombinant protein yield projections.
+
+
+
+---
+
+<a name="scientific-formulations"></a>
+## 📐 Scientific Formulations
+
+BioLabCalc implements standardized, peer-reviewed mathematical models and biophysical equations:
+
+### 1. Beer-Lambert Law & NanoDrop Spectrophotometry
+Light absorbance across an optical pathlength is governed by the Beer-Lambert law:
+
+$$
+A = \epsilon \cdot c \cdot l
+$$
+
+Where:
+* $A$: Absorbance (dimensionless Absorbance Units, AU)
+* $\epsilon$: Molar extinction coefficient ($\text{L}\cdot\text{mol}^{-1}\cdot\text{cm}^{-1}$)
+* $c$: Molar concentration ($\text{mol}\cdot\text{L}^{-1}$)
+* $l$: Optical pathlength ($1.0\text{ cm}$ standard cuvette; $0.1\text{ cm} = 1.0\text{ mm}$ NanoDrop pedestal)
+
+The mass concentration $c_{\text{mass}}$ ($\text{ng}/\mu\text{L} \equiv \mu\text{g}/\text{mL}$) is calculated from absorbance normalized to a $1.0\text{ cm}$ pathlength:
+
+$$
+c_{\text{mass}} = \frac{A_{260} \cdot 10^6}{\epsilon_{260}} \cdot MW
+$$
+
+Standard empirical conversion constants for nucleic acids ($1.0\text{ AU}$ at $260\text{ nm}$ across a $1.0\text{ cm}$ pathlength):
+* **Double-stranded DNA (dsDNA)**: $50.0\text{ ng}/\mu\text{L}$ per $A_{260}$ unit
+* **Single-stranded RNA (ssRNA)**: $40.0\text{ ng}/\mu\text{L}$ per $A_{260}$ unit
+* **Single-stranded DNA (ssDNA)**: $33.0\text{ ng}/\mu\text{L}$ per $A_{260}$ unit
+
+### 2. Nucleic Acid Molecular Weights
+Molecular weights are computed from sequence-level atomic composition:
+
+* **Single-Stranded DNA (ssDNA, 5'-monophosphate)**:
+$$
+MW_{\text{ssDNA}} = (N_A \times 313.21) + (N_T \times 304.20) + (N_C \times 289.18) + (N_G \times 329.21) - 61.96
+$$
+
+* **Double-Stranded DNA (dsDNA)**:
+$$
+MW_{\text{dsDNA}} = (N_{\text{bp}} \times 607.4) + 157.9
+$$
+
+* **Single-Stranded RNA (5'-triphosphate, primary in vitro transcription product)**:
+$$
+MW_{\text{RNA, 5'-ppp}} = (N_A \times 329.21) + (N_U \times 306.17) + (N_C \times 305.18) + (N_G \times 345.21) + 159.0
+$$
+
+* **Single-Stranded RNA (5'-monophosphate, processed transcript)**:
+$$
+MW_{\text{RNA, 5'-p}} = MW_{\text{RNA, 5'-ppp}} - 79.98
+$$
+
+### 3. SantaLucia (1998) Nearest-Neighbor Primer Thermodynamics
+Primer melting temperatures ($T_m$) are calculated using unified nearest-neighbor thermodynamic parameters:
+
+$$
+\Delta H^\circ = \sum \Delta H^\circ_{\text{NN}} + \Delta H^\circ_{\text{init}}
+$$
+
+$$
+\Delta S^\circ = \sum \Delta S^\circ_{\text{NN}} + \Delta S^\circ_{\text{init}}
+$$
+
+$$
+T_m = \frac{\Delta H^\circ}{\Delta S^\circ + R \ln(C_T / 4)} - 273.15 + 16.6 \log_{10}[\text{Na}^+]
+$$
+
+Where:
+* $\Delta H^\circ$: Enthalpy change ($\text{kcal}\cdot\text{mol}^{-1}$)
+* $\Delta S^\circ$: Entropy change ($\text{cal}\cdot\text{mol}^{-1}\cdot\text{K}^{-1}$)
+* $R = 1.9872\text{ cal}\cdot\text{mol}^{-1}\cdot\text{K}^{-1}$: Universal gas constant
+* $C_T$: Total primer concentration (typically $400\text{ nM} = 4.0 \times 10^{-7}\text{ M}$)
+* $[\text{Na}^+]$: Effective monovalent cation concentration (typically $50\text{ mM} = 0.05\text{ M}$)
+
+### 4. Gel Electrophoresis Migration Mobility ($R_f$)
+The relative migration distance ($R_f$) of linear nucleic acid or denatured protein fragments through sieving matrices is inversely proportional to the logarithm of molecular size:
+
+$$
+R_f = a - b \cdot \log_{10}(M)
+$$
+
+Where:
+* $R_f = \frac{d_{\text{band}}}{d_{\text{dye}}}$: Relative mobility normalized to the dye front
+* $M$: Molecular size (in base pairs, nucleotides, or kDa)
+* $a, b$: Calibration constants determined by linear regression against reference ladder bands
+
+### 5. Bacterial Exponential Growth Kinetics (*E. coli*)
+During exponential phase growth, cell density ($\text{OD}_{600}$) increases according to first-order kinetics:
+
+$$
+\text{OD}(t) = \text{OD}_0 \cdot 2^{t / g} = \text{OD}_0 \cdot e^{\mu t}
+$$
+
+Where:
+* $\text{OD}_0$: Initial optical density at $600\text{ nm}$
+* $g$: Generation (doubling) time in minutes ($g = \frac{\ln 2}{\mu}$)
+* $\mu$: Specific growth rate ($\text{min}^{-1}$)
+* The time $t$ to reach target induction optical density ($\text{OD}_{\text{target}}$, typically 0.6–0.8) is:
+$$
+t = g \cdot \frac{\log_{10}(\text{OD}_{\text{target}} / \text{OD}_0)}{\log_{10}(2)}
+$$
+
+### 6. In Vitro Transcription (IVT) Stoichiometry
+Enzymatic synthesis of RNA by T7 RNA polymerase consumes ribonucleotide triphosphates and generates inorganic pyrophosphate ($PP_i$) byproducts:
+
+$$
+\text{Molar Yield (mol)} = \frac{\text{Mass Yield (g)}}{MW_{\text{transcript}}\text{ (g/mol)}}
+$$
+
+For each nucleotide species $X \in \{A, U, C, G\}$:
+$$
+\text{Consumed } X\text{ (moles)} = \text{Molar Yield} \times N_X
+$$
+
+$$
+\text{Pyrophosphate Generated } (PP_i)\text{ (moles)} = \text{Molar Yield} \times (L_{\text{transcript}} - 1)
+$$
+
+### 7. Pace et al. (1995) Protein Extinction Coefficient ($\epsilon_{280}$)
+The theoretical molar extinction coefficient of an unfolded or denatured protein at $280\text{ nm}$ is calculated from aromatic amino acid and disulfide bond counts:
+
+$$
+\epsilon_{280} = (N_{\text{Trp}} \times 5500) + (N_{\text{Tyr}} \times 1490) + (N_{\text{Cystine}} \times 125)
+$$
+
+Where $N_{\text{Cystine}} = \lfloor N_{\text{Cys}} / 2 \rfloor$ under non-reducing conditions, or $0$ under reducing conditions (DTT / $\beta$-ME).
+
+### 8. Fluorophore Degree of Labeling (DOL)
+The molar ratio of fluorophore to biomolecule is quantified spectrophotometrically:
+
+$$
+\text{DOL} = \frac{A_{\text{max}} \cdot \epsilon_{\text{biomolecule}}}{(A_{280} - A_{\text{max}} \cdot CF_{280}) \cdot \epsilon_{\text{dye}}}
+$$
+
+Where:
+* $A_{\text{max}}$: Absorbance at the dye excitation maximum wavelength
+* $A_{280}$: Absorbance at $280\text{ nm}$ (or $A_{260}$ for oligonucleotides)
+* $CF_{280}$: Spectral correction factor ($\frac{A_{280,\text{dye}}}{A_{\text{max},\text{dye}}}$)
+* $\epsilon_{\text{biomolecule}}, \epsilon_{\text{dye}}$: Respective molar extinction coefficients
+
+### 9. qPCR Amplification Efficiency
+From the slope of a linear standard curve ($C_q$ vs. $\log_{10}[\text{template dilution}]$):
+
+$$
+\text{Efficiency } (E) = 10^{-1 / \text{slope}} - 1
+$$
+
+$$
+\text{Percentage Efficiency} = E \times 100\%
+$$
+
+*(An ideal slope of $-3.3219$ corresponds to $E = 1.00$, or $100\%$ amplification efficiency).*
+
+### 10. Tris Buffer Temperature-Dependent pH Shift
+Tris solutions exhibit temperature sensitivity due to a negative ionization enthalpy:
+
+$$
+\Delta \text{pH} = \frac{d\text{p}K_a}{dT} \times (T_{\text{target}} - T_{\text{measured}})
+$$
+
+Where $\frac{d\text{p}K_a}{dT} \approx -0.028\text{ pH units}/^\circ\text{C}$.
+
+---
+
+## 🧪 Running Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+All 114 automated tests pass with 100% test coverage across core mathematical, physical, and biochemical modules.
+
+---
+
+## 🚀 PyPI Publishing & Distribution
+
+BioLabCalc is configured for automated Continuous Delivery to [PyPI](https://pypi.org/project/biolabcalc/) using GitHub Actions and PyPI Trusted Publishing (OIDC).
+
+
+
+## ⚖️ Legal & Compliance Notice
+
+BioLabCalc is developed for open scientific research. For full regulatory, export control, biosecurity, and dependency audit details, consult [LEGAL.md](LEGAL.md).
+
+* **Research Use Only (RUO)**: BioLabCalc is designed solely for academic research and educational purposes. It is **not** certified, validated, or intended for human or animal clinical diagnostics, medical treatment, or therapeutic manufacturing.
+* **Biosecurity & Export Control**: All algorithms are based on fundamental, publicly available scientific research (15 CFR § 734.7 & § 734.8; EAR99). The software contains no select agent design pipelines or dual-use biosecurity evasion mechanisms.
+* **Permissive Dependencies**: All upstream dependencies (`openpyxl`, `matplotlib`, `Pillow`, `numpy`) use OSI-approved permissive licenses (MIT, PSF, HPND, BSD-3-Clause) with zero copyleft (GPL/AGPL) restrictions.
+* **Trademark Notice**: All third-party registered trademarks (e.g. Gibson Assembly®, NanoDrop™, Coomassie®, Triton™, Tween®, Q5®, Phusion®) are the property of their respective owners and are referenced under nominative fair use without affiliation or endorsement.
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.