uht-tooling 0.1.7__tar.gz → 0.1.9__tar.gz

{uht_tooling-0.1.7 → uht_tooling-0.1.9}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: uht-tooling
-Version: 0.1.7
+Version: 0.1.9
 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. |
@@ -141,6 +142,46 @@ Mutation nomenclature examples:
 - `T241Del` (deletion)
 - `T241TS` (insert Ser after Thr241)
 - `L46GP` (replace Leu46 with Gly-Pro)
+- `A123:NNK` (library mutation with degenerate codon)
+
+#### Library mutations with degenerate codons
+
+For saturation mutagenesis and library generation, SLIM supports degenerate (IUPAC ambiguity) codons using the format `<WT_AA><position>:<codon>`. The codon must be exactly 3 characters using valid IUPAC nucleotide codes:
+
+| Code | Bases | Mnemonic |
+|------|-------|----------|
+| A, C, G, T | Single base | Standard |
+| R | A, G | puRine |
+| Y | C, T | pYrimidine |
+| S | G, C | Strong |
+| W | A, T | Weak |
+| K | G, T | Keto |
+| M | A, C | aMino |
+| B | C, G, T | not A |
+| D | A, G, T | not C |
+| H | A, C, T | not G |
+| V | A, C, G | not T |
+| N | A, C, G, T | aNy |
+
+Common degenerate codon schemes for library construction:
+
+| Scheme | Codons | Amino acids | Stop codons | Notes |
+|--------|--------|-------------|-------------|-------|
+| NNK | 32 | 20 | 1 (TAG) | Reduced stop codon frequency |
+| NNS | 32 | 20 | 1 (TAG) | Equivalent to NNK |
+| NNN | 64 | 20 | 3 | All codons, higher stop frequency |
+| NDT | 12 | 12 | 0 | F, L, I, V, Y, H, N, D, C, R, S, G only |
+
+Example CSV with mixed mutation types:
+```csv
+mutations
+A123G
+T50:NNK
+S100:NNS
+T241Del
+```
+
+The workflow validates that the wild-type amino acid matches the template sequence and logs library coverage information (number of possible codons and amino acids) for each degenerate mutation. Primers are generated with the degenerate bases embedded; reverse primers contain the correct IUPAC reverse complements (e.g., K↔M, R↔Y, S↔S).
 
 #### Experimental blueprint
 
@@ -149,6 +190,52 @@ Mutation nomenclature examples:
 - 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/`.
@@ -253,12 +340,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.7 → uht_tooling-0.1.9}/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. |
@@ -112,6 +113,46 @@ Mutation nomenclature examples:
 - `T241Del` (deletion)
 - `T241TS` (insert Ser after Thr241)
 - `L46GP` (replace Leu46 with Gly-Pro)
+- `A123:NNK` (library mutation with degenerate codon)
+
+#### Library mutations with degenerate codons
+
+For saturation mutagenesis and library generation, SLIM supports degenerate (IUPAC ambiguity) codons using the format `<WT_AA><position>:<codon>`. The codon must be exactly 3 characters using valid IUPAC nucleotide codes:
+
+| Code | Bases | Mnemonic |
+|------|-------|----------|
+| A, C, G, T | Single base | Standard |
+| R | A, G | puRine |
+| Y | C, T | pYrimidine |
+| S | G, C | Strong |
+| W | A, T | Weak |
+| K | G, T | Keto |
+| M | A, C | aMino |
+| B | C, G, T | not A |
+| D | A, G, T | not C |
+| H | A, C, T | not G |
+| V | A, C, G | not T |
+| N | A, C, G, T | aNy |
+
+Common degenerate codon schemes for library construction:
+
+| Scheme | Codons | Amino acids | Stop codons | Notes |
+|--------|--------|-------------|-------------|-------|
+| NNK | 32 | 20 | 1 (TAG) | Reduced stop codon frequency |
+| NNS | 32 | 20 | 1 (TAG) | Equivalent to NNK |
+| NNN | 64 | 20 | 3 | All codons, higher stop frequency |
+| NDT | 12 | 12 | 0 | F, L, I, V, Y, H, N, D, C, R, S, G only |
+
+Example CSV with mixed mutation types:
+```csv
+mutations
+A123G
+T50:NNK
+S100:NNS
+T241Del
+```
+
+The workflow validates that the wild-type amino acid matches the template sequence and logs library coverage information (number of possible codons and amino acids) for each degenerate mutation. Primers are generated with the degenerate bases embedded; reverse primers contain the correct IUPAC reverse complements (e.g., K↔M, R↔Y, S↔S).
 
 #### Experimental blueprint
 
@@ -120,6 +161,52 @@ Mutation nomenclature examples:
 - 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/`.
@@ -224,12 +311,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.7 → uht_tooling-0.1.9}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uht-tooling"
-version = "0.1.7"
+version = "0.1.9"
 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.7 → uht_tooling-0.1.9}/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(