Skip to content

feat(annotator): write VRS alleles as JSON Lines with --jsonl-out - #697

Open
NopeCharon wants to merge 2 commits into
ga4gh:mainfrom
NopeCharon:issue-554
Open

NopeCharon wants to merge 2 commits into
ga4gh:mainfrom
NopeCharon:issue-554

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

Closes #554.

Problem

vrs-annotate vcf --ndjson-out and VcfAnnotator.annotate(output_ndjson_path=...) write one JSON object per line, which is JSON Lines. As discussed in the issue, the file already conforms to JSON Lines, so this changes only the names. Renaming the option and kwarg outright would break existing scripts and VcfAnnotator callers. So this follows the approach used for translate_from/translate_to (#679): add the new names on main and deprecate the old ones until v3.

Changes

  • New --jsonl-out CLI option, output_jsonl_path kwarg (VcfAnnotator.jsonl_arg_name) and dump_alleles_to_jsonl(). The output file is the same as before.
  • Deprecated aliases, to be removed in v3:
    • --ndjson-out still works but is hidden from --help and prints a deprecation warning to stderr.
    • output_ndjson_path emits a DeprecationWarning (attributed to the caller of annotate()) and is mapped to output_jsonl_path.
    • dump_alleles_to_ndjson() is marked @deprecated and calls dump_alleles_to_jsonl().
    • Passing both an old and a new name is an error (VcfAnnotatorArgsError / CLI usage error), not a silent choice.
  • Docstrings and the "no output path" error messages now say "JSON Lines" and --jsonl-out/output_jsonl_path.
  • docs/extras/vcf_annotator.md gets an "Output Options" section documenting --vcf-out, --pkl-out and --jsonl-out.

vrs-in-a-box/README.md still uses --ndjson-out. It runs the published 2.1.2 image, which doesn't have --jsonl-out, and the deprecated option keeps working.

Tests

In tests/extras/test_annotate_vcf.py, using the local test SeqRepo, so no new cassettes are needed:

  • test_annotate_vcf_jsonl_only: output_jsonl_path writes the JSON Lines dump and no other output.
  • test_annotate_vcf_ndjson_deprecated: output_ndjson_path warns (pointing at the caller), still writes the dump, and is rejected together with output_jsonl_path.
  • test_dump_alleles_to_ndjson_deprecated: the deprecated function warns and writes the same output.
  • test_annotate_vcf_cli_jsonl (--jsonl-out and --ndjson-out) and test_annotate_vcf_cli_jsonl_and_ndjson: the CLI options through click.testing.CliRunner.
  • test_annotate_vcf_input_validation: updated for the new error message.

The annotator's newline-delimited JSON dump was named NDJSON, but the
format we write (one JSON object per line, no blank lines) is JSON Lines,
which is the name the project wants to use.

* Add `--jsonl-out` to `vrs-annotate vcf`, the `output_jsonl_path` kwarg
  (`VcfAnnotator.jsonl_arg_name`) to `VcfAnnotator.annotate()` and
  `dump_alleles_to_jsonl()`. The written file is unchanged.
* Keep `--ndjson-out`, `output_ndjson_path` and `dump_alleles_to_ndjson()`
  working as deprecated aliases until v3: the CLI option is hidden from
  `--help` and prints a deprecation warning, the kwarg emits a
  DeprecationWarning pointing at the caller and is mapped to
  `output_jsonl_path`, and the function is marked `@deprecated`, as done
  for the translator methods renamed in v3. Passing both the old and new
  name is rejected.
* Use "JSON Lines" in docstrings and error messages, and document the
  annotator's output options, including `--jsonl-out`, in the VCF
  annotator docs.

Tests cover JSON Lines output from the library and the CLI, and the
deprecated option, kwarg and function.

Closes ga4gh#554
@NopeCharon
NopeCharon requested review from a team as code owners November 11, 2026 16:56
Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com>

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.

Replace ndjson with jsonl

1 participant