Julenmendieta/milab 6793 last tweaks

[julenmendieta]

Greptile Summary

This PR adjusts fitted-distribution verdict calling, per-barcode QC status, histogram output, workflow exports, and their UI controls. Important touched terms:

• Bound probability — the minimum fitted signal-component probability required to call a cell bound; it is now configurable from 0.9 to 1 and recorded with the run.
• Expected binder fraction — the estimated share of binding cells used to initialize the two-component fit; it is now configurable and defaults to 10%.
• Fitted background — the per-sample, per-barcode count distribution and mixture fit used by the distribution baseline; its bins now include silent cells, expose a bound-count marker, and can be selected by sample.
• Undeclared barcode share — one undeclared sequence’s share of all pre-refinement reads in its sample; status now evaluates each sequence independently, warning above 1% and alerting above 5%.
• Raw tag UMI count — the per-cell, per-tag count before the verdict count floor; it is now emitted, imported, and exported for downstream composition views.
• Tag order — panel declaration order for barcodes; it is now carried in the histogram payload to keep panel positions stable across samples.

Confidence Score: 4/5

The PR should not merge until the Python execution boundary rejects invalid bound-probability values that otherwise produce silently incorrect verdicts.

The newly configurable cutoff can bypass the Python validation and cause all cells to be classified as not bound while the accompanying fitted-background threshold reports contradictory information.

Files Needing Attention: software/per-cell-metrics/src/emit_verdicts.py, software/per-cell-metrics/src/verdict.py, software/per-cell-metrics/src/tag_distribution.py

Important Files Changed

Filename	Overview
software/per-cell-metrics/src/emit_verdicts.py	Threads new fit settings through verdict generation and adds QC/raw-count artifacts, but bound-probability validation accepts invalid non-finite and above-one values.
software/per-cell-metrics/src/tag_distribution.py	Changes mixture initialization, retains per-pair histogram bins and probability curves, and derives display thresholds from fitted probabilities.
software/per-cell-metrics/src/qc_measures.py	Adds vectorized status evaluation and absolute log1p histogram edges while changing undeclared-barcode status thresholds.
model/src/index.ts	Extends the persisted-to-workflow settings contract, validation, defaults, and fitted-bin output type.
workflow/src/verdict-args.lib.tengo	Adds explicit CLI propagation and defaults for bound probability and expected binder fraction.
workflow/src/verdict-import.tpl.tengo	Imports the new pre-floor per-cell/tag count artifact into a dedicated result frame.
ui/src/pages/MainPage.vue	Adds controls and explanations for fitted-distribution initialization and calling thresholds.
ui/src/pages/AntigenQcPage.vue	Hides unstable tabs during execution and scopes fitted-background plots with a sample selector.
ui/src/components/CountHistogram.vue	Adapts histogram rendering to shared absolute log1p edges and pads shorter per-pair distributions with empty trailing bins.
ui/src/components/FittedBackgroundGrid.vue	Orders barcodes consistently, supports sample scoping, and displays per-fit bound-count markers and diagnostics.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  UI[Verdict settings UI] --> Model[Validated BlockArgs]
  Model --> Args[Workflow CLI arguments]
  Args --> Fit[Per-sample tag distribution fit]
  Fit --> Calls[Cell binding calls]
  Fit --> Bins[Fitted-background bins and thresholds]
  Calls --> Verdicts[Clonotype verdict outputs]
  Bins --> QC[Run-quality UI]
  Raw[Pre-floor cell/tag counts] --> Export[Downstream composition export]

Loading

Prompt To Fix All With AI

### Issue 1
software/per-cell-metrics/src/emit_verdicts.py:304-310
**Invalid bound probabilities pass**

When a direct invocation supplies `NaN`, infinity, or a value above 1, this lower-bound-only validation accepts it. `read_states` then classifies every otherwise reliable cell as not bound, while `NaN` makes `bound_at_count` report the lowest count as the threshold, causing the verdicts and fitted-background marker to disagree silently.

```suggestion
    if not DISTRIBUTION_BOUND_PROBABILITY <= args.bound_probability <= 1.0:
        raise SystemExit(
            f"--bound-probability must be at least {DISTRIBUTION_BOUND_PROBABILITY} and at most 1. "
            f"Below that a cell holding none of a tag could be called bound. Most cells hold none of most tags, "
            f"and the run counts them by arithmetic rather than checking each one, so those cells would be counted "
            f"not-bound in one place and called bound in another. Got {args.bound_probability}."
        )
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Changeset" | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used (5)

• Knowledge Base — Feature integration workflow
• Knowledge Base — Verdict analysis workflow stages
• Knowledge Base — Integration domain model
• Knowledge Base — Feature integration user interface
• Knowledge Base — Reduce antigen-reading memory and correct barcode shares

[greptile-apps]

Invalid bound probabilities pass

When a direct invocation supplies NaN, infinity, or a value above 1, this lower-bound-only validation accepts it. read_states then classifies every otherwise reliable cell as not bound, while NaN makes bound_at_count report the lowest count as the threshold, causing the verdicts and fitted-background marker to disagree silently.

Suggested change

	if args.bound_probability < DISTRIBUTION_BOUND_PROBABILITY:
	raise SystemExit(
	f"--bound-probability must be at least {DISTRIBUTION_BOUND_PROBABILITY}. Below that a cell "
	f"holding none of a tag could be called bound. Most cells hold none of most tags, and the run "
	f"counts them by arithmetic rather than checking each one, so those cells would be counted "
	f"not-bound in one place and called bound in another. Got {args.bound_probability}."
	)
	if not DISTRIBUTION_BOUND_PROBABILITY <= args.bound_probability <= 1.0:
	raise SystemExit(
	f"--bound-probability must be at least {DISTRIBUTION_BOUND_PROBABILITY} and at most 1. "
	f"Below that a cell holding none of a tag could be called bound. Most cells hold none of most tags, "
	f"and the run counts them by arithmetic rather than checking each one, so those cells would be counted "
	f"not-bound in one place and called bound in another. Got {args.bound_probability}."
	)

Knowledge Base Used:

• Integration domain model
• Verdict analysis workflow stages

Prompt To Fix With AI

This is a comment left during a code review.
Path: software/per-cell-metrics/src/emit_verdicts.py
Line: 304-310

Comment:
**Invalid bound probabilities pass**

When a direct invocation supplies `NaN`, infinity, or a value above 1, this lower-bound-only validation accepts it. `read_states` then classifies every otherwise reliable cell as not bound, while `NaN` makes `bound_at_count` report the lowest count as the threshold, causing the verdicts and fitted-background marker to disagree silently.

```suggestion
    if not DISTRIBUTION_BOUND_PROBABILITY <= args.bound_probability <= 1.0:
        raise SystemExit(
            f"--bound-probability must be at least {DISTRIBUTION_BOUND_PROBABILITY} and at most 1. "
            f"Below that a cell holding none of a tag could be called bound. Most cells hold none of most tags, "
            f"and the run counts them by arithmetic rather than checking each one, so those cells would be counted "
            f"not-bound in one place and called bound in another. Got {args.bound_probability}."
        )
```

**Knowledge Base Used:**
- [Integration domain model](https://app.greptile.com/milaboratories/-/custom-context/knowledge-base/platforma-open/feature-integration/-/docs/integration-domain-model.md)
- [Verdict analysis workflow stages](https://app.greptile.com/milaboratories/-/custom-context/knowledge-base/platforma-open/feature-integration/-/docs/workflow-verdict-analysis.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.