uht-tooling 0.1.2__tar.gz

uht_tooling-0.1.2/PKG-INFO

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

uht_tooling-0.1.2/README.md

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

uht_tooling-0.1.2/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uht-tooling"
+version = "0.1.2"
+description = "Tooling for ultra-high throughput screening workflows."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Matt115A" }]
+dependencies = [
+    "biopython==1.85",
+    "fuzzywuzzy==0.18.0",
+    "matplotlib==3.10.7",
+    "pandas==2.3.3",
+    "python-Levenshtein==0.27.3",
+    "pyyaml==6.0.3",
+    "pysam==0.23.3",
+    "scipy==1.15.3",
+    "seaborn==0.13.2",
+    "tabulate==0.9.0",
+    "tqdm==4.67.1",
+    "typer==0.20.0",
+]
+
+[project.optional-dependencies]
+gui = ["gradio==5.49.1"]
+dev = ["pytest==9.0.0", "black==25.9.0", "ruff==0.14.4"]
+
+[project.scripts]
+uht-tooling = "uht_tooling.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

uht_tooling-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uht_tooling-0.1.2/src/uht_tooling/__init__.py

@@ -0,0 +1,10 @@
+"""Core package initialization for uht_tooling."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("uht-tooling")
+except PackageNotFoundError:
+    __version__ = "0.0.0"