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

uht_tooling/cli.py

@@ -18,6 +18,7 @@ from uht_tooling.workflows.umi_hunter import (
     expand_fastq_inputs as expand_fastq_inputs_umi,
     run_umi_hunter,
 )
+from uht_tooling.workflows.gui import launch_gui
 
 app = typer.Typer(help="Command-line interface for the uht-tooling package.")
 
@@ -232,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,
@@ -248,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:
@@ -255,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.")
@@ -355,9 +367,34 @@ def profile_inserts_command(
             typer.echo(f"  Sample {entry['sample']}: {entry['directory']}")
 
 
-@app.command("gui", help="Launch the graphical interface (currently under refactor).")
-def gui_command():
-    raise NotImplementedError("The GUI is being updated to work with user-specified data directories.")
+@app.command("gui", help="Launch the graphical interface.")
+def gui_command(
+    server_name: str = typer.Option(
+        "127.0.0.1",
+        "--server-name",
+        "-n",
+        help="Hostname or IP address to bind the GUI server.",
+    ),
+    server_port: Optional[int] = typer.Option(
+        7860,
+        "--server-port",
+        "-p",
+        help="Preferred port for the GUI (falls back automatically if unavailable).",
+    ),
+    share: bool = typer.Option(
+        False,
+        "--share",
+        help="Enable Gradio's public sharing tunnel (requires network access).",
+    ),
+):
+    """Launch the Gradio GUI."""
+    try:
+        launch_gui(server_name=server_name, server_port=server_port, share=share)
+    except KeyboardInterrupt:
+        typer.echo("GUI stopped by user.")
+    except Exception as exc:
+        typer.echo(f"Failed to start GUI: {exc}")
+        raise typer.Exit(1)
 
 
 def main():

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.2.dist-info → uht_tooling-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uht-tooling
-Version: 0.1.2
+Version: 0.1.4
 Summary: Tooling for ultra-high throughput screening workflows.
 Author: Matt115A
 License: MIT
@@ -27,7 +27,7 @@ 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.
+Automation helpers for ultra-high-throughput molecular biology workflows. The package ships both a CLI and an optional GUI that wrap the same workflow code paths.
 
 ---
 
@@ -35,19 +35,20 @@ Automation helpers for ultra-high-throughput molecular biology workflows. The pa
 
 ### Quick install (recommended, easiest file maintainance)
 ```bash
-python -m pip install "uht-tooling[gui]"
+pip install "uht-tooling[gui]==0.1.3"
+
 ```
 
 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
+pip install uht-tooling
 ```
 
 ### Development install
 ```bash
-git clone https://github.com/Matt115A/uht-tooling.git
-cd uht-tooling
+git clone https://github.com/Matt115A/uht-tooling-packaged.git
+cd uht-tooling-packaged
 python -m pip install -e ".[gui,dev]"
 ```
 
@@ -57,7 +58,7 @@ The editable install exposes the latest sources, while the `dev` extras add lint
 
 ## Directory layout
 
-- Reference inputs live under `data/<workflow>/`.
+- Reference inputs can be found anywhere (you specify in the cli), but we recommend using `data/<workflow>/`.
 - Outputs (CSV, FASTA, plots, logs) are written to `results/<workflow>/`.
 - All workflows log to `results/<workflow>/run.log` for reproducibility and debugging.
 
@@ -79,9 +80,9 @@ Each command mirrors a workflow module. Common entry points:
 | `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. |
+| `uht-tooling umi-hunter` | Cluster UMIs and call consensus genes. |
+| `uht-tooling ep-library-profile` | Measure mutation rates in plasmid libraries without UMIs. |
+| `uht-tooling profile-inserts` | Extract and analyse inserts defined by flanking probe pairs. |
 
 Each command provides detailed help, including option descriptions and expected file formats:
 
@@ -107,13 +108,13 @@ You can pass multiple FASTQ paths using repeated `--fastq` options or glob patte
    ```
 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.
+The helper is preloaded with twelve i5 and twelve i7 indices, enabling up to 144 unique amplicons.
 
 #### 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.
+- Confirm primer removal and quantify DNA using electrophoresis (e.g., BioAnalyzer DNA chip) before moving to the flow cell.
 
 ### SLIM primer design
 
@@ -158,7 +159,7 @@ Mutation nomenclature examples:
   ```
 - Outputs include primer sets and an assembly-plan CSV.
 
-If mutations fall within overlapping primer windows, design sequential reactions to avoid excessive primer reuse.
+If mutations fall within overlapping primer windows, design sequential reactions. 
 
 ### Mutation caller (no UMIs)
 
@@ -175,7 +176,7 @@ If mutations fall within overlapping primer windows, design sequential reactions
      --output-dir results/mutation_caller/ \
      --threshold 10
    ```
-3. Outputs: per-sample subdirectories with substitution summaries, co-occurrence matrices, and logs.
+3. Outputs: per-sample subdirectories with substitution summaries, co-occurrence matrices, and logs. Co-occurence matrices are experimental and are not yet to be relied on.
 
 ### UMI Hunter
 
@@ -188,7 +189,12 @@ 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`.
+- 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.
 
 ### Profile inserts
 
@@ -229,7 +235,7 @@ 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.
+- 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 to interface with the GUI.
 - 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.
 
@@ -238,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.2.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=G8eDBtw_YgcYV7ynk_YD9W2ua0a0pqGCqud5VaHsB6M,11695
+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.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,,
+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,,