uht-tooling 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

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(

uht_tooling/workflows/design_kld.py

@@ -0,0 +1,687 @@
+"""KLD (Kinase-Ligation-DpnI) primer design for inverse PCR mutagenesis."""
+
+import argparse
+import csv
+import logging
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import pandas as pd
+from Bio import SeqIO
+from Bio.Seq import Seq
+from Bio.SeqUtils import MeltingTemp as mt
+
+# KLD primer design parameters
+MIN_TM = 50.0           # Minimum melting temperature
+MAX_TM = 65.0           # Maximum melting temperature
+TM_DIFF_THRESHOLD = 5.0  # Max Tm difference between F & R
+MIN_LENGTH = 18         # Minimum primer length (template-binding region)
+MAX_LENGTH = 24         # Maximum primer length (template-binding region)
+MIN_GC = 40.0           # Minimum GC content %
+MAX_GC = 60.0           # Maximum GC content %
+MIN_BINDING = 10        # Minimum template-binding region
+
+# IUPAC ambiguity codes mapping
+IUPAC_AMBIGUITY = {
+    'A': ['A'], 'C': ['C'], 'G': ['G'], 'T': ['T'],
+    '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'],
+}
+
+VALID_DEGENERATE_BASES = set(IUPAC_AMBIGUITY.keys())
+
+
+def is_valid_degenerate_codon(codon: str) -> bool:
+    """Check if a codon contains only valid IUPAC nucleotide codes."""
+    return len(codon) == 3 and all(b.upper() in VALID_DEGENERATE_BASES for b in codon)
+
+
+def contains_degenerate_bases(seq: str) -> bool:
+    """Return True if sequence contains non-standard (degenerate) bases."""
+    return any(b.upper() not in {'A', 'C', 'G', 'T'} for b in seq)
+
+
+def expand_degenerate_sequence(seq: str) -> List[str]:
+    """Expand a degenerate sequence to all possible standard sequences."""
+    from itertools import product
+    possibilities = [IUPAC_AMBIGUITY.get(b.upper(), [b]) for b in seq]
+    return [''.join(combo) for combo in product(*possibilities)]
+
+
+def codon_table():
+    return {
+        "TTT": "F", "TTC": "F", "TTA": "L", "TTG": "L",
+        "TCT": "S", "TCC": "S", "TCA": "S", "TCG": "S",
+        "TAT": "Y", "TAC": "Y", "TAA": "*", "TAG": "*",
+        "TGT": "C", "TGC": "C", "TGA": "*", "TGG": "W",
+        "CTT": "L", "CTC": "L", "CTA": "L", "CTG": "L",
+        "CCT": "P", "CCC": "P", "CCA": "P", "CCG": "P",
+        "CAT": "H", "CAC": "H", "CAA": "Q", "CAG": "Q",
+        "CGT": "R", "CGC": "R", "CGA": "R", "CGG": "R",
+        "ATT": "I", "ATC": "I", "ATA": "I", "ATG": "M",
+        "ACT": "T", "ACC": "T", "ACA": "T", "ACG": "T",
+        "AAT": "N", "AAC": "N", "AAA": "K", "AAG": "K",
+        "AGT": "S", "AGC": "S", "AGA": "R", "AGG": "R",
+        "GTT": "V", "GTC": "V", "GTA": "V", "GTG": "V",
+        "GCT": "A", "GCC": "A", "GCA": "A", "GCG": "A",
+        "GAT": "D", "GAC": "D", "GAA": "E", "GAG": "E",
+        "GGT": "G", "GGC": "G", "GGA": "G", "GGG": "G",
+    }
+
+
+def translate_codon(cd: str) -> str:
+    """Translate a 3-nt codon to its amino acid."""
+    return codon_table().get(cd.upper(), "?")
+
+
+def pick_mutant_codon(wt_codon: str, target_aa: str) -> Optional[str]:
+    """Pick the codon for target_aa that differs minimally from wt_codon."""
+    best_list = []
+    for codon, aa in codon_table().items():
+        if aa == target_aa:
+            diff = sum(a != b for a, b in zip(codon.upper(), wt_codon.upper()))
+            best_list.append((codon.upper(), diff))
+    if not best_list:
+        return None
+    best_list.sort(key=lambda x: x[1])
+    return best_list[0][0]
+
+
+def calc_tm_binding_region(seq: str) -> float:
+    """Calculate Tm for template-binding region (handles degenerate bases)."""
+    if contains_degenerate_bases(seq):
+        expanded = expand_degenerate_sequence(seq)
+        tms = [mt.Tm_NN(s) for s in expanded]
+        return sum(tms) / len(tms)
+    return mt.Tm_NN(seq)
+
+
+def calc_gc_content(seq: str) -> float:
+    """Calculate GC content percentage."""
+    seq = seq.upper()
+    gc = sum(1 for b in seq if b in 'GC')
+    return (gc / len(seq)) * 100 if seq else 0.0
+
+
+def design_forward_primer(
+    full_seq: str,
+    mutation_nt_pos: int,
+    new_codon: str,
+    min_tm: float = MIN_TM,
+    max_tm: float = MAX_TM,
+    min_len: int = MIN_LENGTH,
+    max_len: int = MAX_LENGTH,
+) -> Tuple[str, str, float, float, int]:
+    """
+    Design forward primer with mutation at 5' end.
+
+    Structure: [MUTATED_CODON] + [WT_DOWNSTREAM_SEQUENCE]
+
+    The forward primer points downstream (→→→), with its 5' end at the mutation
+    site. The template-binding region is the WT sequence immediately downstream
+    of the mutation.
+
+    Args:
+        full_seq: Full plasmid/context sequence
+        mutation_nt_pos: Nucleotide position of mutation start (0-indexed)
+        new_codon: The mutated codon sequence (3 nt, may be degenerate)
+        min_tm: Minimum melting temperature for binding region
+        max_tm: Maximum melting temperature for binding region
+        min_len: Minimum binding region length
+        max_len: Maximum binding region length
+
+    Returns:
+        Tuple of (full_primer_seq, binding_region_seq, tm, gc, total_length)
+
+    Raises:
+        ValueError: If no valid binding region can be found
+    """
+    # Template-binding region starts immediately after mutation codon
+    # (we use len(new_codon) to handle both regular codons and deletions)
+    old_codon_len = 3  # Standard codon replacement
+    binding_start = mutation_nt_pos + old_codon_len
+
+    best_binding = None
+    best_tm_diff = float('inf')
+    target_tm = (min_tm + max_tm) / 2
+
+    for length in range(min_len, max_len + 1):
+        binding_end = binding_start + length
+        if binding_end > len(full_seq):
+            break
+
+        binding_seq = full_seq[binding_start:binding_end]
+        tm = calc_tm_binding_region(binding_seq)
+        gc = calc_gc_content(binding_seq)
+
+        if min_tm <= tm <= max_tm and MIN_GC <= gc <= MAX_GC:
+            tm_diff = abs(tm - target_tm)
+            if tm_diff < best_tm_diff:
+                best_tm_diff = tm_diff
+                best_binding = (binding_seq, tm, gc, length)
+
+    if not best_binding:
+        # Try to find any binding region that meets length constraints
+        for length in range(min_len, max_len + 1):
+            binding_end = binding_start + length
+            if binding_end > len(full_seq):
+                break
+            binding_seq = full_seq[binding_start:binding_end]
+            tm = calc_tm_binding_region(binding_seq)
+            gc = calc_gc_content(binding_seq)
+            # Relax constraints slightly
+            if tm >= min_tm - 5 and tm <= max_tm + 5:
+                best_binding = (binding_seq, tm, gc, length)
+                break
+
+    if not best_binding:
+        raise ValueError(
+            f"Cannot find forward primer binding region meeting constraints "
+            f"(pos={mutation_nt_pos}, Tm={min_tm}-{max_tm}°C, len={min_len}-{max_len}bp)"
+        )
+
+    binding_seq, tm, gc, length = best_binding
+    full_primer = new_codon + binding_seq
+    return full_primer, binding_seq, tm, gc, len(full_primer)
+
+
+def design_reverse_primer(
+    full_seq: str,
+    mutation_nt_pos: int,
+    min_tm: float = MIN_TM,
+    max_tm: float = MAX_TM,
+    min_len: int = MIN_LENGTH,
+    max_len: int = MAX_LENGTH,
+) -> Tuple[str, float, float, int]:
+    """
+    Design reverse primer adjacent to forward primer's 5' end.
+
+    Structure: reverse_complement([WT_UPSTREAM_SEQUENCE])
+
+    The reverse primer's 5' end is at position mutation_nt_pos - 1, immediately
+    adjacent to the forward primer's 5' end. The primer anneals to the top
+    strand upstream of the mutation and points upstream (←←←).
+
+    Args:
+        full_seq: Full plasmid/context sequence
+        mutation_nt_pos: Nucleotide position of mutation start (0-indexed)
+        min_tm: Minimum melting temperature
+        max_tm: Maximum melting temperature
+        min_len: Minimum primer length
+        max_len: Maximum primer length
+
+    Returns:
+        Tuple of (primer_seq, tm, gc, length)
+
+    Raises:
+        ValueError: If no valid primer can be found
+    """
+    # Upstream region ends at mutation position (exclusive)
+    upstream_end = mutation_nt_pos
+
+    best_primer = None
+    best_tm_diff = float('inf')
+    target_tm = (min_tm + max_tm) / 2
+
+    for length in range(min_len, max_len + 1):
+        upstream_start = upstream_end - length
+        if upstream_start < 0:
+            break
+
+        upstream_seq = full_seq[upstream_start:upstream_end]
+        tm = calc_tm_binding_region(upstream_seq)
+        gc = calc_gc_content(upstream_seq)
+
+        if min_tm <= tm <= max_tm and MIN_GC <= gc <= MAX_GC:
+            tm_diff = abs(tm - target_tm)
+            if tm_diff < best_tm_diff:
+                best_tm_diff = tm_diff
+                primer_seq = str(Seq(upstream_seq).reverse_complement())
+                best_primer = (primer_seq, tm, gc, length)
+
+    if not best_primer:
+        # Try to find any primer that meets length constraints
+        for length in range(min_len, max_len + 1):
+            upstream_start = upstream_end - length
+            if upstream_start < 0:
+                break
+            upstream_seq = full_seq[upstream_start:upstream_end]
+            tm = calc_tm_binding_region(upstream_seq)
+            gc = calc_gc_content(upstream_seq)
+            # Relax constraints slightly
+            if tm >= min_tm - 5 and tm <= max_tm + 5:
+                primer_seq = str(Seq(upstream_seq).reverse_complement())
+                best_primer = (primer_seq, tm, gc, length)
+                break
+
+    if not best_primer:
+        raise ValueError(
+            f"Cannot find reverse primer meeting constraints "
+            f"(pos={mutation_nt_pos}, Tm={min_tm}-{max_tm}°C, len={min_len}-{max_len}bp)"
+        )
+
+    return best_primer
+
+
+def balance_primer_tms(
+    fwd_result: Tuple[str, str, float, float, int],
+    rev_result: Tuple[str, float, float, int],
+    full_seq: str,
+    mutation_nt_pos: int,
+    new_codon: str,
+    tm_threshold: float = TM_DIFF_THRESHOLD,
+) -> Tuple[Tuple[str, str, float, float, int], Tuple[str, float, float, int]]:
+    """
+    Balance Tm between forward and reverse primers by adjusting lengths.
+
+    If the Tm difference exceeds the threshold, attempt to trim the hotter
+    primer's binding region from its 3' end to reduce its Tm.
+
+    Args:
+        fwd_result: Forward primer tuple (full_seq, binding_seq, tm, gc, length)
+        rev_result: Reverse primer tuple (primer_seq, tm, gc, length)
+        full_seq: Full plasmid/context sequence
+        mutation_nt_pos: Nucleotide position of mutation start
+        new_codon: The mutated codon sequence
+        tm_threshold: Maximum allowed Tm difference
+
+    Returns:
+        Adjusted (fwd_result, rev_result) tuples
+    """
+    fwd_seq, fwd_binding, fwd_tm, fwd_gc, fwd_len = fwd_result
+    rev_seq, rev_tm, rev_gc, rev_len = rev_result
+
+    tm_diff = abs(fwd_tm - rev_tm)
+
+    if tm_diff <= tm_threshold:
+        return fwd_result, rev_result
+
+    # Try to trim the hotter primer
+    if fwd_tm > rev_tm:
+        # Trim forward binding region from 3' end
+        while len(fwd_binding) > MIN_BINDING and fwd_tm - rev_tm > tm_threshold:
+            fwd_binding = fwd_binding[:-1]
+            fwd_tm = calc_tm_binding_region(fwd_binding)
+
+        fwd_seq = new_codon + fwd_binding
+        fwd_gc = calc_gc_content(fwd_seq)
+        fwd_len = len(fwd_seq)
+        fwd_result = (fwd_seq, fwd_binding, fwd_tm, fwd_gc, fwd_len)
+    else:
+        # Trim reverse primer from 3' end
+        # The reverse primer is already reverse-complemented, so we need to
+        # trim from the 3' end of the original upstream sequence
+        upstream_end = mutation_nt_pos
+        current_len = rev_len
+
+        while current_len > MIN_BINDING and rev_tm - fwd_tm > tm_threshold:
+            current_len -= 1
+            upstream_start = upstream_end - current_len
+            if upstream_start < 0:
+                break
+            upstream_seq = full_seq[upstream_start:upstream_end]
+            rev_tm = calc_tm_binding_region(upstream_seq)
+
+        if upstream_start >= 0:
+            upstream_seq = full_seq[upstream_start:upstream_end]
+            rev_seq = str(Seq(upstream_seq).reverse_complement())
+            rev_gc = calc_gc_content(rev_seq)
+            rev_len = len(rev_seq)
+            rev_result = (rev_seq, rev_tm, rev_gc, rev_len)
+
+    return fwd_result, rev_result
+
+
+def run_design_kld(
+    gene_fasta: Path,
+    context_fasta: Path,
+    mutations_csv: Path,
+    output_dir: Path,
+    log_path: Optional[Path] = None,
+    logger: Optional[logging.Logger] = None,
+) -> Path:
+    """
+    Design KLD (inverse PCR) primers for mutations.
+
+    KLD cloning uses two primers per mutation that point away from each other,
+    amplifying the entire plasmid. The forward primer has the mutation at its
+    5' end, and the reverse primer's 5' end is adjacent to the forward's.
+
+    Args:
+        gene_fasta: Path to FASTA file containing the gene sequence
+        context_fasta: Path to FASTA file containing the plasmid/context sequence
+        mutations_csv: CSV file with a 'mutations' column
+        output_dir: Directory for output files
+        log_path: Optional path for log file
+        logger: Optional logger instance
+
+    Returns:
+        Path to the output CSV file
+
+    Raises:
+        ValueError: If inputs are invalid or mutations cannot be processed
+    """
+    gene_fasta = Path(gene_fasta)
+    context_fasta = Path(context_fasta)
+    mutations_csv = Path(mutations_csv)
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    managed_logger = logger is None
+    if logger is None:
+        logger = logging.getLogger("uht_tooling.design_kld")
+        logger.setLevel(logging.INFO)
+        handler: logging.Handler
+        if log_path:
+            handler = logging.FileHandler(log_path, mode="w")
+        else:
+            handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s: %(message)s"))
+        logger.handlers = []
+        logger.addHandler(handler)
+        logger.propagate = False
+
+    try:
+        # Load sequences
+        gene_record = next(SeqIO.parse(str(gene_fasta), "fasta"))
+        context_record = next(SeqIO.parse(str(context_fasta), "fasta"))
+        gene = str(gene_record.seq).upper()
+        context = str(context_record.seq).upper()
+        logger.info("Loaded gene (%s nt) and context (%s nt).", len(gene), len(context))
+
+        # Load mutations
+        df = pd.read_csv(mutations_csv)
+        if "mutations" not in df.columns:
+            raise ValueError("Mutations CSV must contain a 'mutations' column.")
+        mutations = df["mutations"].dropna().tolist()
+        logger.info("Loaded %s mutation entries.", len(mutations))
+
+        # Align gene within context
+        try:
+            gene_offset = context.index(gene)
+            logger.info("Gene aligned at offset %s within context.", gene_offset)
+        except ValueError as exc:
+            message = "Could not align gene within context. No perfect substring match found."
+            logger.error(message)
+            raise ValueError(message) from exc
+
+        full_seq = context
+
+        # Output file
+        results_path = output_dir / "KLD_primers.csv"
+        with results_path.open("w", newline="") as csvfile:
+            writer = csv.writer(csvfile)
+            writer.writerow([
+                "Primer Name", "Sequence", "Tm (binding)", "GC%", "Length", "Notes"
+            ])
+
+            for mutation in mutations:
+                try:
+                    m = mutation
+                    m_del = re.match(r"^([A-Z])(\d+)Del$", m)
+                    m_indel = re.match(r"^([A-Z])(\d+)InDel([A-Z])(\d+)([A-Z]+)$", m)
+                    m_sub = re.match(r"^([A-Z])(\d+)([A-Z])$", m)
+                    m_ins = re.match(r"^([A-Z])(\d+)([A-Z]{2,})$", m)
+                    m_lib = re.match(r"^([A-Z])(\d+):([A-Za-z]{3})$", m)
+
+                    region_start: int
+                    new_seq: str
+                    notes: str = ""
+
+                    if m_del:
+                        # Deletion: remove the codon entirely
+                        wt_aa, pos1 = m_del.group(1), int(m_del.group(2))
+                        region_start = gene_offset + (pos1 - 1) * 3
+                        # For deletion, new_seq is empty - forward primer starts at next codon
+                        new_seq = ""
+                        notes = "Deletion"
+
+                    elif m_indel:
+                        # InDel: replace range with new amino acids
+                        wt1, pos1_s, wt2, pos2_s, ins_aa = m_indel.groups()
+                        pos1, pos2 = int(pos1_s), int(pos2_s)
+                        region_start = gene_offset + (pos1 - 1) * 3
+                        wt_codon = full_seq[region_start : region_start + 3]
+                        new_seq = ""
+                        for aa in ins_aa:
+                            codon = pick_mutant_codon(wt_codon, aa)
+                            if not codon:
+                                logger.error("No codon found for %s->%s", wt1, ins_aa)
+                                raise ValueError(f"No codon found for {wt1}->{ins_aa}")
+                            new_seq += codon
+                        notes = f"InDel: {pos2 - pos1 + 1} AA -> {len(ins_aa)} AA"
+
+                    elif m_ins:
+                        # Insertion: add amino acids after position
+                        wt_aa, pos1_s, ins_str = m_ins.groups()
+                        pos1 = int(pos1_s)
+                        codon_start_old = gene_offset + (pos1 - 1) * 3
+                        wt_codon = full_seq[codon_start_old : codon_start_old + 3]
+                        if ins_str[0] == wt_aa:
+                            # First AA matches WT, so insert after
+                            inserted_aas = ins_str[1:]
+                            region_start = codon_start_old + 3
+                        else:
+                            # Replace WT with insertion
+                            inserted_aas = ins_str
+                            region_start = codon_start_old
+                        new_seq = ""
+                        for aa in inserted_aas:
+                            codon = pick_mutant_codon(wt_codon, aa)
+                            if not codon:
+                                logger.error("No codon for insertion amino acid %s", aa)
+                                raise ValueError(f"No codon for insertion amino acid {aa}")
+                            new_seq += codon
+                        notes = f"Insertion: +{len(inserted_aas)} AA"
+
+                    elif m_sub:
+                        # Substitution: single amino acid change
+                        wt_aa, pos1, mut_aa = m_sub.group(1), int(m_sub.group(2)), m_sub.group(3)
+                        region_start = gene_offset + (pos1 - 1) * 3
+                        wt_codon = full_seq[region_start : region_start + 3]
+                        translated = translate_codon(wt_codon)
+                        if translated != wt_aa:
+                            logger.error(
+                                "Expected %s but found %s at codon %s for mutation %s",
+                                wt_aa, translated, wt_codon, mutation,
+                            )
+                            raise ValueError(
+                                f"For {mutation}: expected {wt_aa}, found {translated} at {wt_codon}"
+                            )
+                        new_seq = pick_mutant_codon(wt_codon, mut_aa)
+                        if not new_seq:
+                            logger.error("No minimal-change codon for %s->%s", wt_aa, mut_aa)
+                            raise ValueError(f"No minimal-change codon for {wt_aa}->{mut_aa}")
+                        notes = f"Substitution: {wt_aa}->{mut_aa}"
+
+                    elif m_lib:
+                        # Library mutation with degenerate codon
+                        wt_aa, pos_str, degenerate_codon = m_lib.groups()
+                        pos = int(pos_str)
+                        degenerate_codon = degenerate_codon.upper()
+
+                        if not is_valid_degenerate_codon(degenerate_codon):
+                            raise ValueError(f"Invalid degenerate codon: {degenerate_codon}")
+
+                        region_start = gene_offset + (pos - 1) * 3
+                        wt_codon = full_seq[region_start : region_start + 3]
+                        translated = translate_codon(wt_codon)
+                        if translated != wt_aa:
+                            logger.error(
+                                "Expected %s but found %s at codon %s for mutation %s",
+                                wt_aa, translated, wt_codon, mutation,
+                            )
+                            raise ValueError(
+                                f"For {mutation}: expected {wt_aa}, found {translated} at {wt_codon}"
+                            )
+
+                        new_seq = degenerate_codon
+
+                        # Log library coverage info
+                        expanded_codons = expand_degenerate_sequence(degenerate_codon)
+                        unique_aas = set(
+                            translate_codon(c) for c in expanded_codons if translate_codon(c) != '?'
+                        )
+                        logger.info(
+                            "Library mutation %s: %d possible codons, %d amino acids",
+                            mutation, len(expanded_codons), len(unique_aas)
+                        )
+                        notes = f"Library: {len(expanded_codons)} codons, {len(unique_aas)} AAs"
+
+                    else:
+                        logger.error("Unknown mutation format: %s", mutation)
+                        raise ValueError(f"Unknown mutation format: {mutation}")
+
+                    # Handle deletion specially - forward primer starts at next position
+                    if m_del:
+                        # For deletion, the forward primer binding region starts
+                        # immediately after the deleted codon
+                        fwd_binding_start = region_start + 3
+
+                        # Find optimal forward binding region
+                        best_fwd = None
+                        best_tm_diff = float('inf')
+                        target_tm = (MIN_TM + MAX_TM) / 2
+
+                        for length in range(MIN_LENGTH, MAX_LENGTH + 1):
+                            binding_end = fwd_binding_start + length
+                            if binding_end > len(full_seq):
+                                break
+                            binding_seq = full_seq[fwd_binding_start:binding_end]
+                            tm = calc_tm_binding_region(binding_seq)
+                            gc = calc_gc_content(binding_seq)
+                            if MIN_TM <= tm <= MAX_TM and MIN_GC <= gc <= MAX_GC:
+                                tm_diff = abs(tm - target_tm)
+                                if tm_diff < best_tm_diff:
+                                    best_tm_diff = tm_diff
+                                    best_fwd = (binding_seq, binding_seq, tm, gc, length)
+
+                        if not best_fwd:
+                            raise ValueError(
+                                f"Cannot find forward primer for deletion {mutation}"
+                            )
+
+                        fwd_seq, fwd_binding, fwd_tm, fwd_gc, fwd_len = best_fwd
+
+                        # Reverse primer design is the same
+                        rev_seq, rev_tm, rev_gc, rev_len = design_reverse_primer(
+                            full_seq, region_start
+                        )
+                    else:
+                        # Standard primer design
+                        fwd_result = design_forward_primer(
+                            full_seq, region_start, new_seq
+                        )
+                        rev_result = design_reverse_primer(full_seq, region_start)
+
+                        # Balance Tms
+                        fwd_result, rev_result = balance_primer_tms(
+                            fwd_result, rev_result, full_seq, region_start, new_seq
+                        )
+
+                        fwd_seq, fwd_binding, fwd_tm, fwd_gc, fwd_len = fwd_result
+                        rev_seq, rev_tm, rev_gc, rev_len = rev_result
+
+                    # Write forward primer
+                    writer.writerow([
+                        f"{mutation}_F",
+                        fwd_seq,
+                        f"{fwd_tm:.1f}",
+                        f"{fwd_gc:.1f}",
+                        fwd_len,
+                        notes,
+                    ])
+
+                    # Write reverse primer
+                    writer.writerow([
+                        f"{mutation}_R",
+                        rev_seq,
+                        f"{rev_tm:.1f}",
+                        f"{rev_gc:.1f}",
+                        rev_len,
+                        "",
+                    ])
+
+                    logger.info(
+                        "Designed KLD primers for %s: F_Tm=%.1f°C, R_Tm=%.1f°C, diff=%.1f°C",
+                        mutation, fwd_tm, rev_tm, abs(fwd_tm - rev_tm)
+                    )
+
+                except Exception as exc:
+                    logger.error("Error processing mutation %s: %s", mutation, exc)
+                    raise
+
+        logger.info("KLD primer design completed successfully. Output written to %s", results_path)
+        return results_path
+
+    finally:
+        if managed_logger and logger:
+            for handler in list(logger.handlers):
+                handler.close()
+                logger.removeHandler(handler)
+            logger.propagate = True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build argument parser for command-line usage."""
+    parser = argparse.ArgumentParser(
+        description="Design KLD (inverse PCR) primers from user-provided inputs."
+    )
+    parser.add_argument(
+        "--gene-fasta",
+        required=True,
+        type=Path,
+        help="Path to FASTA file containing the gene sequence.",
+    )
+    parser.add_argument(
+        "--context-fasta",
+        required=True,
+        type=Path,
+        help="Path to FASTA file containing the plasmid or genomic context.",
+    )
+    parser.add_argument(
+        "--mutations-csv",
+        required=True,
+        type=Path,
+        help="CSV file containing a 'mutations' column with each mutation specification.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        required=True,
+        type=Path,
+        help="Directory where results and logs will be written.",
+    )
+    parser.add_argument(
+        "--log-path",
+        default=None,
+        type=Path,
+        help="Optional path for the run log (defaults to console logging).",
+    )
+    return parser
+
+
+def main(argv: Optional[List[str]] = None):
+    """Main entry point for command-line usage."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    run_design_kld(
+        gene_fasta=args.gene_fasta,
+        context_fasta=args.context_fasta,
+        mutations_csv=args.mutations_csv,
+        output_dir=args.output_dir,
+        log_path=args.log_path,
+    )
+
+
+if __name__ == "__main__":
+    main()

