uht-tooling 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

uht_tooling/cli.py

@@ -233,6 +233,11 @@ def umi_hunter_command(
         max=1.0,
         help="Mutation threshold for consensus calling (default: 0.7).",
     ),
+    min_cluster_size: int = typer.Option(
+        1,
+        min=1,
+        help="Minimum number of reads required in a UMI cluster before a consensus is generated.",
+    ),
     log_path: Optional[Path] = typer.Option(
         None,
         dir_okay=False,
@@ -249,6 +254,7 @@ def umi_hunter_command(
         output_dir=output_dir,
         umi_identity_threshold=umi_identity_threshold,
         consensus_mutation_threshold=consensus_mutation_threshold,
+        min_cluster_size=min_cluster_size,
         log_path=log_path,
     )
     if not results:
@@ -256,7 +262,12 @@ def umi_hunter_command(
     else:
         typer.echo("UMI hunter outputs:")
         for entry in results:
-            typer.echo(f"  Sample {entry['sample']}: {entry['directory']}")
+            total_clusters = entry.get("clusters_total", entry.get("clusters", 0))
+            typer.echo(
+                f"  Sample {entry['sample']}: "
+                f"{entry.get('clusters', 0)} consensus clusters "
+                f"(from {total_clusters} total) → {entry['directory']}"
+            )
 
 
 @app.command("ep-library-profile", help="Profile mutation rates for ep-library sequencing data.")

uht_tooling/workflows/gui.py

@@ -10,7 +10,7 @@ import tempfile
 import textwrap
 import zipfile
 from pathlib import Path
-from typing import Iterable, List, Optional, Sequence, Tuple
+from typing import Any, Iterable, List, Optional, Sequence, Tuple
 
 try:
     import gradio as gr
@@ -241,28 +241,60 @@ def run_gui_design_gibson(
 def run_gui_mutation_caller(
     fastq_file: Optional[str],
     template_file: Optional[str],
-    config_csv_file: Optional[str],
+    upstream_flank: str,
+    downstream_flank: str,
+    min_gene_length: Optional[float],
+    max_gene_length: Optional[float],
 ) -> Tuple[str, Optional[str]]:
+    config_dir: Optional[Path] = None
+    output_dir: Optional[Path] = None
     try:
-        if not fastq_file or not template_file or not config_csv_file:
-            raise ValueError("Upload a FASTQ(.gz), template FASTA, and configuration CSV.")
+        if not fastq_file or not template_file:
+            raise ValueError("Upload a FASTQ(.gz) read file and the reference template FASTA.")
+
+        gene_start = _ensure_text(upstream_flank, "Upstream flank")
+        gene_end = _ensure_text(downstream_flank, "Downstream flank")
+        if min_gene_length is None or max_gene_length is None:
+            raise ValueError("Provide minimum and maximum gene lengths (in nucleotides).")
+
+        gene_min = int(min_gene_length)
+        gene_max = int(max_gene_length)
+        if gene_min <= 0 or gene_max <= 0:
+            raise ValueError("Gene length bounds must be positive integers.")
+        if gene_min > gene_max:
+            raise ValueError("Minimum gene length cannot exceed the maximum gene length.")
+
+        config_dir = Path(tempfile.mkdtemp(prefix="uht_gui_mutation_cfg_"))
+        config_csv = config_dir / "mutation_flanks.csv"
+        pd.DataFrame(
+            {
+                "gene_flanks": [gene_start.upper(), gene_end.upper()],
+                "gene_min_max": [gene_min, gene_max],
+            }
+        ).to_csv(config_csv, index=False)
 
         output_dir = Path(tempfile.mkdtemp(prefix="uht_gui_mutation_out_"))
         results = run_mutation_caller(
             template_fasta=Path(template_file),
-            flanks_csv=Path(config_csv_file),
+            flanks_csv=config_csv,
             fastq_files=[Path(fastq_file)],
             output_dir=output_dir,
             threshold=10,
         )
 
         if not results:
-            return "No amino-acid substitutions detected.", None
-
-        lines = ["### Mutation Caller", ""]
+            return "No amino-acid substitutions detected. Check flank selections and read quality.", None
+
+        lines = [
+            "### Mutation Caller",
+            "",
+            "Long-read reads were aligned to the provided template, flank-delimited coding regions were extracted, and amino-acid substitutions were summarised.",
+            "",
+            "**Run outputs**",
+        ]
         sample_dirs = []
         for entry in results:
-            lines.append(f"**{entry['sample']}** → {entry['directory']}")
+            lines.append(f"- **{entry['sample']}** → {entry['directory']}")
             sample_dirs.append(Path(entry["directory"]))
         summary = "\n".join(lines)
         archive = _zip_paths(sample_dirs, "mutation_caller")
@@ -270,33 +302,94 @@ def run_gui_mutation_caller(
     except Exception as exc:  # pragma: no cover
         _LOGGER.exception("Mutation caller GUI failure")
         return f"⚠️ Error: {exc}", None
+    finally:
+        if config_dir:
+            _clean_temp_path(config_dir)
+        if output_dir:
+            _clean_temp_path(output_dir)
 
 
 def run_gui_umi_hunter(
     fastq_file: Optional[str],
     template_file: Optional[str],
-    config_csv_file: Optional[str],
+    umi_start: str,
+    umi_end: str,
+    umi_min_length: Optional[float],
+    umi_max_length: Optional[float],
+    gene_start: str,
+    gene_end: str,
+    umi_identity_threshold: float,
+    consensus_threshold: float,
+    min_cluster_size: int,
 ) -> Tuple[str, Optional[str]]:
+    config_dir: Optional[Path] = None
+    output_dir: Optional[Path] = None
     try:
-        if not fastq_file or not template_file or not config_csv_file:
-            raise ValueError("Upload a FASTQ(.gz), template FASTA, and configuration CSV.")
+        if not fastq_file or not template_file:
+            raise ValueError("Upload a FASTQ(.gz) read file and the template FASTA.")
+
+        umi_start_clean = _ensure_text(umi_start, "UMI upstream flank").upper()
+        umi_end_clean = _ensure_text(umi_end, "UMI downstream flank").upper()
+        gene_start_clean = _ensure_text(gene_start, "Gene upstream flank").upper()
+        gene_end_clean = _ensure_text(gene_end, "Gene downstream flank").upper()
+        if umi_min_length is None or umi_max_length is None:
+            raise ValueError("Provide minimum and maximum UMI lengths.")
+
+        umi_min = int(umi_min_length)
+        umi_max = int(umi_max_length)
+        if umi_min <= 0 or umi_max <= 0:
+            raise ValueError("UMI length bounds must be positive integers.")
+        if umi_min > umi_max:
+            raise ValueError("Minimum UMI length cannot exceed the maximum length.")
+        if not (0.0 <= umi_identity_threshold <= 1.0):
+            raise ValueError("UMI identity threshold must be between 0 and 1.")
+        if not (0.0 <= consensus_threshold <= 1.0):
+            raise ValueError("Consensus mutation threshold must be between 0 and 1.")
+        if min_cluster_size is None or int(min_cluster_size) < 1:
+            raise ValueError("Minimum cluster size must be at least 1.")
+        min_cluster_size_int = int(min_cluster_size)
+
+        config_dir = Path(tempfile.mkdtemp(prefix="uht_gui_umi_cfg_"))
+        config_csv = config_dir / "umi_config.csv"
+        pd.DataFrame(
+            {
+                "umi_flanks": [umi_start_clean, umi_end_clean],
+                "umi_min_max": [umi_min, umi_max],
+                "gene_flanks": [gene_start_clean, gene_end_clean],
+            }
+        ).to_csv(config_csv, index=False)
 
         output_dir = Path(tempfile.mkdtemp(prefix="uht_gui_umi_out_"))
         results = run_umi_hunter(
             template_fasta=Path(template_file),
-            config_csv=Path(config_csv_file),
+            config_csv=config_csv,
             fastq_files=[Path(fastq_file)],
             output_dir=output_dir,
+            umi_identity_threshold=umi_identity_threshold,
+            consensus_mutation_threshold=consensus_threshold,
+            min_cluster_size=min_cluster_size_int,
         )
 
         if not results:
-            return "No UMI clusters were generated. Check input quality and thresholds.", None
+            return (
+                "No UMI clusters were generated. Double-check flank selections and threshold settings.",
+                None,
+            )
 
-        lines = ["### UMI Hunter", ""]
+        lines = [
+            "### UMI Hunter",
+            "",
+            "Reads were scanned for UMI and gene flanks, deduplicated by UMI, and consensus alleles were generated.",
+            "",
+            "**Run outputs**",
+        ]
         sample_dirs = []
         for entry in results:
+            total_clusters = entry.get("clusters_total", entry["clusters"])
             lines.append(
-                f"**{entry['sample']}** → {entry['clusters']} clusters, results in {entry['directory']}"
+                f"- **{entry['sample']}** → {entry['clusters']} consensus clusters "
+                f"(≥ {min_cluster_size_int} reads) from {total_clusters} total, "
+                f"results in {entry['directory']}"
             )
             sample_dirs.append(Path(entry["directory"]))
         summary = "\n".join(lines)
@@ -305,35 +398,82 @@ def run_gui_umi_hunter(
     except Exception as exc:  # pragma: no cover
         _LOGGER.exception("UMI hunter GUI failure")
         return f"⚠️ Error: {exc}", None
+    finally:
+        if config_dir:
+            _clean_temp_path(config_dir)
+        if output_dir:
+            _clean_temp_path(output_dir)
 
 
 def run_gui_profile_inserts(
-    probes_csv_path: Optional[str],
+    probes_table: Any,
     fastq_files: Sequence[str],
+    min_ratio: int,
 ) -> Tuple[str, Optional[str]]:
+    config_dir: Optional[Path] = None
+    output_dir: Optional[Path] = None
     try:
-        if not probes_csv_path or not fastq_files:
-            raise ValueError("Upload the probe CSV and at least one FASTQ(.gz) file.")
+        if not fastq_files:
+            raise ValueError("Upload at least one FASTQ(.gz) file.")
+        if probes_table is None:
+            raise ValueError("Provide at least one probe pair.")
+
+        if isinstance(probes_table, pd.DataFrame):
+            df = probes_table.copy()
+        else:
+            df = pd.DataFrame(probes_table or [], columns=["name", "upstream", "downstream"])
+
+        # Normalise and validate probe entries
+        df = df.replace({pd.NA: "", None: ""})
+        for column in df.columns:
+            if df[column].dtype == object:
+                df[column] = df[column].map(lambda x: x.strip() if isinstance(x, str) else x)
+
+        if "upstream" not in df.columns or "downstream" not in df.columns:
+            raise ValueError("Probe table must contain 'upstream' and 'downstream' columns.")
+
+        df_valid = df[(df["upstream"] != "") & (df["downstream"] != "")].copy()
+        if df_valid.empty:
+            raise ValueError("Enter at least one probe pair with both upstream and downstream sequences.")
+
+        df_valid = df_valid.reset_index(drop=True)
+        if "name" not in df_valid.columns:
+            df_valid["name"] = [f"probe_{i + 1}" for i in range(len(df_valid))]
+        else:
+            fallback_names = pd.Series(
+                [f"probe_{i + 1}" for i in range(len(df_valid))], index=df_valid.index
+            )
+            df_valid["name"] = df_valid["name"].replace("", pd.NA).fillna(fallback_names)
+
+        config_dir = Path(tempfile.mkdtemp(prefix="uht_gui_profile_cfg_"))
+        probes_csv = config_dir / "probes.csv"
+        df_valid.to_csv(probes_csv, index=False)
 
         output_dir = Path(tempfile.mkdtemp(prefix="uht_gui_profile_out_"))
         results = run_profile_inserts(
-            probes_csv=Path(probes_csv_path),
+            probes_csv=probes_csv,
             fastq_files=[Path(f) for f in fastq_files],
             output_dir=output_dir,
+            min_ratio=int(min_ratio),
         )
 
         if not results:
-            return "No inserts were extracted. Adjust probe settings and try again.", None
+            return "No inserts were extracted. Adjust probe sequences or similarity threshold and try again.", None
 
         first_insert = results[0]["fasta"] if isinstance(results, list) else None
         preview = "*(preview unavailable)*"
         if first_insert and Path(first_insert).exists():
-            preview = Path(first_insert).read_text().splitlines()[0][:80] + "..."
+            preview = Path(first_insert).read_text().splitlines()[0][:120] + "..."
 
         summary = textwrap.dedent(
             """
             ### Insert Profiling
-            Extracted inserts and generated QC metrics. Download the archive for full outputs.
+            Probe-defined regions were scanned in the provided FASTQ files, inserts were extracted, and QC metrics were generated.
+
+            **Key outputs**
+            - FASTA files containing extracted inserts per probe pair
+            - Summary tables covering length, GC content, duplicate rate, and probe match quality
+            - A gallery of QC plots (length distributions, base composition, probe performance)
             """
         )
         archive = _zip_paths([Path(r["directory"]) for r in results], "profile_inserts")
@@ -341,6 +481,11 @@ def run_gui_profile_inserts(
     except Exception as exc:  # pragma: no cover
         _LOGGER.exception("Profile inserts GUI failure")
         return f"⚠️ Error: {exc}", None
+    finally:
+        if config_dir:
+            _clean_temp_path(config_dir)
+        if output_dir:
+            _clean_temp_path(output_dir)
 
 
 def run_gui_ep_library_profile(
@@ -406,18 +551,34 @@ def create_gui() -> gr.Blocks:
                 textwrap.dedent(
                     """
                     # uht-tooling
-                    A guided graphical interface for primer design and sequencing analysis.
-                    Use the tabs below, supply the required inputs, and download the generated results.
+                    A guided graphical interface for primer design and sequencing analysis. Each tab mirrors the command-line workflows documented in the README and bundles results, logs, and QC artefacts for download.
+
+                    **How to use**
+                    1. Select the workflow that matches your experiment.
+                    2. Provide the required inputs (text fields, FASTQ/FASTA uploads, or probe tables).
+                    3. Run the analysis and download the ZIP archive for complete outputs.
+
+                    Need automation or batch processing? Use the Typer CLI (`uht-tooling ...`) with the same arguments shown here.
                     """
                 )
             )
 
         with gr.Tab("Nextera XT"):  # --- Nextera ---
             gr.Markdown(
-                """
-                ### Illumina-Compatible Primer Design
-                Provide the forward and reverse binding regions in 5'→3' orientation.
-                """
+                textwrap.dedent(
+                    """
+                    ### 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**
+                    - Forward primer binding region (5'→3')
+                    - Reverse primer binding region (5'→3')
+
+                    **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')")
             reverse = gr.Textbox(label="Reverse primer (5'→3')")
@@ -429,13 +590,34 @@ def create_gui() -> gr.Blocks:
                 inputs=[forward, reverse],
                 outputs=[nextera_summary, nextera_download],
             )
+            with gr.Accordion("Wet-lab guidance", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - Monitor amplification by qPCR and cap the cycle count to reach roughly 10 % yield to limit bias.
+                        - Purify products with SPRIselect beads (~0.65:1 bead:DNA ratio) to remove residual primers.
+                        - Confirm primer depletion via electrophoresis (e.g., BioAnalyzer) before sequencing prep.
+                        """
+                    )
+                )
 
         with gr.Tab("SLIM"):
             gr.Markdown(
-                """
-                ### Sequence-Ligation Independent Mutagenesis
-                Paste the gene coding sequence, the plasmid context, and one mutation per line.
-                """
+                textwrap.dedent(
+                    """
+                    ### 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`).
+
+                    **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)
             slim_context = gr.Textbox(label="Plasmid context", lines=4)
@@ -448,13 +630,36 @@ def create_gui() -> gr.Blocks:
                 inputs=[slim_gene, slim_context, slim_mutations],
                 outputs=[slim_summary, slim_download],
             )
+            with gr.Accordion("Bench workflow blueprint", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        1. Run two PCRs: (A) long forward + short reverse, (B) long reverse + short forward.
+                        2. Combine 10 µL from each PCR with 10 µL H-buffer (150 mM Tris pH 8, 400 mM NaCl, 60 mM EDTA).
+                        3. Thermocycle: 99 °C 3 min → 2× (65 °C 5 min → 30 °C 15 min) → hold at 4 °C.
+                        4. Transform directly into NEB 5-alpha or BL21 (DE3); the method scales to dozens of mutants simultaneously.
+                        """
+                    )
+                )
 
         with gr.Tab("Gibson"):
             gr.Markdown(
-                """
-                ### Gibson Assembly Primer Design
-                Use `+` to combine multiple mutations applied simultaneously.
-                """
+                textwrap.dedent(
+                    """
+                    ### 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**
+                    - Coding sequence for the gene of interest.
+                    - Circular plasmid context sequence.
+                    - Mutation definitions (one per line; use `+` to bundle simultaneous edits).
+
+                    **Outputs**
+                    - 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)
             gibson_context = gr.Textbox(label="Plasmid context", lines=4)
@@ -467,74 +672,270 @@ def create_gui() -> gr.Blocks:
                 inputs=[gibson_gene, gibson_context, gibson_mutations],
                 outputs=[gibson_summary, gibson_download],
             )
+            with gr.Accordion("Tips for multi-mutation designs", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - If two mutations compete for primer space, design them in sequential runs to avoid overly long primers.
+                        - Use the assembly plan CSV to map which fragments to combine in each Gibson reaction.
+                        - When replacing entire codons (e.g. `L46GP`), ensure the plasmid context covers both flanks to maintain overlap.
+                        """
+                    )
+                )
 
         with gr.Tab("Mutation Caller"):
             gr.Markdown(
-                """
-                ### Long-read Mutation Analysis
-                Upload a FASTQ(.gz), the template FASTA, and the mutation_caller CSV configuration.
-                """
+                textwrap.dedent(
+                    """
+                    ### 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**
+                    - FASTQ (.fastq.gz): Oxford Nanopore or other long-read data.
+                    - 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.
+                    """
+                )
             )
-            mc_fastq = gr.File(label="FASTQ (.fastq.gz)", file_types=[".fastq", ".gz"], type="filepath")
-            mc_template = gr.File(label="Template FASTA", file_types=[".fasta", ".fa"], type="filepath")
-            mc_config = gr.File(label="Configuration CSV", file_types=[".csv"], type="filepath")
+            with gr.Row():
+                mc_fastq = gr.File(
+                    label="FASTQ (.fastq.gz)",
+                    file_types=[".fastq", ".gz"],
+                    type="filepath",
+                )
+                mc_template = gr.File(
+                    label="Template FASTA",
+                    file_types=[".fasta", ".fa"],
+                    type="filepath",
+                )
+            with gr.Row():
+                mc_upstream = gr.Textbox(
+                    label="Upstream flank (5'→3')",
+                    placeholder="e.g. ACTGTTAG",
+                )
+                mc_downstream = gr.Textbox(
+                    label="Downstream flank (5'→3')",
+                    placeholder="e.g. CGAACCTA",
+                )
+            with gr.Row():
+                mc_min_len = gr.Number(
+                    label="Minimum gene length (nt)",
+                    value=900,
+                    precision=0,
+                )
+                mc_max_len = gr.Number(
+                    label="Maximum gene length (nt)",
+                    value=1200,
+                    precision=0,
+                )
             mc_btn = gr.Button("Run mutation caller", variant="primary")
             mc_summary = gr.Markdown(label="Summary")
             mc_download = gr.File(label="Download results", file_count="single")
             mc_btn.click(
                 fn=run_gui_mutation_caller,
-                inputs=[mc_fastq, mc_template, mc_config],
+                inputs=[
+                    mc_fastq,
+                    mc_template,
+                    mc_upstream,
+                    mc_downstream,
+                    mc_min_len,
+                    mc_max_len,
+                ],
                 outputs=[mc_summary, mc_download],
             )
+            with gr.Accordion("What happens under the hood", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - Reads are scanned for the upstream and downstream flanks; the sequence between them is treated as the gene of interest if it falls within the specified length window.
+                        - MAFFT aligns recovered genes to the reference template and the pipeline annotates amino-acid substitutions, co-occurrence networks, and depth statistics.
+                        - 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(
-                """
-                ### UMI-Gene Pair Clustering
-                Upload a FASTQ(.gz), template FASTA, and the UMI configuration CSV.
-                """
+                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.
+
+                    **Required inputs**
+                    - FASTQ (.fastq.gz) containing UMI-tagged reads.
+                    - Template FASTA for downstream consensus calling.
+                    - 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(
+                    label="FASTQ (.fastq.gz)",
+                    file_types=[".fastq", ".gz"],
+                    type="filepath",
+                )
+                umi_template = gr.File(
+                    label="Template FASTA",
+                    file_types=[".fasta", ".fa"],
+                    type="filepath",
+                )
+            with gr.Row():
+                umi_start = gr.Textbox(
+                    label="UMI upstream flank (5'→3')",
+                    placeholder="e.g. ACACTCTTTCCCTACACGAC",
+                )
+                umi_end = gr.Textbox(
+                    label="UMI downstream flank (5'→3')",
+                    placeholder="e.g. GACTGGAGTTCAGACGTGTG",
+                )
+            with gr.Row():
+                gene_start = gr.Textbox(
+                    label="Gene upstream flank (5'→3')",
+                    placeholder="e.g. ATG...",
+                )
+                gene_end = gr.Textbox(
+                    label="Gene downstream flank (5'→3')",
+                    placeholder="e.g. TTA...",
+                )
+            with gr.Row():
+                umi_min_len = gr.Number(
+                    label="Minimum UMI length (nt)",
+                    value=8,
+                    precision=0,
+                )
+                umi_max_len = gr.Number(
+                    label="Maximum UMI length (nt)",
+                    value=14,
+                    precision=0,
+                )
+            with gr.Row():
+                umi_identity = gr.Slider(
+                    label="UMI clustering identity",
+                    minimum=0.5,
+                    maximum=1.0,
+                    value=0.9,
+                    step=0.05,
+                )
+                consensus_threshold = gr.Slider(
+                    label="Consensus mutation threshold",
+                    minimum=0.5,
+                    maximum=1.0,
+                    value=0.7,
+                    step=0.05,
+                )
+            umi_min_cluster = gr.Slider(
+                label="Minimum reads per cluster",
+                minimum=1,
+                maximum=50,
+                value=3,
+                step=1,
             )
-            umi_fastq = gr.File(label="FASTQ (.fastq.gz)", file_types=[".fastq", ".gz"], type="filepath")
-            umi_template = gr.File(label="Template FASTA", file_types=[".fasta", ".fa"], type="filepath")
-            umi_config = gr.File(label="UMI config CSV", file_types=[".csv"], type="filepath")
             umi_btn = gr.Button("Run UMI hunter", variant="primary")
             umi_summary = gr.Markdown(label="Summary")
             umi_download = gr.File(label="Download results", file_count="single")
             umi_btn.click(
                 fn=run_gui_umi_hunter,
-                inputs=[umi_fastq, umi_template, umi_config],
+                inputs=[
+                    umi_fastq,
+                    umi_template,
+                    umi_start,
+                    umi_end,
+                    umi_min_len,
+                    umi_max_len,
+                    gene_start,
+                    gene_end,
+                    umi_identity,
+                    consensus_threshold,
+                    umi_min_cluster,
+                ],
                 outputs=[umi_summary, umi_download],
             )
+            with gr.Accordion("What the pipeline generates", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - Reads are searched for the UMI barcode and gene flanks on both strands; valid pairs feed into UMI grouping.
+                        - UMIs within the chosen identity threshold are merged, and consensus sequences are computed with the mutation threshold.
+                        - 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(
-                """
-                ### Insert Profiling
-                Upload the probe CSV and one or more FASTQ(.gz) files containing reads.
-                """
+                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(
+                headers=["name (optional)", "upstream", "downstream"],
+                datatype=["str", "str", "str"],
+                row_count=(1, "dynamic"),
+                col_count=3,
+                value=[["probe_1", "", ""]],
+                interactive=True,
+                label="Probe pairs",
             )
-            pi_csv = gr.File(label="Probe CSV", file_types=[".csv"], type="filepath")
             pi_fastq = gr.File(
-                label="FASTQ files",
+                label="FASTQ files (.fastq/.gz)",
                 file_types=[".fastq", ".gz"],
                 file_count="multiple",
                 type="filepath",
             )
+            pi_ratio = gr.Slider(
+                label="Minimum fuzzy-match ratio",
+                minimum=50,
+                maximum=100,
+                value=80,
+                step=1,
+            )
             pi_btn = gr.Button("Profile inserts", variant="primary")
             pi_summary = gr.Markdown(label="Summary")
             pi_download = gr.File(label="Download results", file_count="single")
             pi_btn.click(
                 fn=run_gui_profile_inserts,
-                inputs=[pi_csv, pi_fastq],
+                inputs=[probes_table, pi_fastq, pi_ratio],
                 outputs=[pi_summary, pi_download],
             )
+            with gr.Accordion("Output overview", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - Inserts are extracted whenever probe matches are detected above the chosen similarity threshold (default 80).
+                        - A FASTA file of inserts, probe-level QC metrics, base composition summaries, and a suite of plots (length distribution, GC content, duplicate rate, probe performance) are packaged for each input FASTQ.
+                        - Logs are stored alongside the results so runs remain fully reproducible.
+                        """
+                    )
+                )
 
         with gr.Tab("EP Library Profile"):
             gr.Markdown(
-                """
-                ### Library Profiling Without UMIs
-                Upload one or more FASTQ(.gz) files plus the region and plasmid references.
-                """
+                textwrap.dedent(
+                    """
+                    ### Library Profiling Without UMIs
+                    Estimates background and target mutation rates for enzyme evolution libraries without UMI barcodes.
+
+                    **Inputs**
+                    - FASTQ reads (*.fastq/.gz) from the ep-library experiment.
+                    - Region-of-interest FASTA delineating the mutational window.
+                    - Plasmid FASTA providing the full reference context.
+
+                    **Outputs**
+                    - 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(
                 label="FASTQ files",
@@ -552,6 +953,16 @@ def create_gui() -> gr.Blocks:
                 inputs=[ep_fastq, ep_region, ep_plasmid],
                 outputs=[ep_summary, ep_download],
             )
+            with gr.Accordion("How mutation rates are derived", open=False):
+                gr.Markdown(
+                    textwrap.dedent(
+                        """
+                        - Reads are aligned against the plasmid reference; mismatches inside the region-of-interest drive target rate estimates, while mismatches elsewhere define the background rate.
+                        - Z-scores and p-values summarise enrichment versus background, mirroring the CLI outputs.
+                        - Download the archive to inspect per-sample plots, TSV summaries, and logs for troubleshooting.
+                        """
+                    )
+                )
 
         gr.Markdown(
             textwrap.dedent(

uht_tooling/workflows/umi_hunter.py

@@ -264,6 +264,7 @@ def run_umi_hunter(
     output_dir: Path,
     umi_identity_threshold: float = 0.9,
     consensus_mutation_threshold: float = 0.7,
+    min_cluster_size: int = 1,
     log_path: Optional[Path] = None,
     logger: Optional[logging.Logger] = None,
 ) -> List[Dict[str, Path]]:
@@ -291,6 +292,9 @@ def run_umi_hunter(
         if not fastq_files:
             raise ValueError("No FASTQ files provided.")
 
+        if min_cluster_size < 1:
+            raise ValueError("Minimum cluster size must be at least 1.")
+
         cfg = load_flank_config(config_csv)
         pattern_umi, pattern_gene = build_patterns(cfg)
         reference_record = next(SeqIO.parse(str(template_fasta), "fasta"))
@@ -314,10 +318,20 @@ def run_umi_hunter(
             umi_csv = sample_dir / f"{sample_base}_UMI_clusters.csv"
             write_umi_csv(umi_csv, clusters)
 
+            significant_clusters = [
+                cluster for cluster in clusters if cluster["total_count"] >= min_cluster_size
+            ]
+            if not significant_clusters:
+                logger.info(
+                    "No clusters met the minimum size threshold (%s reads) for %s.",
+                    min_cluster_size,
+                    sample_base,
+                )
+
             gene_csv = sample_dir / f"{sample_base}_gene_consensus.csv"
             consensus_records = write_gene_csv(
                 gene_csv,
-                clusters,
+                significant_clusters,
                 reference_record,
                 consensus_mutation_threshold,
                 logger,
@@ -334,7 +348,8 @@ def run_umi_hunter(
                     "gene_csv": gene_csv,
                     "fasta": fasta_out,
                     "reads": read_count,
-                    "clusters": len(clusters),
+                    "clusters": len(significant_clusters),
+                    "clusters_total": len(clusters),
                 }
             )
 

{uht_tooling-0.1.3.dist-info → uht_tooling-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uht-tooling
-Version: 0.1.3
+Version: 0.1.4
 Summary: Tooling for ultra-high throughput screening workflows.
 Author: Matt115A
 License: MIT
@@ -189,9 +189,10 @@ If mutations fall within overlapping primer windows, design sequential reactions
     --fastq data/umi_hunter/*.fastq.gz \
     --output-dir results/umi_hunter/
   ```
-- Tunable parameters include `--umi-identity-threshold` and `--consensus-mutation-threshold`.
-- --umi-identity-threshold is a decimal between 0-1 and defines how similar two UMIs have to be to be considered grouped.
-- --consensus-mutation-threshold is the minimum group size to report a consensus sequence.
+- Tunable parameters include `--umi-identity-threshold`, `--consensus-mutation-threshold`, and `--min-cluster-size`.
+- `--umi-identity-threshold` (0–1) controls how similar two UMIs must be to fall into the same cluster.
+- `--consensus-mutation-threshold` (0–1) is the fraction of reads within a cluster that must agree on a base before it is written into the consensus sequence.
+- `--min-cluster-size` sets the minimum number of reads required in a cluster before a consensus is generated (smaller clusters remain listed in the raw UMI CSV but no consensus FASTA is produced).
 
 Please be aware, this toolkit will not scale well beyond around 50k reads/sample. See UMIC-seq pipelines for efficient UMI-gene dictionary generation.
 
@@ -243,9 +244,9 @@ Key points:
 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.
+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.
 
 ### Workflow tips

{uht_tooling-0.1.3.dist-info → uht_tooling-0.1.4.dist-info}/RECORD

@@ -1,17 +1,17 @@
 uht_tooling/__init__.py,sha256=hf0tJaa4_9y9aYb8OB1FtJh1FOuX08dQ6_MCveWFNAc,242
-uht_tooling/cli.py,sha256=sQU0duLmMOqvqzB6hDV7GIQYdvzAKKK3rLx0Iq07ZR4,12432
+uht_tooling/cli.py,sha256=yKTPqWwYAs7tzO_TeyaLhSfzkNoCUPnc0wU2fgOR2wk,12882
 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/gui.py,sha256=g3lhHBWuKi1qEpY4iBnhr-tROSGepMQJm-fjiVCrk08,42559
 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.3.dist-info/METADATA,sha256=0bPz8odnvbX13BvlQC4HsXvJwu7dRK7YyQ2nD7KwHEA,11220
-uht_tooling-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-uht_tooling-0.1.3.dist-info/entry_points.txt,sha256=t3_bMkEnlnV4vd6nrjNQxHDsHzHHoZenhmxuIYLcRBY,53
-uht_tooling-0.1.3.dist-info/top_level.txt,sha256=iTCCiSn0OjrTx1VOdxXhUlPi1TR9LxaJEZJoMyRcv9c,12
-uht_tooling-0.1.3.dist-info/RECORD,,
+uht_tooling/workflows/umi_hunter.py,sha256=baycWycqVzUfMp5u2WZdHRl0sNuykTjy-iqtj5ahucU,15075
+uht_tooling-0.1.4.dist-info/METADATA,sha256=l7CcHpNlvnxYghc8eqw1PGRaPcqxSHeL_GJuRJNifSI,11626
+uht_tooling-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+uht_tooling-0.1.4.dist-info/entry_points.txt,sha256=t3_bMkEnlnV4vd6nrjNQxHDsHzHHoZenhmxuIYLcRBY,53
+uht_tooling-0.1.4.dist-info/top_level.txt,sha256=iTCCiSn0OjrTx1VOdxXhUlPi1TR9LxaJEZJoMyRcv9c,12
+uht_tooling-0.1.4.dist-info/RECORD,,