uht-tooling 0.1.8__tar.gz → 0.2.0__tar.gz

{uht_tooling-0.1.8 → uht_tooling-0.2.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: uht-tooling
-Version: 0.1.8
+Version: 0.2.0
 Summary: Tooling for ultra-high throughput screening workflows.
 Author: Matt115A
-License: MIT
+License-Expression: MIT
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: biopython==1.85
@@ -82,6 +82,7 @@ Each command mirrors a workflow module. Common entry points:
 | --- | --- |
 | `uht-tooling nextera-primers` | Generate Nextera XT primer pairs from a binding-region CSV. |
 | `uht-tooling design-slim` | Design SLIM mutagenesis primers from FASTA/CSV inputs. |
+| `uht-tooling design-kld` | Design KLD (inverse PCR) mutagenesis primers. |
 | `uht-tooling design-gibson` | Produce Gibson mutagenesis primers and assembly plans. |
 | `uht-tooling mutation-caller` | Summarise amino-acid substitutions from long-read FASTQ files. |
 | `uht-tooling umi-hunter` | Cluster UMIs and call consensus genes. |
@@ -189,6 +190,52 @@ The workflow validates that the wild-type amino acid matches the template sequen
 - Combine 10 µL from each PCR with 10 µL H-buffer (150 mM Tris pH 8, 400 mM NaCl, 60 mM EDTA) for a 30 µL annealing reaction: 99 °C for 3 min, then two cycles of 65 °C for 5 min followed by 30 °C for 15 min, hold at 4 °C.
 - Transform directly into NEB 5-alpha or BL21 (DE3) cells without additional cleanup. The protocol has been validated for simultaneous introduction of dozens of mutations.
 
+### KLD primer design
+
+KLD (Kinase-Ligation-DpnI) is an alternative mutagenesis method using inverse PCR to amplify the entire plasmid with mutations incorporated at the primer junction.
+
+- Inputs: Same as SLIM design
+  - `data/design_kld/kld_template_gene.fasta`
+  - `data/design_kld/kld_context.fasta`
+  - `data/design_kld/kld_target_mutations.csv` (single `mutations` column)
+- Run:
+  ```bash
+  uht-tooling design-kld \
+    --gene-fasta data/design_kld/kld_template_gene.fasta \
+    --context-fasta data/design_kld/kld_context.fasta \
+    --mutations-csv data/design_kld/kld_target_mutations.csv \
+    --output-dir results/design_kld/
+  ```
+- Output: `results/design_kld/KLD_primers.csv` plus logs.
+
+Mutation nomenclature: Same as SLIM (substitution, deletion, insertion, indel, library).
+
+#### KLD vs SLIM
+
+| Method | Primers | Mechanism | Best for |
+|--------|---------|-----------|----------|
+| SLIM | 4 per mutation | Overlap assembly | Multiple simultaneous mutations |
+| KLD | 2 per mutation | Inverse PCR + ligation | Single mutations, simpler workflow |
+
+#### KLD primer design rules
+
+- Forward primer: Mutation codon at 5' end + downstream template-binding region
+- Reverse primer: Reverse complement of upstream region, 5' end adjacent to forward
+- Tm calculated on template-binding regions only (50-65°C target)
+- Tm difference between primers kept within 5°C
+- GC content 40-60%
+- Binding region 18-24 bp
+
+#### Experimental workflow
+
+1. PCR amplify entire plasmid with KLD primer pair
+2. DpnI digest to remove methylated template
+3. T4 PNK phosphorylation of 5' ends
+4. T4 DNA ligase to circularize
+5. Transform into competent cells
+
+NEB sells a KLD Enzyme Mix (M0554) that combines these steps.
+
 ### Gibson assembly primers
 
 - Inputs mirror the SLIM workflow but use `data/design_gibson/`.
@@ -266,13 +313,57 @@ Please be aware, this toolkit will not scale well beyond around 50k reads/sample
     --fastq data/ep-library-profile/*.fastq.gz \
     --output-dir results/ep-library-profile/
   ```
-- Output bundle includes per-sample directories, a master summary TSV, and a `summary_panels` figure that visualises positional mutation rates, coverage, and amino-acid simulations.
+
+**Output structure**
+
+Each sample produces an organized output directory:
+
+```
+sample_name/
+├── KEY_FINDINGS.txt              # Lay-user executive summary
+├── summary_panels.png/pdf        # Main visualization
+├── aa_mutation_consensus.txt     # Consensus estimate details
+├── run.log                       # Analysis log
+└── detailed/                     # Technical outputs
+    ├── methodology_notes.txt     # Documents which lambda drives what
+    ├── lambda_comparison.csv     # Side-by-side lambda comparison
+    ├── gene_mismatch_rates.csv
+    ├── base_distribution.csv
+    ├── aa_substitutions.csv
+    ├── plasmid_coverage.csv
+    ├── aa_mutation_distribution.csv
+    ├── comprehensive_qc_data.csv
+    ├── simple_qc_data.csv
+    └── qc_plots/                 # QC visualizations
+        ├── qc_plot_*.png
+        ├── comprehensive_qc_analysis.png
+        ├── error_analysis.png
+        └── qc_mutation_rate_vs_quality.png/csv
+```
+
+**Lambda estimates: which to use**
+
+The profiler calculates lambda (mutations per gene copy) via two methods:
+
+| Method | Formula | Error Quantified? | Used For |
+|--------|---------|-------------------|----------|
+| Simple | `(hit_rate - bg_rate) × seq_len` | No | KDE plot, Monte Carlo simulation |
+| Consensus | Precision-weighted average across Q-scores | Yes | Recommended for reporting |
+
+- **For publication/reporting**: Use the consensus value from `KEY_FINDINGS.txt` or `aa_mutation_consensus.txt`.
+- **For understanding distribution shape**: See the KDE plot in `summary_panels.png` (note: uses simple lambda).
+- **For detailed error analysis**: See `detailed/comprehensive_qc_data.csv`.
+
+The `KEY_FINDINGS.txt` file provides a plain-language summary including:
+- Expected AA mutations per gene copy
+- Poisson-based interpretation (% wild-type, % 1 mutation, % 2+ mutations)
+- Quality assessment (GOOD/ACCEPTABLE/LOW COVERAGE)
 
 **How the mutation rate and AA expectations are derived**
 
-1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the “target” rate; mismatches elsewhere provide the background.
+1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the "target" rate; mismatches elsewhere provide the background.
 2. The per-base background rate is subtracted from the target rate to yield a net nucleotide mutation rate, and the standard deviation reflects binomial sampling and quality-score uncertainty.
-3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drives the AA mutation mean/variance that appear in the panel plot.
+3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drive the AA mutation mean/variance that appear in the panel plot.
 4. If multiple Q-score thresholds are analysed, the CLI aggregates them via a precision-weighted consensus (1 / standard deviation weighting) after filtering out thresholds with insufficient coverage; the consensus value is written to `aa_mutation_consensus.txt` and plotted as a horizontal guide.
 
 ---
@@ -293,12 +384,13 @@ Key points:
 ### Tabs and capabilities
 
 1. **Nextera XT** – forward/reverse primer inputs with CSV preview.
-2. **SLIM** – template/context FASTA text areas plus mutation list.
-3. **Gibson** – multi-mutation support using `+` syntax.
-4. **Mutation Caller** – upload FASTQ and template FASTA, then enter flanks and gene length bounds inline.
-5. **UMI Hunter** – long-read UMI clustering with flank entry, UMI length bounds, mutation threshold, and minimum cluster size.
-6. **Profile Inserts** – interactive probe table plus multiple FASTQ uploads with adjustable fuzzy-match ratio.
-7. **EP Library Profile** – FASTQ uploads plus plasmid and region FASTA inputs.
+2. **SLIM** – template/context FASTA text areas plus mutation list (supports library codons like `R57:NNK`).
+3. **KLD** – inverse-PCR primer design using the same mutation list format (including library codons like `R57:NNK`).
+4. **Gibson** – multi-mutation support using `+` syntax.
+5. **Mutation Caller** – upload FASTQ and template FASTA, then enter flanks and gene length bounds inline.
+6. **UMI Hunter** – long-read UMI clustering with flank entry, UMI length bounds, mutation threshold, and minimum cluster size.
+7. **Profile Inserts** – interactive probe table plus multiple FASTQ uploads with adjustable fuzzy-match ratio.
+8. **EP Library Profile** – FASTQ uploads plus plasmid and region FASTA inputs.
 
 ### Workflow tips
 

{uht_tooling-0.1.8 → uht_tooling-0.2.0}/README.md

@@ -53,6 +53,7 @@ Each command mirrors a workflow module. Common entry points:
 | --- | --- |
 | `uht-tooling nextera-primers` | Generate Nextera XT primer pairs from a binding-region CSV. |
 | `uht-tooling design-slim` | Design SLIM mutagenesis primers from FASTA/CSV inputs. |
+| `uht-tooling design-kld` | Design KLD (inverse PCR) mutagenesis primers. |
 | `uht-tooling design-gibson` | Produce Gibson mutagenesis primers and assembly plans. |
 | `uht-tooling mutation-caller` | Summarise amino-acid substitutions from long-read FASTQ files. |
 | `uht-tooling umi-hunter` | Cluster UMIs and call consensus genes. |
@@ -160,6 +161,52 @@ The workflow validates that the wild-type amino acid matches the template sequen
 - Combine 10 µL from each PCR with 10 µL H-buffer (150 mM Tris pH 8, 400 mM NaCl, 60 mM EDTA) for a 30 µL annealing reaction: 99 °C for 3 min, then two cycles of 65 °C for 5 min followed by 30 °C for 15 min, hold at 4 °C.
 - Transform directly into NEB 5-alpha or BL21 (DE3) cells without additional cleanup. The protocol has been validated for simultaneous introduction of dozens of mutations.
 
+### KLD primer design
+
+KLD (Kinase-Ligation-DpnI) is an alternative mutagenesis method using inverse PCR to amplify the entire plasmid with mutations incorporated at the primer junction.
+
+- Inputs: Same as SLIM design
+  - `data/design_kld/kld_template_gene.fasta`
+  - `data/design_kld/kld_context.fasta`
+  - `data/design_kld/kld_target_mutations.csv` (single `mutations` column)
+- Run:
+  ```bash
+  uht-tooling design-kld \
+    --gene-fasta data/design_kld/kld_template_gene.fasta \
+    --context-fasta data/design_kld/kld_context.fasta \
+    --mutations-csv data/design_kld/kld_target_mutations.csv \
+    --output-dir results/design_kld/
+  ```
+- Output: `results/design_kld/KLD_primers.csv` plus logs.
+
+Mutation nomenclature: Same as SLIM (substitution, deletion, insertion, indel, library).
+
+#### KLD vs SLIM
+
+| Method | Primers | Mechanism | Best for |
+|--------|---------|-----------|----------|
+| SLIM | 4 per mutation | Overlap assembly | Multiple simultaneous mutations |
+| KLD | 2 per mutation | Inverse PCR + ligation | Single mutations, simpler workflow |
+
+#### KLD primer design rules
+
+- Forward primer: Mutation codon at 5' end + downstream template-binding region
+- Reverse primer: Reverse complement of upstream region, 5' end adjacent to forward
+- Tm calculated on template-binding regions only (50-65°C target)
+- Tm difference between primers kept within 5°C
+- GC content 40-60%
+- Binding region 18-24 bp
+
+#### Experimental workflow
+
+1. PCR amplify entire plasmid with KLD primer pair
+2. DpnI digest to remove methylated template
+3. T4 PNK phosphorylation of 5' ends
+4. T4 DNA ligase to circularize
+5. Transform into competent cells
+
+NEB sells a KLD Enzyme Mix (M0554) that combines these steps.
+
 ### Gibson assembly primers
 
 - Inputs mirror the SLIM workflow but use `data/design_gibson/`.
@@ -237,13 +284,57 @@ Please be aware, this toolkit will not scale well beyond around 50k reads/sample
     --fastq data/ep-library-profile/*.fastq.gz \
     --output-dir results/ep-library-profile/
   ```
-- Output bundle includes per-sample directories, a master summary TSV, and a `summary_panels` figure that visualises positional mutation rates, coverage, and amino-acid simulations.
+
+**Output structure**
+
+Each sample produces an organized output directory:
+
+```
+sample_name/
+├── KEY_FINDINGS.txt              # Lay-user executive summary
+├── summary_panels.png/pdf        # Main visualization
+├── aa_mutation_consensus.txt     # Consensus estimate details
+├── run.log                       # Analysis log
+└── detailed/                     # Technical outputs
+    ├── methodology_notes.txt     # Documents which lambda drives what
+    ├── lambda_comparison.csv     # Side-by-side lambda comparison
+    ├── gene_mismatch_rates.csv
+    ├── base_distribution.csv
+    ├── aa_substitutions.csv
+    ├── plasmid_coverage.csv
+    ├── aa_mutation_distribution.csv
+    ├── comprehensive_qc_data.csv
+    ├── simple_qc_data.csv
+    └── qc_plots/                 # QC visualizations
+        ├── qc_plot_*.png
+        ├── comprehensive_qc_analysis.png
+        ├── error_analysis.png
+        └── qc_mutation_rate_vs_quality.png/csv
+```
+
+**Lambda estimates: which to use**
+
+The profiler calculates lambda (mutations per gene copy) via two methods:
+
+| Method | Formula | Error Quantified? | Used For |
+|--------|---------|-------------------|----------|
+| Simple | `(hit_rate - bg_rate) × seq_len` | No | KDE plot, Monte Carlo simulation |
+| Consensus | Precision-weighted average across Q-scores | Yes | Recommended for reporting |
+
+- **For publication/reporting**: Use the consensus value from `KEY_FINDINGS.txt` or `aa_mutation_consensus.txt`.
+- **For understanding distribution shape**: See the KDE plot in `summary_panels.png` (note: uses simple lambda).
+- **For detailed error analysis**: See `detailed/comprehensive_qc_data.csv`.
+
+The `KEY_FINDINGS.txt` file provides a plain-language summary including:
+- Expected AA mutations per gene copy
+- Poisson-based interpretation (% wild-type, % 1 mutation, % 2+ mutations)
+- Quality assessment (GOOD/ACCEPTABLE/LOW COVERAGE)
 
 **How the mutation rate and AA expectations are derived**
 
-1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the “target” rate; mismatches elsewhere provide the background.
+1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the "target" rate; mismatches elsewhere provide the background.
 2. The per-base background rate is subtracted from the target rate to yield a net nucleotide mutation rate, and the standard deviation reflects binomial sampling and quality-score uncertainty.
-3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drives the AA mutation mean/variance that appear in the panel plot.
+3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drive the AA mutation mean/variance that appear in the panel plot.
 4. If multiple Q-score thresholds are analysed, the CLI aggregates them via a precision-weighted consensus (1 / standard deviation weighting) after filtering out thresholds with insufficient coverage; the consensus value is written to `aa_mutation_consensus.txt` and plotted as a horizontal guide.
 
 ---
@@ -264,12 +355,13 @@ Key points:
 ### Tabs and capabilities
 
 1. **Nextera XT** – forward/reverse primer inputs with CSV preview.
-2. **SLIM** – template/context FASTA text areas plus mutation list.
-3. **Gibson** – multi-mutation support using `+` syntax.
-4. **Mutation Caller** – upload FASTQ and template FASTA, then enter flanks and gene length bounds inline.
-5. **UMI Hunter** – long-read UMI clustering with flank entry, UMI length bounds, mutation threshold, and minimum cluster size.
-6. **Profile Inserts** – interactive probe table plus multiple FASTQ uploads with adjustable fuzzy-match ratio.
-7. **EP Library Profile** – FASTQ uploads plus plasmid and region FASTA inputs.
+2. **SLIM** – template/context FASTA text areas plus mutation list (supports library codons like `R57:NNK`).
+3. **KLD** – inverse-PCR primer design using the same mutation list format (including library codons like `R57:NNK`).
+4. **Gibson** – multi-mutation support using `+` syntax.
+5. **Mutation Caller** – upload FASTQ and template FASTA, then enter flanks and gene length bounds inline.
+6. **UMI Hunter** – long-read UMI clustering with flank entry, UMI length bounds, mutation threshold, and minimum cluster size.
+7. **Profile Inserts** – interactive probe table plus multiple FASTQ uploads with adjustable fuzzy-match ratio.
+8. **EP Library Profile** – FASTQ uploads plus plasmid and region FASTA inputs.
 
 ### Workflow tips
 

{uht_tooling-0.1.8 → uht_tooling-0.2.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uht-tooling"
-version = "0.1.8"
+version = "0.2.0"
 description = "Tooling for ultra-high throughput screening workflows."
 readme = "README.md"
 requires-python = ">=3.8"
-license = { text = "MIT" }
+license = "MIT"
 authors = [{ name = "Matt115A" }]
 dependencies = [
     "biopython==1.85",

{uht_tooling-0.1.8 → uht_tooling-0.2.0}/src/uht_tooling/cli.py

@@ -4,6 +4,7 @@ from typing import Optional
 import typer
 
 from uht_tooling.workflows.design_gibson import run_design_gibson
+from uht_tooling.workflows.design_kld import run_design_kld
 from uht_tooling.workflows.design_slim import run_design_slim
 from uht_tooling.workflows.mutation_caller import (
     expand_fastq_inputs as expand_fastq_inputs_mutation,
@@ -66,6 +67,45 @@ def design_slim_command(
     typer.echo(f"SLIM primers written to {output_dir / 'SLIM_primers.csv'}")
 
 
+@app.command("design-kld", help="Design KLD (inverse PCR) primers from user-specified FASTA/CSV inputs.")
+def design_kld_command(
+    gene_fasta: Path = typer.Option(..., exists=True, readable=True, help="Path to the gene FASTA file."),
+    context_fasta: Path = typer.Option(
+        ...,
+        exists=True,
+        readable=True,
+        help="Path to the context FASTA file containing the plasmid or genomic sequence.",
+    ),
+    mutations_csv: Path = typer.Option(
+        ...,
+        exists=True,
+        readable=True,
+        help="CSV file containing a 'mutations' column with the desired edits.",
+    ),
+    output_dir: Path = typer.Option(
+        ...,
+        dir_okay=True,
+        writable=True,
+        help="Directory where results will be written.",
+    ),
+    log_path: Optional[Path] = typer.Option(
+        None,
+        dir_okay=False,
+        writable=True,
+        help="Optional path to write a dedicated log file for this run.",
+    ),
+):
+    """Design KLD (inverse PCR) primers from user-provided inputs."""
+    result_path = run_design_kld(
+        gene_fasta=gene_fasta,
+        context_fasta=context_fasta,
+        mutations_csv=mutations_csv,
+        output_dir=output_dir,
+        log_path=log_path,
+    )
+    typer.echo(f"KLD primers written to {result_path}")
+
+
 @app.command("nextera-primers", help="Generate Nextera XT primers from binding region CSV input.")
 def nextera_primers_command(
     binding_csv: Path = typer.Option(