uht_tooling/workflows/design_slim.py

@@ -16,6 +16,41 @@ TARGET_TM = 60.0
 MAX_TM = 70.0
 UPSTREAM_15 = 12
 
+# IUPAC ambiguity codes mapping
+IUPAC_AMBIGUITY = {
+    'A': ['A'], 'C': ['C'], 'G': ['G'], 'T': ['T'],
+    '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'],
+}
+
+VALID_DEGENERATE_BASES = set(IUPAC_AMBIGUITY.keys())
+
+
+def is_valid_degenerate_codon(codon: str) -> bool:
+    """Check if a codon contains only valid IUPAC nucleotide codes."""
+    return len(codon) == 3 and all(b.upper() in VALID_DEGENERATE_BASES for b in codon)
+
+
+def contains_degenerate_bases(seq: str) -> bool:
+    """Return True if sequence contains non-standard (degenerate) bases."""
+    return any(b.upper() not in {'A', 'C', 'G', 'T'} for b in seq)
+
+
+def expand_degenerate_sequence(seq: str) -> list[str]:
+    """Expand a degenerate sequence to all possible standard sequences."""
+    from itertools import product
+    possibilities = [IUPAC_AMBIGUITY.get(b.upper(), [b]) for b in seq]
+    return [''.join(combo) for combo in product(*possibilities)]
+
 
 def codon_table():
     return {
@@ -103,7 +138,12 @@ def pick_mutant_codon(wt_codon, target_aa):
     return best_list[0][0]
 
 
-def calc_tm(seq):
+def calc_tm(seq: str) -> float:
+    """Calculate Tm, using average across expansions for degenerate sequences."""
+    if contains_degenerate_bases(seq):
+        expanded = expand_degenerate_sequence(seq)
+        tms = [mt.Tm_NN(s) for s in expanded]
+        return sum(tms) / len(tms)
     return mt.Tm_NN(seq)
 
 
@@ -266,6 +306,7 @@ def run_design_slim(
                     m_indel = re.match(r"^([A-Z])(\d+)InDel([A-Z])(\d+)([A-Z]+)$", m)
                     m_sub = re.match(r"^([A-Z])(\d+)([A-Z])$", m)
                     m_ins = re.match(r"^([A-Z])(\d+)([A-Z]{2,})$", m)
+                    m_lib = re.match(r"^([A-Z])(\d+):([A-Za-z]{3})$", m)
 
                     if m_del:
                         wt_aa, pos1 = m_del.group(1), int(m_del.group(2))
@@ -328,6 +369,39 @@ def run_design_slim(
                         if not new_seq:
                             logger.error("No minimal-change codon for %s->%s", wt_aa, mut_aa)
                             raise ValueError(f"No minimal-change codon for {wt_aa}->{mut_aa}")
+                    elif m_lib:
+                        wt_aa, pos_str, degenerate_codon = m_lib.groups()
+                        pos = int(pos_str)
+                        degenerate_codon = degenerate_codon.upper()
+
+                        # Validate the degenerate codon
+                        if not is_valid_degenerate_codon(degenerate_codon):
+                            raise ValueError(f"Invalid degenerate codon: {degenerate_codon}")
+
+                        region_start = gene_offset + (pos - 1) * 3
+                        old_len = 3
+
+                        # Validate WT amino acid (same as substitution validation)
+                        wt_codon = full_seq[region_start : region_start + 3]
+                        translated = translate_codon(wt_codon)
+                        if translated != wt_aa:
+                            logger.error(
+                                "Expected %s but found %s at codon %s for mutation %s",
+                                wt_aa, translated, wt_codon, mutation,
+                            )
+                            raise ValueError(
+                                f"For {mutation}: expected {wt_aa}, found {translated} at {wt_codon}"
+                            )
+
+                        new_seq = degenerate_codon
+
+                        # Log library coverage info
+                        expanded_codons = expand_degenerate_sequence(degenerate_codon)
+                        unique_aas = set(translate_codon(c) for c in expanded_codons if translate_codon(c) != '?')
+                        logger.info(
+                            "Library mutation %s: %d possible codons, %d amino acids",
+                            mutation, len(expanded_codons), len(unique_aas)
+                        )
                     else:
                         logger.error("Unknown mutation format: %s", mutation)
                         raise ValueError(f"Unknown mutation format: {mutation}")

uht_tooling/workflows/gui.py

@@ -22,6 +22,7 @@ except ImportError as exc:  # pragma: no cover - handled at runtime
     ) from exc
 
 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.mut_rate import run_ep_library_profile
 from uht_tooling.workflows.mutation_caller import run_mutation_caller
@@ -187,6 +188,47 @@ def run_gui_design_slim(
         _clean_temp_path(locals().get("output_dir", Path()))
 
 
+def run_gui_design_kld(
+    template_gene_content: str,
+    context_content: str,
+    mutations_text: str,
+) -> Tuple[str, Optional[str]]:
+    try:
+        gene_seq = _ensure_text(template_gene_content, "Template gene sequence")
+        context_seq = _ensure_text(context_content, "Context sequence")
+        mutation_lines = [line.strip() for line in mutations_text.splitlines() if line.strip()]
+        if not mutation_lines:
+            raise ValueError("Provide at least one mutation (e.g., A123G).")
+
+        work_dir = Path(tempfile.mkdtemp(prefix="uht_gui_kld_work_"))
+        output_dir = Path(tempfile.mkdtemp(prefix="uht_gui_kld_out_"))
+
+        gene_fasta = work_dir / "template_gene.fasta"
+        context_fasta = work_dir / "context.fasta"
+        mutations_csv = work_dir / "mutations.csv"
+
+        gene_fasta.write_text(f">template\n{gene_seq}\n")
+        context_fasta.write_text(f">context\n{context_seq}\n")
+        mutations_csv.write_text("mutations\n" + "\n".join(mutation_lines) + "\n")
+
+        result_csv = run_design_kld(
+            gene_fasta=gene_fasta,
+            context_fasta=context_fasta,
+            mutations_csv=mutations_csv,
+            output_dir=output_dir,
+        )
+
+        summary = _format_header("KLD Primer Design") + _preview_csv(result_csv)
+        archive = _zip_paths([output_dir], "kld")
+        return summary, str(archive)
+    except Exception as exc:  # pragma: no cover
+        _LOGGER.exception("KLD GUI failure")
+        return f"⚠️ Error: {exc}", None
+    finally:
+        _clean_temp_path(locals().get("work_dir", Path()))
+        _clean_temp_path(locals().get("output_dir", Path()))
+
+
 def run_gui_design_gibson(
     template_gene_content: str,
     context_content: str,
@@ -566,8 +608,8 @@ def create_gui() -> gr.Blocks:
         with gr.Tab("Nextera XT"):  # --- Nextera ---
             gr.Markdown(
                 textwrap.dedent(
-                    """
-                    ### Illumina-Compatible Primer Design
+                """
+                ### Illumina-Compatible Primer Design
                     Generates Nextera XT-ready primers from forward/reverse binding regions. The workflow preloads 12 i5 and 12 i7 indices (144 combinations) and mirrors the “One-PCR-to-flowcell” process described in the README.
 
                     **Inputs**
@@ -577,7 +619,7 @@ def create_gui() -> gr.Blocks:
                     **Outputs**
                     - CSV with i5/i7 indices, primer sequences, and ordering-ready metadata.
                     - Run log noting index selection and any validation warnings.
-                    """
+                """
                 )
             )
             forward = gr.Textbox(label="Forward primer (5'→3')")
@@ -599,24 +641,25 @@ def create_gui() -> gr.Blocks:
                         - Confirm primer depletion via electrophoresis (e.g., BioAnalyzer) before sequencing prep.
                         """
                     )
-                )
+            )
 
         with gr.Tab("SLIM"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
-                    ### Sequence-Ligation Independent Mutagenesis
+                """
+                ### Sequence-Ligation Independent Mutagenesis
                     Designs paired short/long primers to introduce targeted mutations by SLIM cloning, matching the workflow outlined in the README.
 
                     **Inputs**
                     - Target gene coding sequence (FASTA content).
                     - Plasmid or genomic context containing the gene.
                     - Mutations (one per line, e.g. substitution `A123G`, deletion `T241Del`, insertion `T241TS`).
+                    - Library codons are supported via `AApos:COD` syntax (e.g. `R57:NNK`).
 
                     **Outputs**
                     - `SLIM_primers.csv` with primer sequences and annealing temperatures.
                     - Log file capturing primer QC and any design warnings.
-                    """
+                """
                 )
             )
             slim_gene = gr.Textbox(label="Gene sequence", lines=4)
@@ -640,13 +683,44 @@ def create_gui() -> gr.Blocks:
                         4. Transform directly into NEB 5-alpha or BL21 (DE3); the method scales to dozens of mutants simultaneously.
                         """
                     )
+            )
+
+        with gr.Tab("KLD"):
+            gr.Markdown(
+                textwrap.dedent(
+                """
+                ### KLD (Inverse PCR) Primer Design
+                    Designs inverse-PCR primers for KLD cloning. Forward primers carry the mutation at the 5' end, and reverse primers bind upstream to re-amplify the full plasmid.
+
+                    **Inputs**
+                    - Target gene coding sequence (FASTA content).
+                    - Plasmid or genomic context containing the gene.
+                    - Mutations (one per line, e.g. substitution `A123G`, deletion `T241Del`, insertion `T241TS`).
+                    - Library codons are supported via `AApos:COD` syntax (e.g. `R57:NNK`).
+
+                    **Outputs**
+                    - `KLD_primers.csv` with primer sequences and annealing temperatures.
+                    - Log file capturing primer QC and any design warnings.
+                """
                 )
+            )
+            kld_gene = gr.Textbox(label="Gene sequence", lines=4)
+            kld_context = gr.Textbox(label="Plasmid context", lines=4)
+            kld_mutations = gr.Textbox(label="Mutations (one per line)", lines=6)
+            kld_btn = gr.Button("Design KLD primers", variant="primary")
+            kld_summary = gr.Markdown(label="Summary")
+            kld_download = gr.File(label="Download primers", file_count="single")
+            kld_btn.click(
+                fn=run_gui_design_kld,
+                inputs=[kld_gene, kld_context, kld_mutations],
+                outputs=[kld_summary, kld_download],
+            )
 
         with gr.Tab("Gibson"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
-                    ### Gibson Assembly Primer Design
+                """
+                ### Gibson Assembly Primer Design
                     Plans primer sets and assembly steps for Gibson mutagenesis, supporting multi-mutation constructs using the `+` syntax (e.g. `A123G+T150A`).
 
                     **Inputs**
@@ -658,7 +732,7 @@ def create_gui() -> gr.Blocks:
                     - Primer CSV with overlap sequences and melting temperatures.
                     - Assembly plan CSV detailing fragment combinations.
                     - Log summarising design decisions and any warnings about overlapping regions.
-                    """
+                """
                 )
             )
             gibson_gene = gr.Textbox(label="Gene sequence", lines=4)
