Skip to content

feat(annotator): add --rle-seq-limit option to vrs-annotate vcf - #700

Open
NopeCharon wants to merge 1 commit into
ga4gh:mainfrom
NopeCharon:issue-347
Open

NopeCharon wants to merge 1 commit into
ga4gh:mainfrom
NopeCharon:issue-347

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

Closes #347.

Problem

Since #660, the maximum length of the optional ReferenceLengthExpression.sequence can be set with the GA4GH_VRS_RLE_SEQ_LIMIT environment variable. For the VCF annotator, that variable was the only option. It applies to the whole process and is read at import time. There was no vrs-annotate option for it, and a VcfAnnotator couldn't be given its own limit. The docs said so too: "the VCF writer still applies the configured output limit".

Changes

  • AbstractVcfAnnotator.__init__() takes an rle_seq_limit argument, defaulting to the configured RLE_SEQ_LIMIT. It is passed to the translator for every allele. That means it sets the sequence in the VRS objects passed to on_vrs_object() and written to PKL/NDJSON. It also replaces the module-level limit used for the VRS_States INFO field, so the VCF and the dumped objects always agree.
  • vrs-annotate vcf has a new --rle-seq-limit option. It takes the same values as the environment variable: a non-negative integer, 0 to omit the sequence, or none (case-insensitive) for no limit. Invalid values exit with a usage error, e.g. Invalid value for '--rle-seq-limit': '-2' is not a non-negative integer or 'none'. When the option isn't given, the configured default is used.
  • docs/extras/vcf_annotator.md documents the option and the constructor argument.

VRS IDs don't change, because the RLE sequence isn't one of the inherent (digested) properties.

Tests

All new tests reuse the existing test_annotate_vcf_rle.yaml cassette. In that input, the ALT of 1-102995989-CTTT-CTTTCTTT is an RLE with length 8:

  • test_annotate_vcf_rle_seq_limit: VcfAnnotator(..., rle_seq_limit=...) overrides the configured default in both directions, for both VRS_States and the NDJSON allele. Examples: 0/4 under the default of 50, 8/None under GA4GH_VRS_RLE_SEQ_LIMIT=4, and 4 under none.
  • test_annotate_vcf_cli_rle_seq_limit: --rle-seq-limit overrides the configured default, and the default is used when the option is omitted.
  • test_annotate_vcf_cli_invalid_rle_seq_limit: -1, 1.5, invalid and an empty value are rejected and no output is written.

So the CLI's option default follows the configured environment, the configured_modules fixture now also reloads ga4gh.vrs.extras.annotator.cli. The new tests fail without the change.

ruff check, ruff format --check and the full test suite (pytest --vcr-record=none, 237 passed) pass locally. I also ran vrs-annotate vcf end to end against the bundled SeqRepo on a chr19 duplication (CATG>CATGCATG). With --rle-seq-limit set to 8, 4, 0 and none, and with and without GA4GH_VRS_RLE_SEQ_LIMIT=4, VRS_States and the NDJSON output came out as expected, and the allele IDs were the same in every run.

The maximum length of the optional ReferenceLengthExpression sequence
could only be changed for the VCF annotator through the
GA4GH_VRS_RLE_SEQ_LIMIT environment variable, which applies to the whole
process. There was no way to set it for a single annotation run, either
from the CLI or when constructing a VcfAnnotator.

- Add an `rle_seq_limit` argument to `AbstractVcfAnnotator.__init__()`,
  defaulting to the configured `RLE_SEQ_LIMIT`. It is passed to the
  translator for every allele, so it controls the sequence in the VRS
  objects that are collected (PKL/NDJSON output, `on_vrs_object()`), and
  it replaces the module-level limit used for the VRS_States INFO field.
- Add a `--rle-seq-limit` option to `vrs-annotate vcf`. Like the
  environment variable, it takes a non-negative integer, 0 to omit the
  sequence, or `none` (case-insensitive) for no limit. Invalid values
  are rejected with a usage error. When the option is not given, the
  configured default is used.
- Document the option and the constructor argument in the VCF annotator
  docs.

VRS IDs are unaffected, since the RLE sequence is not part of the
digest.

Tests reuse the test_annotate_vcf_rle cassette: the constructor argument
overrides the configured default (in both directions) for VRS_States and
NDJSON output, and the CLI option overrides the configured default,
falls back to it when omitted, and rejects invalid values. The
configured_modules fixture now also reloads the CLI module, so its
option default follows the configured environment.

Closes ga4gh#347
@NopeCharon
NopeCharon requested review from a team as code owners November 12, 2026 08:06

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow RLE seq limit to be set in VCF Annotator

1 participant