read_variant_calls
Read-only
Read a variant call set (VCF, bgzipped VCF or BCF) in this project and return the records matching a query: a locus, a variant class, a QUAL floor, PASS-only, a sample that is not hom-ref, or an INFO key. Every answer says what it read over and what it filtered on, so a count can never be mistaken for the file's total. A call set too large to read whole opens at its header, and a locus is then the way in rather than an option.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | last base of the region, 1-based and inclusive. Needs `contig`. Unset is the contig's last record. | |
| file | No | which call set in this project, by name. Unset, it is the project's only one, and it refuses rather than guessing when there is more than one. | |
| limit | No | how many matching records to return. The COUNT is always the full number of matches: this caps the rows, never the accounting. | |
| start | No | first base of the region, 1-based and inclusive, as VCF itself counts. Needs `contig`. Unset is the contig's first record. | |
| types | No | keep only these variant classes. The classes are htslib's own, assigned by the ported `setVariantType` and identical to the ones the panel's type filter offers. Unset keeps every class. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| contig | No | restrict to one contig, named as the FILE names it: `20` and `chr20` are different names and neither is normalized into the other. With `start`/`end` this is a locus read; alone it is the whole contig. | |
| sample | No | keep only records where this sample's genotype is neither hom-ref nor missing, which is that sample's own variants out of a cohort. Named as the file's header names it. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| info_key | No | keep only records carrying this INFO key; with `info_value`, only those where it equals that value. | |
| min_qual | No | keep only records whose QUAL is at least this. A record stating no QUAL (`.`) is DROPPED unless `include_missing_qual` is on, because a missing score is not a passing one. | |
| pass_only | No | keep only records whose FILTER is PASS or unset (`.`): the usual first question of a call set, and the one filter that changes what most downstream steps should see. | |
| info_value | No | with `info_key`, the value that key must equal. | |
| include_missing_qual | No | keep records that state no QUAL when `min_qual` is set. Off by default: a caller asking for a quality floor is asking about scores, and a record with none has not met it. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| read | Yes | how many records were read before filtering. For a locus read this is the records in that window, NOT the file (`scope` says which) | |
| scope | Yes | whether the numbers describe the whole file or one region, and (when the file was too large to read whole) that its header alone was opened. A count read from a window must never be readable as the file's | |
| matched | Yes | how many records matched: the full count, not the number of rows returned | |
| samples | Yes | the call set's sample names in header order, empty for a sites-only VCF, which is a fact about the file rather than a failure | |
| summary | Yes | what was read and what matched, in one sentence generated from this run | |
| variants | Yes | the matching records, up to `limit`: chrom, pos (1-based), ids, ref, alts, qual, filters, end and the record's own htslib class label. Genotypes are not included: `sample` filters on them and `variant_call_summary` counts them, and a cohort record would otherwise carry thousands of columns per row | |
| filters_applied | Yes | every filter this run actually applied, with its value. A caller comparing two runs needs to know which asked the narrower question |