@@ -681,13 +755,13 @@ def create_gui() -> gr.Blocks:
                         - When replacing entire codons (e.g. `L46GP`), ensure the plasmid context covers both flanks to maintain overlap.
                         """
                     )
-                )
+            )
 
         with gr.Tab("Mutation Caller"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
-                    ### Long-read Mutation Analysis
+                """
+                ### Long-read Mutation Analysis
                     Extracts coding regions bounded by user-defined flanks, aligns them to the template, and reports amino-acid substitutions alongside co-occurrence summaries.
 
                     **Required inputs**
@@ -695,8 +769,8 @@ def create_gui() -> gr.Blocks:
                     - Template FASTA: coding sequence used as the reference for alignment.
                     - Flank sequences: short 8–12 bp motifs immediately upstream and downstream of the gene.
                     - Gene length bounds: acceptable size window (in nucleotides) for the extracted gene segment.
-                    """
-                )
+                """
+            )
             )
             with gr.Row():
                 mc_fastq = gr.File(
@@ -753,12 +827,12 @@ def create_gui() -> gr.Blocks:
                         - Outputs mirror the CLI version: per-sample directories with CSV summaries, JSON co-occurrence graphs, QC plots, and a detailed `run.log`.
                         """
                     )
-                )
+            )
 
         with gr.Tab("UMI Hunter"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
+                """
                     ### UMI–Gene Pair Clustering
                     Detects UMI barcodes, extracts paired gene inserts, clusters reads by UMI identity, and emits consensus sequences with abundance tables.
 
@@ -768,8 +842,8 @@ def create_gui() -> gr.Blocks:
                     - UMI and gene flank sequences marking the barcode and insert boundaries.
                     - UMI length bounds plus clustering thresholds.
                     - Minimum reads per cluster to keep (clusters below the threshold are reported but no consensus is generated).
-                    """
-                )
+                """
+            )
             )
             with gr.Row():
                 umi_fastq = gr.File(
@@ -862,19 +936,19 @@ def create_gui() -> gr.Blocks:
                         - Outputs include per-sample summaries, consensus FASTA files, cluster membership tables, QC plots, and logs mirroring the CLI workflow.
                         """
                     )
-                )
+            )
 
         with gr.Tab("Profile Inserts"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
+                """
                     ### Probe-Guided Insert Profiling
                     Characterises inserts demarcated by user-supplied upstream/downstream probes, extracts sequences, and produces QC plots plus summary tables.
 
                     **Required inputs**
                     - FASTQ reads containing the inserts of interest.
                     - One or more probe pairs: 5'→3' sequences for the upstream and downstream anchors (reverse complements are matched automatically).
-                    """
+                """
                 )
             )
             probes_table = gr.Dataframe(
@@ -916,13 +990,13 @@ def create_gui() -> gr.Blocks:
                         - Logs are stored alongside the results so runs remain fully reproducible.
                         """
                     )
-                )
+            )
 
         with gr.Tab("EP Library Profile"):
             gr.Markdown(
                 textwrap.dedent(
-                    """
-                    ### Library Profiling Without UMIs
+                """
+                ### Library Profiling Without UMIs
                     Estimates background and target mutation rates for enzyme evolution libraries without UMI barcodes.
 
                     **Inputs**
@@ -934,7 +1008,7 @@ def create_gui() -> gr.Blocks:
                     - Per-sample directories with coverage tables, mutation rate statistics, and QC plots.
                     - `master_summary.txt` aggregating condition-level metrics.
                     - Verbose logs recording alignment commands and rate calculations.
-                    """
+                """
                 )
             )
             ep_fastq = gr.File(
@@ -963,7 +1037,7 @@ def create_gui() -> gr.Blocks:
                         - Download the archive to inspect per-sample plots, TSV summaries, the consensus summary, and logs for troubleshooting.
                         """
                     )
