uht-tooling 0.1.2__py3-none-any.whl

uht_tooling/workflows/umi_hunter.py

@@ -0,0 +1,412 @@
+import argparse
+import csv
+import gzip
+import logging
+import os
+import re
+import subprocess
+import tempfile
+from collections import Counter
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+import pandas as pd
+from Bio import AlignIO, SeqIO
+from Bio.Align.Applications import MafftCommandline
+from Bio.Seq import Seq
+from Bio.SeqRecord import SeqRecord
+from tqdm import tqdm
+
+
+def reverse_complement(seq: str) -> str:
+    return seq.translate(str.maketrans("ACGTacgt", "TGCAtgca"))[::-1]
+
+
+def load_flank_config(config_csv: Path) -> dict:
+    df = pd.read_csv(config_csv)
+    return {
+        "umi_start": df.loc[0, "umi_flanks"],
+        "umi_end": df.loc[1, "umi_flanks"],
+        "umi_min": int(df.loc[0, "umi_min_max"]),
+        "umi_max": int(df.loc[1, "umi_min_max"]),
+        "gene_start": df.loc[0, "gene_flanks"],
+        "gene_end": df.loc[1, "gene_flanks"],
+    }
+
+
+def build_patterns(cfg: dict) -> tuple[re.Pattern, re.Pattern]:
+    pattern_umi = re.compile(
+        rf"{cfg['umi_start']}([ACGT]{{{cfg['umi_min']},{cfg['umi_max']}}}){cfg['umi_end']}",
+        re.IGNORECASE,
+    )
+    pattern_gene = re.compile(rf"{cfg['gene_start']}(.*?){cfg['gene_end']}", re.IGNORECASE)
+    return pattern_umi, pattern_gene
+
+
+def extract_read_info(
+    seq: str,
+    pattern_umi: re.Pattern,
+    pattern_gene: re.Pattern,
+    logger: logging.Logger,
+) -> tuple[Optional[str], Optional[str]]:
+    umi_match = pattern_umi.search(seq)
+    gene_match = pattern_gene.search(seq)
+    if umi_match and gene_match:
+        return umi_match.group(1), gene_match.group(1)
+    rev_seq = reverse_complement(seq)
+    umi_match = pattern_umi.search(rev_seq)
+    gene_match = pattern_gene.search(rev_seq)
+    if umi_match and gene_match:
+        return umi_match.group(1), gene_match.group(1)
+    logger.debug("Failed to extract UMI/gene from read")
+    return None, None
+
+
+def process_fastq(
+    file_path: Path,
+    pattern_umi: re.Pattern,
+    pattern_gene: re.Pattern,
+    logger: logging.Logger,
+) -> tuple[int, Dict[str, List[str]]]:
+    read_count = 0
+    umi_info: Dict[str, List[str]] = {}
+    extracted = 0
+    with gzip.open(file_path, "rt") as handle:
+        while True:
+            header = handle.readline()
+            if not header:
+                break
+            seq = handle.readline().strip()
+            handle.readline()
+            handle.readline()
+            read_count += 1
+
+            umi, gene = extract_read_info(seq, pattern_umi, pattern_gene, logger)
+            if umi and gene:
+                umi_info.setdefault(umi, []).append(gene)
+                extracted += 1
+            if read_count % 100000 == 0:
+                logger.info("Processed %s reads so far in %s", read_count, file_path.name)
+    logger.info(
+        "Finished reading %s: total reads=%s, extracted pairs=%s",
+        file_path,
+        read_count,
+        extracted,
+    )
+    return read_count, umi_info
+
+
+def levenshtein(s1: str, s2: str) -> int:
+    if len(s1) < len(s2):
+        return levenshtein(s2, s1)
+    if len(s2) == 0:
+        return len(s1)
+    previous_row = list(range(len(s2) + 1))
+    for i, c1 in enumerate(s1):
+        current_row = [i + 1]
+        for j, c2 in enumerate(s2):
+            insertions = previous_row[j + 1] + 1
+            deletions = current_row[j] + 1
+            substitutions = previous_row[j] + (c1 != c2)
+            current_row.append(min(insertions, deletions, substitutions))
+        previous_row = current_row
+    return previous_row[-1]
+
+
+def percent_identity(seq1: str, seq2: str) -> float:
+    max_len = max(len(seq1), len(seq2))
+    if max_len == 0:
+        return 1.0
+    dist = levenshtein(seq1, seq2)
+    return (max_len - dist) / max_len
+
+
+def cluster_umis(
+    umi_info: Dict[str, List[str]],
+    threshold: float,
+    logger: logging.Logger,
+) -> List[dict]:
+    logger.info("Clustering %s unique UMIs with threshold %.2f", len(umi_info), threshold)
+    sorted_umis = sorted(umi_info.items(), key=lambda item: len(item[1]), reverse=True)
+    clusters: List[dict] = []
+    for umi, gene_list in sorted_umis:
+        count = len(gene_list)
+        for cluster in clusters:
+            if percent_identity(umi, cluster["rep"]) >= threshold:
+                cluster["total_count"] += count
+                cluster["members"][umi] = count
+                cluster["gene_seqs"].extend(gene_list)
+                break
+        else:
+            clusters.append(
+                {
+                    "rep": umi,
+                    "total_count": count,
+                    "members": {umi: count},
+                    "gene_seqs": list(gene_list),
+                }
+            )
+    logger.info("Formed %s UMI clusters", len(clusters))
+    return clusters
+
+
+def run_mafft_alignment(reference: SeqRecord, gene_seqs: List[str]) -> AlignIO.MultipleSeqAlignment:
+    with tempfile.NamedTemporaryFile(mode="w", delete=False) as tmp_in:
+        fasta_in = tmp_in.name
+        reference.id = "REF_template"
+        reference.description = ""
+        SeqIO.write(reference, tmp_in, "fasta")
+        for i, seq in enumerate(gene_seqs):
+            record = SeqRecord(Seq(seq), id=f"seq{i}", description="")
+            SeqIO.write(record, tmp_in, "fasta")
+
+    mafft_cline = MafftCommandline(input=fasta_in)
+    proc = subprocess.Popen(
+        str(mafft_cline),
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+    )
+    stdout, stderr = proc.communicate()
+    if proc.returncode != 0:
+        os.remove(fasta_in)
+        raise RuntimeError(f"MAFFT failed with exit code {proc.returncode}:\n{stderr}")
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False) as tmp_out:
+        fasta_out = tmp_out.name
+        tmp_out.write(stdout)
+
+    alignment = AlignIO.read(fasta_out, "fasta")
+    os.remove(fasta_in)
+    os.remove(fasta_out)
+    return alignment
+
+
+def generate_consensus(
+    reference_record: SeqRecord,
+    gene_seqs: List[str],
+    mutation_threshold: float,
+    logger: logging.Logger,
+) -> str:
+    if not gene_seqs:
+        return ""
+    alignment = run_mafft_alignment(reference_record, gene_seqs)
+    ref_record = None
+    other_records: List[SeqRecord] = []
+    for record in alignment:
+        if record.id == "REF_template":
+            ref_record = record
+        else:
+            other_records.append(record)
+    if ref_record is None or not other_records:
+        logger.warning("Reference or read sequences missing from alignment output")
+        return ""
+
+    consensus_chars: List[str] = []
+    num_reads = len(other_records)
+    length = alignment.get_alignment_length()
+    for idx in range(length):
+        ref_base = ref_record.seq[idx]
+        col_bases = [record.seq[idx] for record in other_records]
+        counts = Counter(col_bases)
+        most_common, count = counts.most_common(1)[0]
+        freq = count / num_reads
+        if most_common != ref_base and freq >= mutation_threshold:
+            consensus_chars.append(most_common)
+        else:
+            consensus_chars.append(ref_base)
+    return "".join(consensus_chars).replace("-", "")
+
+
+def write_umi_csv(output_file: Path, clusters: List[dict]):
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    with output_file.open("w", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["Cluster Representative", "Total Count", "Members"])
+        for cluster in clusters:
+            members_str = "; ".join(f"{umi}:{count}" for umi, count in cluster["members"].items())
+            writer.writerow([cluster["rep"], cluster["total_count"], members_str])
+
+
+def write_gene_csv(
+    output_file: Path,
+    clusters: List[dict],
+    reference_record: SeqRecord,
+    mutation_threshold: float,
+    logger: logging.Logger,
+) -> List[SeqRecord]:
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    ungapped_ref_length = len(str(reference_record.seq).replace("-", ""))
+    consensus_records: List[SeqRecord] = []
+    with output_file.open("w", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(
+            ["Cluster Representative", "Total Count", "Consensus Gene", "Length Difference", "Members"]
+        )
+        clusters_to_align = [cluster for cluster in clusters if cluster["total_count"] > 0]
+        for idx, cluster in enumerate(tqdm(clusters_to_align, desc="Processing UMI clusters", unit="cluster")):
+            consensus = generate_consensus(reference_record, cluster["gene_seqs"], mutation_threshold, logger)
+            length_diff = len(consensus) - ungapped_ref_length
+            members_str = "; ".join(f"{umi}:{count}" for umi, count in cluster["members"].items())
+            writer.writerow([cluster["rep"], cluster["total_count"], consensus, length_diff, members_str])
+            record_id = f"{cluster['rep']}_cluster{idx + 1}"
+            consensus_records.append(
+                SeqRecord(Seq(consensus), id=record_id, description=f"Length diff: {length_diff}")
+            )
+    return consensus_records
+
+
+def run_umi_hunter(
+    template_fasta: Path,
+    config_csv: Path,
+    fastq_files: Sequence[Path],
+    output_dir: Path,
+    umi_identity_threshold: float = 0.9,
+    consensus_mutation_threshold: float = 0.7,
+    log_path: Optional[Path] = None,
+    logger: Optional[logging.Logger] = None,
+) -> List[Dict[str, Path]]:
+    template_fasta = Path(template_fasta)
+    config_csv = Path(config_csv)
+    fastq_files = [Path(fq) for fq in fastq_files]
+    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.umi_hunter")
+        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:
+        if not fastq_files:
+            raise ValueError("No FASTQ files provided.")
+
+        cfg = load_flank_config(config_csv)
+        pattern_umi, pattern_gene = build_patterns(cfg)
+        reference_record = next(SeqIO.parse(str(template_fasta), "fasta"))
+
+        results: List[Dict[str, Path]] = []
+
+        for fastq in fastq_files:
+            if not fastq.exists():
+                logger.warning("FASTQ file %s not found; skipping.", fastq)
+                continue
+            sample_base = fastq.stem.replace(".fastq", "")
+            sample_dir = output_dir / sample_base
+            sample_dir.mkdir(parents=True, exist_ok=True)
+
+            read_count, umi_info = process_fastq(fastq, pattern_umi, pattern_gene, logger)
+            if not umi_info:
+                logger.warning("No UMIs extracted for %s; skipping.", fastq)
+                continue
+
+            clusters = cluster_umis(umi_info, umi_identity_threshold, logger)
+            umi_csv = sample_dir / f"{sample_base}_UMI_clusters.csv"
+            write_umi_csv(umi_csv, clusters)
+
+            gene_csv = sample_dir / f"{sample_base}_gene_consensus.csv"
+            consensus_records = write_gene_csv(
+                gene_csv,
+                clusters,
+                reference_record,
+                consensus_mutation_threshold,
+                logger,
+            )
+
+            fasta_out = sample_dir / f"{sample_base}_consensuses.fasta"
+            SeqIO.write(consensus_records, fasta_out, "fasta")
+
+            results.append(
+                {
+                    "sample": sample_base,
+                    "directory": sample_dir,
+                    "umi_csv": umi_csv,
+                    "gene_csv": gene_csv,
+                    "fasta": fasta_out,
+                    "reads": read_count,
+                    "clusters": len(clusters),
+                }
+            )
+
+        if not results:
+            logger.warning("No UMI hunter outputs generated.")
+        return results
+    finally:
+        if managed_logger and logger:
+            for handler in list(logger.handlers):
+                handler.close()
+                logger.removeHandler(handler)
+            logger.propagate = True
+
+
+def expand_fastq_inputs(inputs: Iterable[str]) -> List[Path]:
+    paths: List[Path] = []
+    for item in inputs:
+        if any(ch in item for ch in "*?[]"):
+            paths.extend(Path().glob(item))
+        else:
+            paths.append(Path(item))
+    unique_paths: List[Path] = []
+    seen = set()
+    for path in paths:
+        resolved = path.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            unique_paths.append(path)
+    return unique_paths
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Cluster UMIs and generate consensus sequences from long-read data.")
+    parser.add_argument("--template-fasta", required=True, type=Path, help="Template FASTA file.")
+    parser.add_argument("--config-csv", required=True, type=Path, help="CSV describing UMI and gene flanks.")
+    parser.add_argument(
+        "--fastq",
+        required=True,
+        nargs="+",
+        help="One or more FASTQ(.gz) paths or glob patterns.",
+    )
+    parser.add_argument("--output-dir", required=True, type=Path, help="Directory for per-sample outputs.")
+    parser.add_argument(
+        "--umi-identity-threshold",
+        type=float,
+        default=0.9,
+        help="UMI clustering identity threshold (default: 0.9).",
+    )
+    parser.add_argument(
+        "--consensus-mutation-threshold",
+        type=float,
+        default=0.7,
+        help="Consensus mutation threshold for MAFFT-derived consensus (default: 0.7).",
+    )
+    parser.add_argument("--log-path", default=None, type=Path, help="Optional log file path.")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    fastq_files = expand_fastq_inputs(args.fastq)
+    run_umi_hunter(
+        template_fasta=args.template_fasta,
+        config_csv=args.config_csv,
+        fastq_files=fastq_files,
+        output_dir=args.output_dir,
+        umi_identity_threshold=args.umi_identity_threshold,
+        consensus_mutation_threshold=args.consensus_mutation_threshold,
+        log_path=args.log_path,
+    )
+
+
+if __name__ == "__main__":
+    main()

uht_tooling-0.1.2.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: uht-tooling
+Version: 0.1.2
+Summary: Tooling for ultra-high throughput screening workflows.
+Author: Matt115A
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: biopython==1.85
+Requires-Dist: fuzzywuzzy==0.18.0
+Requires-Dist: matplotlib==3.10.7
+Requires-Dist: pandas==2.3.3
+Requires-Dist: python-Levenshtein==0.27.3
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: pysam==0.23.3
+Requires-Dist: scipy==1.15.3
+Requires-Dist: seaborn==0.13.2
+Requires-Dist: tabulate==0.9.0
+Requires-Dist: tqdm==4.67.1
+Requires-Dist: typer==0.20.0
+Provides-Extra: gui
+Requires-Dist: gradio==5.49.1; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.0; extra == "dev"
+Requires-Dist: black==25.9.0; extra == "dev"
+Requires-Dist: ruff==0.14.4; extra == "dev"
+
+# uht-tooling
+
+Automation helpers for ultra-high-throughput molecular biology workflows. The package ships both a Typer-based CLI and an optional Gradio GUI that wrap the same workflow code paths.
+
+---
+
+## Installation
+
+### Quick install (recommended, easiest file maintainance)
+```bash
+python -m pip install "uht-tooling[gui]"
+```
+
+This installs the core workflows plus the optional GUI dependencies (Gradio, pandas). Omit the `[gui]` extras if you only need the CLI:
+
+```bash
+python -m pip install uht-tooling
+```
+
+### Development install
+```bash
+git clone https://github.com/Matt115A/uht-tooling.git
+cd uht-tooling
+python -m pip install -e ".[gui,dev]"
+```
+
+The editable install exposes the latest sources, while the `dev` extras add linting and test tooling.
+
+---
+
+## Directory layout
+
+- Reference inputs live under `data/<workflow>/`.
+- Outputs (CSV, FASTA, plots, logs) are written to `results/<workflow>/`.
+- All workflows log to `results/<workflow>/run.log` for reproducibility and debugging.
+
+---
+
+## Command-line interface
+
+The CLI is exposed as the `uht-tooling` executable. List the available commands:
+
+```bash
+uht-tooling --help
+```
+
+Each command mirrors a workflow module. Common entry points:
+
+| Command | Purpose |
+| --- | --- |
+| `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-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 alleles. |
+| `uht-tooling ep-library-profile` | Measure mutation rates without UMIs. |
+| `uht-tooling profile-inserts` | Extract inserts defined by probe pairs. |
+
+Each command provides detailed help, including option descriptions and expected file formats:
+
+```bash
+uht-tooling mutation-caller --help
+```
+
+You can pass multiple FASTQ paths using repeated `--fastq` options or glob patterns. Optional `--log-path` flags redirect logs if you prefer a location outside the default results directory.
+
+---
+
+## Workflow reference
+
+### Nextera XT primer design
+
+1. Prepare `data/nextera_designer/nextera_designer.csv` with a `binding_region` column. Row 1 should contain the forward region, row 2 the reverse region, both in 5'→3' orientation.
+2. Optional: supply a YAML overrides file for index lists/prefixes via `--config`.
+3. Run:
+   ```bash
+   uht-tooling nextera-primers \
+     --binding-csv data/nextera_designer/nextera_designer.csv \
+     --output-csv results/nextera_designer/nextera_xt_primers.csv
+   ```
+4. Primer CSVs will be written to `results/nextera_designer/`, accompanied by a log file.
+
+The helper is preloaded with twelve i5 and twelve i7 indices, enabling up to 144 unique amplicons. Downstream lab workflow suggestions (qPCR monitoring, SPRIselect cleanup) remain unchanged from earlier releases.
+
+#### Wet-lab workflow notes
+
+- Perform the initial amplification with an i5/i7 primer pair and monitor a small aliquot by qPCR. Cap thermocycling early so you only generate ~10% of the theoretical yield—this minimizes amplification bias.
+- Purify the product with SPRIselect beads at approximately a 0.65:1 bead:DNA volume ratio to remove residual primers and short fragments.
+- Confirm primer removal using electrophoresis (e.g., BioAnalyzer DNA chip) before moving to sequencing prep.
+
+### SLIM primer design
+
+- Inputs:
+  - `data/design_slim/slim_template_gene.fasta`
+  - `data/design_slim/slim_context.fasta`
+  - `data/design_slim/slim_target_mutations.csv` (single `mutations` column)
+- Run:
+  ```bash
+  uht-tooling design-slim \
+    --gene-fasta data/design_slim/slim_template_gene.fasta \
+    --context-fasta data/design_slim/slim_context.fasta \
+    --mutations-csv data/design_slim/slim_target_mutations.csv \
+    --output-dir results/design_slim/
+  ```
+- Output: `results/design_slim/SLIM_primers.csv` plus logs.
+
+Mutation nomenclature examples:
+- `A123G` (substitution)
+- `T241Del` (deletion)
+- `T241TS` (insert Ser after Thr241)
+- `L46GP` (replace Leu46 with Gly-Pro)
+
+#### Experimental blueprint
+
+- Hands-on time is approximately three hours (excluding protein purification), with mutant protein obtainable in roughly three days.
+- Conduct two PCRs per mutant set: (A) long forward with short reverse and (B) long reverse with short forward.
+- 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.
+
+### Gibson assembly primers
+
+- Inputs mirror the SLIM workflow but use `data/design_gibson/`.
+- Link sub-mutations with `+` to specify multi-mutation assemblies (e.g., `A123G+T150A`).
+- Run:
+  ```bash
+  uht-tooling design-gibson \
+    --gene-fasta data/design_gibson/gibson_template_gene.fasta \
+    --context-fasta data/design_gibson/gibson_context.fasta \
+    --mutations-csv data/design_gibson/gibson_target_mutations.csv \
+    --output-dir results/design_gibson/
+  ```
+- Outputs include primer sets and an assembly-plan CSV.
+
+If mutations fall within overlapping primer windows, design sequential reactions to avoid excessive primer reuse.
+
+### Mutation caller (no UMIs)
+
+1. Supply:
+   - `data/mutation_caller/mutation_caller_template.fasta`
+   - `data/mutation_caller/mutation_caller.csv` with `gene_flanks` and `gene_min_max` columns (two rows each).
+   - One or more FASTQ files via `--fastq`.
+2. Run:
+   ```bash
+   uht-tooling mutation-caller \
+     --template-fasta data/mutation_caller/mutation_caller_template.fasta \
+     --flanks-csv data/mutation_caller/mutation_caller.csv \
+     --fastq data/mutation_caller/*.fastq.gz \
+     --output-dir results/mutation_caller/ \
+     --threshold 10
+   ```
+3. Outputs: per-sample subdirectories with substitution summaries, co-occurrence matrices, and logs.
+
+### UMI Hunter
+
+- Inputs: `data/umi_hunter/template.fasta`, `data/umi_hunter/umi_hunter.csv`, and FASTQ reads.
+- Command:
+  ```bash
+  uht-tooling umi-hunter \
+    --template-fasta data/umi_hunter/template.fasta \
+    --config-csv data/umi_hunter/umi_hunter.csv \
+    --fastq data/umi_hunter/*.fastq.gz \
+    --output-dir results/umi_hunter/
+  ```
+- Tunable parameters include `--umi-identity-threshold` and `--consensus-mutation-threshold`.
+
+### Profile inserts
+
+- Prepare `data/profile_inserts/sample_probes.csv` with `upstream` and `downstream` columns.
+- Run:
+  ```bash
+  uht-tooling profile-inserts \
+    --probes-csv data/profile_inserts/sample_probes.csv \
+    --fastq data/profile_inserts/*.fastq.gz \
+    --output-dir results/profile_inserts/
+  ```
+- Outputs: extracted insert FASTA files, QC plots, metrics, and logs. Adjust fuzzy matching strictness via `--min-ratio`.
+
+### EP library profiler (no UMIs)
+
+- Inputs:
+  - `data/ep-library-profile/region_of_interest.fasta`
+  - `data/ep-library-profile/plasmid.fasta`
+  - FASTQ inputs (`--fastq` accepts multiple files)
+- Run:
+  ```bash
+  uht-tooling ep-library-profile \
+    --region-fasta data/ep-library-profile/region_of_interest.fasta \
+    --plasmid-fasta data/ep-library-profile/plasmid.fasta \
+    --fastq data/ep-library-profile/*.fastq.gz \
+    --output-dir results/ep-library-profile/
+  ```
+- Output bundle includes per-sample directories and a master summary TSV.
+
+---
+
+## GUI quick start (optional)
+
+The Gradio GUI wraps the same workflows with upload widgets and result previews. Launch it directly:
+
+```bash
+python -m uht_tooling.workflows.gui
+```
+
+Key points:
+- The server binds to `http://127.0.0.1:7860` by default and falls back to an available port if 7860 is busy. Copy http://127.0.0.1:7860 into your browser.
+- Temporary working directories are created under the system temp folder and cleaned automatically.
+- Output archives (ZIP files) mirror the directory structure produced by the CLI.
+
+### 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, template FASTA, and configuration CSV.
+5. **UMI Hunter** – long-read UMI clustering with configurable thresholds.
+6. **Profile Inserts** – probe CSV and multiple FASTQ uploads.
+7. **EP Library Profile** – FASTQ uploads plus plasmid and region FASTA inputs.
+
+### Workflow tips
+
+- For large FASTQ datasets, the CLI remains the most efficient option (especially for automation or batch processing).
+- Use the command-line flag `--share` in `python -m uht_tooling.workflows.gui` if you need to expose the GUI outside localhost.
+
+### Troubleshooting
+
+- **Port already bound:** the launcher automatically selects the next free port and logs the chosen URL.
+- **Missing dependency:** ensure you installed with `pip install "uht-tooling[gui]"`.
+- **Stopping the server:** press `Ctrl+C` in the terminal session running the GUI.
+
+---
+
+## Logging
+
+Every workflow configures logging to the destination output directory. Inspect `run.log` for command echoes, parameter choices, and any warnings produced during execution. When providing bug reports, include this log file along with input metadata to streamline triage.
+
+---
+
+## Roadmap
+
+- Replace deprecated Biopython command-line wrappers with native subprocess implementations.
+- Expand CLI coverage to any remaining legacy scripts that are still invoked via `make`.
+- Add documentation for automation pipelines and integrate continuous integration tests.
+
+Contributions in the form of bug reports, pull requests, or feature suggestions are welcome. File issues on GitHub with clear reproduction steps and sample data when possible.

uht_tooling-0.1.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+uht_tooling/__init__.py,sha256=hf0tJaa4_9y9aYb8OB1FtJh1FOuX08dQ6_MCveWFNAc,242
+uht_tooling/cli.py,sha256=G8eDBtw_YgcYV7ynk_YD9W2ua0a0pqGCqud5VaHsB6M,11695
+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=jP3gYZp8hyBCms65nzoZ_EW3rsNrn2ZGGp8gBSvny6Q,23123
+uht_tooling/workflows/mut_rate.py,sha256=wjX1lNXTcaH49gfARSrpKLU1mD5hCgH0ZFTcdlNrAB4,105670
+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=kXR7Tw3vK4TnL8OShRt9kZ36ONpOSd-1txwB95Ldi-I,14470
+uht_tooling-0.1.2.dist-info/METADATA,sha256=bu34FtN9RwijcENNhkRxT1LdXQyl8uBfToBOItastDU,10800
+uht_tooling-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+uht_tooling-0.1.2.dist-info/entry_points.txt,sha256=t3_bMkEnlnV4vd6nrjNQxHDsHzHHoZenhmxuIYLcRBY,53
+uht_tooling-0.1.2.dist-info/top_level.txt,sha256=iTCCiSn0OjrTx1VOdxXhUlPi1TR9LxaJEZJoMyRcv9c,12
+uht_tooling-0.1.2.dist-info/RECORD,,