Evidence-based reference compatibility assessment for genomic data.
RefCompat examines whether genomic resources can be used together against a selected reference FASTA. It checks sequence identity, reference declarations, and coordinate usage, distinguishing demonstrated conflicts from questions the available evidence cannot answer.
For example, chr1 and 1 may identify the same sequence, but names alone cannot establish that. Conversely, matching contig names do not guarantee matching sequence content. RefCompat uses verifiable evidence rather than assuming either relationship.
Status: Pre-alpha. The underlying engine implements the assessments below, but the public CLI currently provides only FASTA, .fai, and .dict diagnostics. Whole-dataset compatibility assessment is not yet exposed as a public CLI command.
RefCompat supports Python 3.10–3.14. The current way to run it is from a source checkout using uv:
git clone https://github.com/GregRR/refcompat.git
cd refcompat
uv sync --lockedTry these commands with the small example files included in the repository:
uv run refcompat inspect-fasta tests/fixtures/fasta/ga4gh_base.fa
uv run refcompat check-fai tests/fixtures/fai/htslib_example.fa tests/fixtures/fai/htslib_example.fa.fai
uv run refcompat check-dict tests/fixtures/fasta/ga4gh_base.fa tests/fixtures/dict/ga4gh_base.dictThe example index and dictionary each match their corresponding FASTA. The index check reports exact structural match: yes and no differences. Replace the fixture paths with your own files to inspect your reference and its companions.
All three commands accept --format json for machine-readable diagnostics. Use uv run refcompat --help to see the available commands.
Exit codes: 0 means a diagnostic completed, even if it found a mismatch; 2 indicates an input or execution error. These diagnostics do not return a whole-dataset compatibility verdict. Their JSON output is separate from the versioned whole-bundle report schema.
| Resource | What RefCompat evaluates |
|---|---|
| FASTA | Sequence content identity using GA4GH refget and sequence-collection identifiers. |
FASTA index (.fai) |
Index structure and consistency with the FASTA. |
Sequence dictionary (.dict) |
Sequence names, lengths, order, and declared MD5 identities relative to the FASTA. |
| VCF and BCF2 | Reference declarations, exhaustive REF-allele comparison against the selected FASTA, and evidence-backed cross-name sequence binding. |
| BAM and CRAM | Header sequence dictionaries, declared sequence identities, and reference relationships; not alignment records. |
| GTF and GFF3 | Feature coordinate bounds, sequence-region declarations, and supported annotation-owned sequence evidence. |
| BED | Streaming structural validation of standard BED3–BED9 and BED12, including zero-based, half-open intervals. BED-to-FASTA bounds evaluation is not yet implemented. |
The engine can also evaluate requirements across resources relative to an explicitly selected FASTA, preserving the provenance of supporting evidence and identifying unresolved questions. An optional UCSC preflight profile uses explicitly selected database context and supports reproducible offline snapshots.
These capabilities exist in Python components and internal workflows; the public CLI and Python API do not yet expose all of them as supported user interfaces. See the check specifications for the exact scope and limitations.
Whole-bundle reasoning distinguishes four conclusions:
COMPATIBLE— Evaluated mandatory requirements are satisfied.COMPATIBLE_WITH_CONDITIONS— Compatibility depends on stated conditions or scope.INCOMPATIBLE— Verified evidence conflicts with a mandatory requirement.INDETERMINATE— Evidence is insufficient to resolve a required relationship.
Analysis completeness is evaluated separately: an unreadable file or interrupted analysis is not treated as a genomic incompatibility.
RefCompat is read-only. It does not rename contigs, modify variants or alignment headers, realign reads, or perform coordinate liftover. Header-only CRAM analysis does not retrieve reference data.
- Documentation index — guides and detailed technical topics
- Check specifications — what each check establishes
- Compatibility model — requirements, evidence, and verdicts
- Report contract — structured output and schema versions
- Design — architecture and scientific decisions
- Development guide — local development and tests
- Roadmap — planned functionality
- Changelog — changes between versions
See CONTRIBUTING.md for development guidance and scientific review priorities. Report bugs or suggest features through GitHub Issues.
RefCompat is licensed under Apache License 2.0. Attribution information is in NOTICE and third-party notices. For research citations, see CITATION.cff.