-                )
+            )
 
         gr.Markdown(
             textwrap.dedent(

uht_tooling/workflows/mut_rate.py

@@ -566,10 +566,10 @@ def compute_consensus_aa_mutation(
 ) -> Tuple[Optional[dict], List[dict]]:
     """
     Derive a consensus amino-acid mutation estimate across Q-score thresholds.
-
+    
     Each threshold must meet a minimum coverage requirement. The consensus is a
     precision-weighted average (weights = 1 / std_aa_mutations).
-
+    
     Returns:
         consensus_info (dict or None)
             {
@@ -648,7 +648,7 @@ def compute_consensus_aa_mutation(
         consensus_std,
         thresholds,
     )
-
+    
     return consensus_info, valid_results
 
 def create_simple_qc_plots(quality_thresholds, qc_results, results_dir, consensus_info=None):
@@ -2170,12 +2170,12 @@ def run_main_analysis_for_qscore(fastq_path, qscore, qscore_desc, sample_name, w
             color="gray",
             transform=ax3.transAxes,
         )
-    
-    ax3.set_title("AA Mutation Distribution", fontsize=14, fontweight='bold')
-    ax3.set_xlabel("Number of AA Mutations", fontsize=12)
-    ax3.set_ylabel("Density", fontsize=12)
-    ax3.spines['top'].set_visible(False)
-    ax3.spines['right'].set_visible(False)
+        
+        ax3.set_title("AA Mutation Distribution", fontsize=14, fontweight='bold')
+        ax3.set_xlabel("Number of AA Mutations", fontsize=12)
+        ax3.set_ylabel("Density", fontsize=12)
+        ax3.spines['top'].set_visible(False)
+        ax3.spines['right'].set_visible(False)
 
     # Save the combined figure as both PNG and PDF
     panel_path_png = os.path.join(qscore_results_dir, "summary_panels.png")

{uht_tooling-0.1.7.dist-info → uht_tooling-0.1.9.dist-info}/METADATA

@@ -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.dist-info → uht_tooling-0.1.9.dist-info}/RECORD

@@ -1,17 +1,18 @@
 uht_tooling/__init__.py,sha256=hf0tJaa4_9y9aYb8OB1FtJh1FOuX08dQ6_MCveWFNAc,242
-uht_tooling/cli.py,sha256=XnpJbMiuB3g5GL-d2bLf4TsDsd9eWDG-tjaAaMnAPTk,13008
+uht_tooling/cli.py,sha256=3QUxYBFqhQyeZ9xM_JTlqhr_UJhb_PRj7Y_UMH5Tslc,14366
 uht_tooling/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 uht_tooling/workflows/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 uht_tooling/workflows/design_gibson.py,sha256=SQEThq6dxPMPCsUrwqMUaG5I-diE9jUXPRii9Y7O_7U,13617
-uht_tooling/workflows/design_slim.py,sha256=Qeh8N32kmVFZvohmTlBudJsLzOqLy4XcY3aXbkP-sFQ,14421
-uht_tooling/workflows/gui.py,sha256=P4FdZWsS0NLX5VmOZZ-WO-biVEhbfa6M1gY6DFcgR7k,43153
-uht_tooling/workflows/mut_rate.py,sha256=j8QzYe9QrT_yyhSYUbH3MHyvUp61U_h0w1bEd8b3aFI,109038
+uht_tooling/workflows/design_kld.py,sha256=SWbKVfi1JgJ7cN9TU3dLEiYmZT7LQiGL_mUZ-n3PdzE,27368
+uht_tooling/workflows/design_slim.py,sha256=wGXnmaJCzlAZTjf2SRupwt_3MBl5cgZr1O9nnMQyoGo,17767
+uht_tooling/workflows/gui.py,sha256=FpzxgjOo8SQCPJRM7ltVLk3bcwZ_AxjQzZxwz7J_c1M,46436
+uht_tooling/workflows/mut_rate.py,sha256=Sv4OU68RNTOOsKV0QSbJ7FOgxh3vQeUeib_5mrXqyHg,109074
 uht_tooling/workflows/mutation_caller.py,sha256=BczuNATOSUcmlw-x6qTzEQfW8MBbvGclEyqiQiBX0cg,16222
 uht_tooling/workflows/nextera_designer.py,sha256=8MZ_DyQ0JwPojXH5mZ6bAGAkqki_0qQGac45T_Ll8FQ,6170
 uht_tooling/workflows/profile_inserts.py,sha256=C-SZ10YefiV_4QZbo1oEkI4qYipwaYqPP5jF-MC5O58,16947
 uht_tooling/workflows/umi_hunter.py,sha256=baycWycqVzUfMp5u2WZdHRl0sNuykTjy-iqtj5ahucU,15075
-uht_tooling-0.1.7.dist-info/METADATA,sha256=YuHkyuvRdznGgVH111anZaqsOBt9k-szz1vJGF-eWy0,12925
-uht_tooling-0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-uht_tooling-0.1.7.dist-info/entry_points.txt,sha256=t3_bMkEnlnV4vd6nrjNQxHDsHzHHoZenhmxuIYLcRBY,53
-uht_tooling-0.1.7.dist-info/top_level.txt,sha256=iTCCiSn0OjrTx1VOdxXhUlPi1TR9LxaJEZJoMyRcv9c,12
-uht_tooling-0.1.7.dist-info/RECORD,,
+uht_tooling-0.1.9.dist-info/METADATA,sha256=mMC92ln1dMYhDQFlKRfBsMMsMVvy0p0LDY8s6aX-4Ig,16399
+uht_tooling-0.1.9.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+uht_tooling-0.1.9.dist-info/entry_points.txt,sha256=t3_bMkEnlnV4vd6nrjNQxHDsHzHHoZenhmxuIYLcRBY,53
+uht_tooling-0.1.9.dist-info/top_level.txt,sha256=iTCCiSn0OjrTx1VOdxXhUlPi1TR9LxaJEZJoMyRcv9c,12
+uht_tooling-0.1.9.dist-info/RECORD,,

{uht_tooling-0.1.7.dist-info → uht_tooling-0.1.9.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any