uht-tooling 0.1.2__tar.gz → 0.1.4__tar.gz

{uht_tooling-0.1.2 → uht_tooling-0.1.4}/PKG-INFO

@@ -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 → uht_tooling-0.1.4}/README.md

@@ -1,6 +1,6 @@
 # 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.
 
 ---
 
@@ -8,19 +8,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]"
 ```
 
@@ -30,7 +31,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.
 
@@ -52,9 +53,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:
 
@@ -80,13 +81,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
 
@@ -131,7 +132,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)
 
@@ -148,7 +149,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
 
@@ -161,7 +162,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
 
@@ -202,7 +208,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.
 
@@ -211,9 +217,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 → uht_tooling-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uht-tooling"
-version = "0.1.2"
+version = "0.1.4"
 description = "Tooling for ultra-high throughput screening workflows."
 readme = "README.md"
 requires-python = ">=3.8"

{uht_tooling-0.1.2 → uht_tooling-0.1.4}/src/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():