# LGASieve

LGASieve contains two related BRCA1/2 large-genomic-alteration workflows:

1. The original BAM-level research caller, which combines read depth,
   breakpoint evidence, and germline allele balance.
2. `lgasieve-depth`, a broad-panel, control-anchored research screen designed
   to send deletion/duplication candidates to independent dosage
   confirmation.

BRCA exon-level deletion/duplication detection by targeted NGS is clinically
established. This repository is research software and has not undergone the
assay-specific analytical and clinical validation required for patient
reporting.

## Control-anchored clinical screen

The screen requires:

- a target manifest with at least 20 stable, non-reportable control bins;
- disjoint normal cohorts for model fitting and null calibration;
- a site-, chemistry-, and assay-matched model;
- counts for the complete normalization domain, not only BRCA1/2;
- an independent method such as MLPA, exon-focused aCGH, or ddPCR to confirm
  every positive screen.

Target manifest (`targets.tsv`):

```text
target_id	gene	exon	order	reportable
CTRL_0001	CONTROL	1	1	0
BRCA1_E02	BRCA1	2	2	1
```

Count matrices contain one row per sample and one column per target:

```text
sample	CTRL_0001	BRCA1_E02
normal_001	412	387
```

Fit a model:

```shell
lgasieve-depth fit \
  --targets targets.tsv \
  --fit-counts fit_normals.tsv \
  --calibration-counts calibration_normals.tsv \
  --components 12 \
  --alpha 0.01 \
  --out site_assay_model.json
```

Screen samples:

```shell
lgasieve-depth screen \
  --model site_assay_model.json \
  --counts cases.tsv \
  --out screen_results.json
```

Result states are:

- `REFLEX_POSITIVE`: one or more NGS candidates require independent
  confirmation;
- `NO_REFLEX_FLAG`: the research model emitted no referral flag and the
  software's frozen target mask is complete; this is not a clinical negative;
- `NO_CANDIDATE_PARTIAL_COVERAGE`: no candidate was observed, but one or more
  reportable targets are excluded, so no negative interpretation is
  permitted;
- `NO_CALL_QC`: sample-level depth or noise failed.

All fitted nuisance structure comes from the fit cohort. The untouched
calibration cohort sets one joint DEL/DUP, all-window empirical threshold.
The fit command rejects overlapping sample IDs, duplicate count rows, and a
calibration cohort too small to resolve the requested family error rate.
Version-1 model files are intentionally refused and must be refitted into the
strict version-2 format.

Model fitting, synthetic software verification, and absence of a referral flag
are not substitutes for laboratory validation or clinical interpretation.

## Verification

Run the automated tests:

```shell
python -m pytest -q
```

Run the synthetic full-panel software verification:

```shell
python -m scripts.clinical_panel_simulation \
  --validation-seed-offset 1000 \
  --output analysis/clinical_panel_simulation_final.json \
  --model analysis/anchored_clinical_depth_model_final.json
```