uht-tooling 0.1.9__tar.gz → 0.3.0__tar.gz

{uht_tooling-0.1.9 → uht_tooling-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uht-tooling
-Version: 0.1.9
+Version: 0.3.0
 Summary: Tooling for ultra-high throughput screening workflows.
 Author: Matt115A
 License-Expression: MIT
@@ -47,7 +47,22 @@ This installs the core workflows plus the optional GUI dependency (Gradio). Omit
 pip install uht-tooling
 ```
 
-You will need a functioning version of mafft - you should install this separately and it should be accessible from your environment.
+### External Tools
+
+Some workflows require external bioinformatics tools:
+
+| Workflow | Required Tools |
+|----------|---------------|
+| mutation-caller | mafft |
+| umi-hunter | mafft |
+| ep-library-profile | minimap2, NanoFilt |
+
+Install via conda:
+```bash
+conda install -c bioconda mafft minimap2 nanofilt
+```
+
+The CLI and GUI will validate tool availability before running and provide clear error messages if tools are missing.
 
 ### Development install
 ```bash
@@ -95,10 +110,69 @@ Each command provides detailed help, including option descriptions and expected
 uht-tooling mutation-caller --help
 ```
 
+### Short Flags
+
+All commands support short flags for common options:
+
+```bash
+# Long form
+uht-tooling design-slim --gene-fasta gene.fa --context-fasta ctx.fa --mutations-csv mut.csv --output-dir out/
+
+# Short form
+uht-tooling design-slim -g gene.fa -c ctx.fa -m mut.csv -o out/
+```
+
+| Long Flag | Short | Commands |
+|-----------|-------|----------|
+| `--gene-fasta` | `-g` | design-slim, design-kld, design-gibson |
+| `--context-fasta` | `-c` | design-slim, design-kld, design-gibson |
+| `--mutations-csv` | `-m` | design-slim, design-kld, design-gibson |
+| `--output-dir` | `-o` | 7 commands |
+| `--log-path` | `-l` | 7 commands |
+| `--template-fasta` | `-t` | mutation-caller, umi-hunter |
+| `--fastq` | `-q` | 4 commands |
+| `--threshold` | `-T` | mutation-caller |
+| `--config-csv` | `-C` | umi-hunter |
+| `--binding-csv` | `-b` | nextera-primers |
+| `--probes-csv` | `-P` | profile-inserts |
+| `--region-fasta` | `-R` | ep-library-profile |
+| `--plasmid-fasta` | `-p` | ep-library-profile |
+| `--work-dir` | `-w` | ep-library-profile |
+| `--config` | `-K` | global (all commands) |
+
 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.
 
 ---
 
+## Configuration File
+
+uht-tooling supports a YAML configuration file for default options.
+
+**Auto-discovery locations** (in order):
+1. `$UHT_TOOLING_CONFIG` environment variable
+2. `~/.uht-tooling.yaml`
+3. `~/.config/uht-tooling/config.yaml`
+4. `.uht-tooling.yaml` (current directory)
+
+Or specify explicitly: `uht-tooling --config my-config.yaml ...`
+
+**Example ~/.uht-tooling.yaml:**
+```yaml
+paths:
+  output_dir: ~/results/uht-tooling
+
+defaults:
+  mutation_caller:
+    threshold: 15
+  umi_hunter:
+    umi_identity_threshold: 0.85
+    min_cluster_size: 5
+```
+
+CLI options always take precedence over config values.
+
+---
+
 ## Workflow reference
 
 ### Nextera XT primer design
@@ -313,13 +387,57 @@ Please be aware, this toolkit will not scale well beyond around 50k reads/sample
     --fastq data/ep-library-profile/*.fastq.gz \
     --output-dir results/ep-library-profile/
   ```
-- Output bundle includes per-sample directories, a master summary TSV, and a `summary_panels` figure that visualises positional mutation rates, coverage, and amino-acid simulations.
+
+**Output structure**
+
+Each sample produces an organized output directory:
+
+```
+sample_name/
+├── KEY_FINDINGS.txt              # Lay-user executive summary
+├── summary_panels.png/pdf        # Main visualization
+├── aa_mutation_consensus.txt     # Consensus estimate details
+├── run.log                       # Analysis log
+└── detailed/                     # Technical outputs
+    ├── methodology_notes.txt     # Documents which lambda drives what
+    ├── lambda_comparison.csv     # Side-by-side lambda comparison
+    ├── gene_mismatch_rates.csv
+    ├── base_distribution.csv
+    ├── aa_substitutions.csv
+    ├── plasmid_coverage.csv
+    ├── aa_mutation_distribution.csv
+    ├── comprehensive_qc_data.csv
+    ├── simple_qc_data.csv
+    └── qc_plots/                 # QC visualizations
+        ├── qc_plot_*.png
+        ├── comprehensive_qc_analysis.png
+        ├── error_analysis.png
+        └── qc_mutation_rate_vs_quality.png/csv
+```
+
+**Lambda estimates: which to use**
+
+The profiler calculates lambda (mutations per gene copy) via two methods:
+
+| Method | Formula | Error Quantified? | Used For |
+|--------|---------|-------------------|----------|
+| Simple | `(hit_rate - bg_rate) × seq_len` | No | KDE plot, Monte Carlo simulation |
+| Consensus | Precision-weighted average across Q-scores | Yes | Recommended for reporting |
+
+- **For publication/reporting**: Use the consensus value from `KEY_FINDINGS.txt` or `aa_mutation_consensus.txt`.
+- **For understanding distribution shape**: See the KDE plot in `summary_panels.png` (note: uses simple lambda).
+- **For detailed error analysis**: See `detailed/comprehensive_qc_data.csv`.
+
+The `KEY_FINDINGS.txt` file provides a plain-language summary including:
+- Expected AA mutations per gene copy
+- Poisson-based interpretation (% wild-type, % 1 mutation, % 2+ mutations)
+- Quality assessment (GOOD/ACCEPTABLE/LOW COVERAGE)
 
 **How the mutation rate and AA expectations are derived**
 
-1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the “target” rate; mismatches elsewhere provide the background.
+1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the "target" rate; mismatches elsewhere provide the background.
 2. The per-base background rate is subtracted from the target rate to yield a net nucleotide mutation rate, and the standard deviation reflects binomial sampling and quality-score uncertainty.
-3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drives the AA mutation mean/variance that appear in the panel plot.
+3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drive the AA mutation mean/variance that appear in the panel plot.
 4. If multiple Q-score thresholds are analysed, the CLI aggregates them via a precision-weighted consensus (1 / standard deviation weighting) after filtering out thresholds with insufficient coverage; the consensus value is written to `aa_mutation_consensus.txt` and plotted as a horizontal guide.
 
 ---

{uht_tooling-0.1.9 → uht_tooling-0.3.0}/README.md

@@ -18,7 +18,22 @@ This installs the core workflows plus the optional GUI dependency (Gradio). Omit
 pip install uht-tooling
 ```
 
-You will need a functioning version of mafft - you should install this separately and it should be accessible from your environment.
+### External Tools
+
+Some workflows require external bioinformatics tools:
+
+| Workflow | Required Tools |
+|----------|---------------|
+| mutation-caller | mafft |
+| umi-hunter | mafft |
+| ep-library-profile | minimap2, NanoFilt |
+
+Install via conda:
+```bash
+conda install -c bioconda mafft minimap2 nanofilt
+```
+
+The CLI and GUI will validate tool availability before running and provide clear error messages if tools are missing.
 
 ### Development install
 ```bash
@@ -66,10 +81,69 @@ Each command provides detailed help, including option descriptions and expected
 uht-tooling mutation-caller --help
 ```
 
+### Short Flags
+
+All commands support short flags for common options:
+
+```bash
+# Long form
+uht-tooling design-slim --gene-fasta gene.fa --context-fasta ctx.fa --mutations-csv mut.csv --output-dir out/
+
+# Short form
+uht-tooling design-slim -g gene.fa -c ctx.fa -m mut.csv -o out/
+```
+
+| Long Flag | Short | Commands |
+|-----------|-------|----------|
+| `--gene-fasta` | `-g` | design-slim, design-kld, design-gibson |
+| `--context-fasta` | `-c` | design-slim, design-kld, design-gibson |
+| `--mutations-csv` | `-m` | design-slim, design-kld, design-gibson |
+| `--output-dir` | `-o` | 7 commands |
+| `--log-path` | `-l` | 7 commands |
+| `--template-fasta` | `-t` | mutation-caller, umi-hunter |
+| `--fastq` | `-q` | 4 commands |
+| `--threshold` | `-T` | mutation-caller |
+| `--config-csv` | `-C` | umi-hunter |
+| `--binding-csv` | `-b` | nextera-primers |
+| `--probes-csv` | `-P` | profile-inserts |
+| `--region-fasta` | `-R` | ep-library-profile |
+| `--plasmid-fasta` | `-p` | ep-library-profile |
+| `--work-dir` | `-w` | ep-library-profile |
+| `--config` | `-K` | global (all commands) |
+
 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.
 
 ---
 
+## Configuration File
+
+uht-tooling supports a YAML configuration file for default options.
+
+**Auto-discovery locations** (in order):
+1. `$UHT_TOOLING_CONFIG` environment variable
+2. `~/.uht-tooling.yaml`
+3. `~/.config/uht-tooling/config.yaml`
+4. `.uht-tooling.yaml` (current directory)
+
+Or specify explicitly: `uht-tooling --config my-config.yaml ...`
+
+**Example ~/.uht-tooling.yaml:**
+```yaml
+paths:
+  output_dir: ~/results/uht-tooling
+
+defaults:
+  mutation_caller:
+    threshold: 15
+  umi_hunter:
+    umi_identity_threshold: 0.85
+    min_cluster_size: 5
+```
+
+CLI options always take precedence over config values.
+
+---
+
 ## Workflow reference
 
 ### Nextera XT primer design
@@ -284,13 +358,57 @@ Please be aware, this toolkit will not scale well beyond around 50k reads/sample
     --fastq data/ep-library-profile/*.fastq.gz \
     --output-dir results/ep-library-profile/
   ```
-- Output bundle includes per-sample directories, a master summary TSV, and a `summary_panels` figure that visualises positional mutation rates, coverage, and amino-acid simulations.
+
+**Output structure**
+
+Each sample produces an organized output directory:
+
+```
+sample_name/
+├── KEY_FINDINGS.txt              # Lay-user executive summary
+├── summary_panels.png/pdf        # Main visualization
+├── aa_mutation_consensus.txt     # Consensus estimate details
+├── run.log                       # Analysis log
+└── detailed/                     # Technical outputs
+    ├── methodology_notes.txt     # Documents which lambda drives what
+    ├── lambda_comparison.csv     # Side-by-side lambda comparison
+    ├── gene_mismatch_rates.csv
+    ├── base_distribution.csv
+    ├── aa_substitutions.csv
+    ├── plasmid_coverage.csv
+    ├── aa_mutation_distribution.csv
+    ├── comprehensive_qc_data.csv
+    ├── simple_qc_data.csv
+    └── qc_plots/                 # QC visualizations
+        ├── qc_plot_*.png
+        ├── comprehensive_qc_analysis.png
+        ├── error_analysis.png
+        └── qc_mutation_rate_vs_quality.png/csv
+```
+
+**Lambda estimates: which to use**
+
+The profiler calculates lambda (mutations per gene copy) via two methods:
+
+| Method | Formula | Error Quantified? | Used For |
+|--------|---------|-------------------|----------|
+| Simple | `(hit_rate - bg_rate) × seq_len` | No | KDE plot, Monte Carlo simulation |
+| Consensus | Precision-weighted average across Q-scores | Yes | Recommended for reporting |
+
+- **For publication/reporting**: Use the consensus value from `KEY_FINDINGS.txt` or `aa_mutation_consensus.txt`.
+- **For understanding distribution shape**: See the KDE plot in `summary_panels.png` (note: uses simple lambda).
+- **For detailed error analysis**: See `detailed/comprehensive_qc_data.csv`.
+
+The `KEY_FINDINGS.txt` file provides a plain-language summary including:
+- Expected AA mutations per gene copy
+- Poisson-based interpretation (% wild-type, % 1 mutation, % 2+ mutations)
+- Quality assessment (GOOD/ACCEPTABLE/LOW COVERAGE)
 
 **How the mutation rate and AA expectations are derived**
 
-1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the “target” rate; mismatches elsewhere provide the background.
+1. Reads are aligned to both the region of interest and the full plasmid. Mismatches in the region define the "target" rate; mismatches elsewhere provide the background.
 2. The per-base background rate is subtracted from the target rate to yield a net nucleotide mutation rate, and the standard deviation reflects binomial sampling and quality-score uncertainty.
-3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drives the AA mutation mean/variance that appear in the panel plot.
+3. The net rate is multiplied by the CDS length to estimate λ_bp (mutations per copy). Monte Carlo simulations then flip random bases, translate the mutated CDS, and count amino-acid differences across 1,000 trials—these drive the AA mutation mean/variance that appear in the panel plot.
 4. If multiple Q-score thresholds are analysed, the CLI aggregates them via a precision-weighted consensus (1 / standard deviation weighting) after filtering out thresholds with insufficient coverage; the consensus value is written to `aa_mutation_consensus.txt` and plotted as a horizontal guide.
 
 ---

{uht_tooling-0.1.9 → uht_tooling-0.3.0}/pyproject.toml

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