Re1nhard-1 / deconv-preflight

# deconv-preflight
Check bulk expression tables against single-cell reference IDs and metadata before
deconvolution. Runs locally with Python 3.11+ and no runtime dependencies.
## Install and try
From this checkout, in a virtual environment:
 [code] 
Expected: `PASS: 0 error(s), 0 warning(s)`. These small fixtures are synthetic.
Replace `valid/bulk.tsv` and `valid/metadata.tsv` with the `broken/` versions to
see failures. For a public-data example, see PBMC3k.
## Inputs
| Flag | Format |
| --- | --- |
| `--bulk` | CSV/TSV; first column `gene_id`, other columns unique sample IDs; non-negative finite values |
| `--reference-genes` | One gene ID per line, no header |
| `--reference-cells` | One cell ID per line, in reference matrix order, no header |
| `--metadata` | CSV/TSV with `cell_id`, `donor_id`, `cell_type`; one row per reference cell |
UTF-8 and gzip (`.gz`) are supported. Extra metadata columns are ignored.
IDs must be unique and match exactly; no automatic mapping, trimming or reordering.
See reference export examples.
## Results
Errors include missing/duplicate IDs, invalid values, mismatched cells, zero-only
samples, and samples without positive expression on shared genes. Warnings flag
cell order, single donors, incomplete donor coverage and fractional values.
- `--json report.json`: create a new report; existing files are never overwritten.
- `--json -`: JSON only on standard output.
- `--strict`: return failure for warnings too.
- `--min-shared-genes N`: warn below your chosen expressed-gene overlap threshold.
Exit codes: **0** checks passed (warnings allowed), **1** validation failure,
**2** invocation or file error. JSON includes finding codes, details and overlap counts.
This alpha checks exported input structure only. It does not check reference
expression values, normalization, tissue/species compatibility or scientific
validity, and does not run deconvolution. Inputs stay unchanged and are not uploaded.
Reports can contain your identifiers; review before sharing. No PyPI release yet.
## Development
 [code] 
Contributing · Changes · MIT license