Check bulk expression tables against single-cell reference IDs and metadata before deconvolution. Runs locally with Python 3.11+ and no runtime dependencies.
From this checkout, in a virtual environment:
python -m pip install .
deconv-preflight check \
--bulk examples/valid/bulk.tsv \
--reference-genes examples/valid/reference_genes.txt \
--reference-cells examples/valid/reference_cells.txt \
--metadata examples/valid/metadata.tsvExpected: 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.
| 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.
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.
python -m unittest discover -s tests -v