`HgvsTools.is_intronic` misses intronic `r.` (RNA) variants
- Dominant language
- Python
- Stars
- 62
- Forks
- 42
- Avg merge
- 1h 2m
- Merged PRs (30d)
- 1
Description
## Summary
`HgvsTools.is_intronic` gates on the outer `sv.posedit.pos` being a `hgvs.location.BaseOffsetInterval`. The hgvs library (2.0.0a0) emits `BaseOffsetInterval` for `c.` and `n.` variants but wraps `r.` (RNA) endpoints in a plain `Interval`, even though the inner positions are still `BaseOffsetPosition`s carrying `is_intronic=True`. The outer-type gate therefore silently returns `False` for intronic `r.` inputs.
Both translator paths (`AlleleTranslator._from_hgvs` via `extract_allele_values`, and `CnvTranslator._from_hgvs`) rely on this check to reject intronic inputs before building a `SequenceLocation`. When the check is bypassed, downstream code accesses `pos.start.base` / `pos.end.base` and drops the intron offset, producing a `SequenceLocation` whose coordinates point at the exon-boundary position in the mature transcript rather than signaling an unrepresentable variant.
Per [VRS 2.0 — Implied Sequence Coordinates](https://vrs.ga4gh.org/en/latest/concepts/LocationAndReference/SequenceLocation.html#implied-sequence-coordinates), offset positions representing sequence not found on the `SequenceReference` cannot be encoded as VRS `start`/`end` values at all. Intronic HGVS inputs should therefore be rejected — which is what `is_intronic` is meant to do, and does correctly for `c.`/`n.` but not `r.`.
## Reproducer
```python
from ga4gh.vrs.utils.hgvs_tools import HgvsTools
from ga4gh.vrs.dataproxy import SeqRepoRESTDataProxy
dp = SeqRepoRESTDataProxy(
base_url="http://localhost:5000/seqrepo", disable_healthcheck=True
)
ht = HgvsTools(dp)
for expr in [
"NM_000001.1:c.100+5A>T", # c. intronic — correctly detected
"NR_000001.1:n.100+5A>T", # n. intronic — correctly detected
"NM_000001.1:r.100+5a>u", # r. intronic — silently missed
]:
sv = ht.parse(expr)
print(expr, "→ is_intronic:", ht.is_intronic(sv))
```
Output (current):
```
NM_000001.1:c.100+5A>T → is_intronic: True
NR_000001.1:n.100+5A>T → is_intronic: True
NM_000001.1:r.100+5a>u → is_intronic: False ← should be True
```
## Real-world `r.` examples from ClinVar
The following `r.` expressions come from ClinVar.
All four parse cleanly under `hgvs 2.0.0a0`
and exhibit the same `Interval` + `BaseOffsetPosition` shape that motivates
this issue. They are **all exonic** (`offset=0`), so they are not affected
by the bug — they are correctly classified as non-intronic by both the
current and proposed `is_intronic` implementations. They are listed here as
representative real-world `r.` inputs to pin in future regression tests.
| Expression | Outer pos | Inner type | `offset` | Intronic? |
|---|---|---|---|---|
| `NR_001566.1:r.398_399del` | `Interval` | `BaseOffsetPosition` | 0 / 0 | No |
| `NR_001566.1:r.245del` | `Interval` | `BaseOffsetPosition` | 0 / 0 | No |
| `NM_001374385.1:r.2843_2931del` | `Interval` | `BaseOffsetPosition` | 0 / 0 | No |
| `NM_001323289.2:r.2632c>a` | `Interval` | `BaseOffsetPosition` | 0 / 0 | No |
These examples confirm two relevant properties of the parser:
1. The `Interval` + `BaseOffsetPosition` wrapping is consistent across `r.`
inputs regardless of edit type (`del`, `>`) or accession namespace
(`NM_*` or `NR_*`). The proposed per-endpoint `isinstance` check will
classify all four as non-intronic and allow them through.
2. The bug surfaces only when a *hypothetical* intronic counterpart
(e.g. `NM_001374385.1:r.2843+1_2931del`) is encountered. No such example
exists in the ClinVar set we inspected, which may be why the gap has not
been reported before.
If someone has a real intronic `r.` example from a curated source, it
should be added to the regression test matrix below.
## Why the outer gate is wrong
Walking the parser's output for each prefix:
| Input | Outer `sv.posedit.pos` | Inner `.start` / `.end` | `is_intronic(sv)` should be |
|---|---|---|---|
| `g.100_200del` | `Interval` | `SimplePosition` | False (g. has no intronic concept) |
| `c.100+5A>T` | `BaseOffsetInterval` | `BaseOffsetPosition(offset=5)` | True |
| `c.100A>T` | `BaseOffsetInterval` | `BaseOffsetPosition(offset=0)` | False |
| `n.100+5A>T` | `BaseOffsetInterval` | `BaseOffsetPosition(offset=5)` | True |
| `r.100+5a>u` | **`Interval`** | `BaseOffsetPosition(offset=5)` | True (currently returns False) |
| `g.(A_B)_(C_D)del` | `Interval(uncertain=True)` | nested `Interval` of `SimplePosition` | False (parser forbids uncertain on c./n./r., so no intronic-uncertain combination is reachable) |
The `r.` row is the only case where the outer-gate check disagrees with the correct answer.
## Proposed fix
Replace the container-type gate with per-endpoint `isinstance` checks on `BaseOffsetPosition`:
```python
def is_intronic(self, sv: HgvsSequenceVariant) -> bool:
"""Check if the given SequenceVariant is intronic.
Tests each endpoint directly rather than gating on the outer container
type. hgvs 2.0.0a0 wraps the BaseOffsetPosition endpoints of ``r.`` (RNA)
variants in a plain ``Interval`` (not ``BaseOffsetInterval``); a
container-only gate silently misses ``r.`` intronic forms like
``r.100+5a>u``.
Returns:
bool: True if either endpoint is a :class:`BaseOffsetPosition` with
a non-zero (or ``None``) offset.
"""
start = sv.posedit.pos.start
end = sv.posedit.pos.end
return (
isinstance(start, hgvs.location.BaseOffsetPosition) and start.is_intronic
) or (
isinstance(end, hgvs.location.BaseOffsetPosition) and end.is_intronic
)
```
### Behavior preservation across existing cases
- `g.*` inputs: `SimplePosition` endpoints fail both `isinstance` checks → `False` (unchanged)
- `c.`/`n.` exonic: `BaseOffsetPosition(offset=0)` → `isinstance` True, `is_intronic` False → `False` (unchanged)
- `c.`/`n.` intronic (either side): `is_intronic` True on at least one endpoint → `True` (unchanged)
- UTR forms like `c.-10` / `c.*10`: `BaseOffsetPosition(offset=0)` → `False` (unchanged)
- Uncertain ranges on `g.`: inner endpoints are nested `Interval`, not `BaseOffsetPosition` → `False` (unchanged; correct since `g.` has no intronic concept)
- **`r.` intronic: now returns `True`** — this is the fix.
### Callsites require no changes
Both existing guards — [src/ga4gh/vrs/utils/hgvs_tools.py:282-284](https://github.com/ga4gh/vrs-python/blob/v3/src/ga4gh/vrs/utils/hgvs_tools.py#L282-L284) and [src/ga4gh/vrs/extras/translator.py:491-493](https://github.com/ga4gh/vrs-python/blob/v3/src/ga4gh/vrs/extras/translator.py#L491-L493) — consume only the boolean return and raise `ValueError("Intronic HGVS variants are not supported")` when True. Behavior for previously-rejected inputs is unchanged.
## Test case
Add a network-free parametrized test to `tests/test_hgvs_tools.py`. No data-proxy or cassette needed — the check operates purely on the parsed hgvs object. Suggested parametrization covers every row of the matrix above.
```python
import hgvs.parser
import pytest
from ga4gh.vrs.utils.hgvs_tools import HgvsTools
@pytest.fixture(scope="module")
def hgvs_tools():
# is_intronic doesn't touch the data_proxy; pass None to avoid wiring
# up seqrepo/UTA for a pure shape test.
return HgvsTools(data_proxy=None)
class TestIsIntronic:
"""Pins the behavior of :meth:`HgvsTools.is_intronic` across every
HGVS prefix and endpoint-shape combination the hgvs parser can produce.
"""
@pytest.mark.parametrize(
("hgvs_expr", "expected"),
[
# Genomic: no intronic concept
("NC_000001.11:g.100_200del", False),
# Coding: exonic, 5' UTR, 3' UTR
("NM_000001.1:c.100A>T", False),
("NM_000001.1:c.-10A>T", False),
("NM_000001.1:c.*10A>T", False),
# Coding: intronic
("NM_000001.1:c.100+5A>T", True),
("NM_000001.1:c.100-3A>T", True),
# Coding: mixed intronic / exonic endpoints
("NM_000001.1:c.100+5_200del", True),
("NM_000001.1:c.100_200+5del", True),
# Non-coding transcript
("NR_000001.1:n.100A>T", False),
("NR_000001.1:n.100+5A>T", True),
# RNA — the gap this issue addresses
("NM_000001.1:r.100a>u", False),
("NM_000001.1:r.100+5a>u", True),
# ClinVar-derived real-world r. examples (all exonic; confirm
# the proposed per-endpoint check correctly classifies them)
("NR_001566.1:r.398_399del", False),
("NR_001566.1:r.245del", False),
("NM_001374385.1:r.2843_2931del", False),
("NM_001323289.2:r.2632c>a", False),
# Genomic uncertain range (structural form #609 uses)
("NC_000001.11:g.(100_200)_(300_400)del", False),
],
)
def test_is_intronic_matrix(self, hgvs_tools, hgvs_expr, expected):
sv = hgvs_tools.parse(hgvs_expr)
assert hgvs_tools.is_intronic(sv) is expected
```
Note: `HgvsTools.__init__` currently opens a UTA connection unconditionally. For this test to be truly network-free, the fixture may need `HgvsTools.is_intronic` to tolerate `data_proxy=None` at construction — if that's not already the case, either lazy-init the UTA connection or move `is_intronic` to a free-function helper that doesn't take `self`. Either shape is a small refactor, scope-adjacent to this issue.
## Scope and impact
- Pre-existing gap; not introduced by or related to issue #609.
- Impact for consumers: any `r.100+5a>u`-style intronic RNA input that made it through `AlleleTranslator._from_hgvs` on the current v3 code would have produced a `SequenceLocation` with coordinates that don't reflect the intronic offset (off by the offset's magnitude). After the fix, the same input raises `ValueError("Intronic HGVS variants are not supported")`, matching the `c.`/`n.` behavior.
- No `r.` test cases exist in the current test suite, consistent with `r.` being a less commonly used HGVS prefix for vrs-python's consumers. Opening this issue separately (rather than bundling into the #609 PR) keeps the scope clean and lets a maintainer decide whether `r.` support is in-scope to harden or out-of-scope to reject upstream.
## Alternative: reject `r.` outright
If `r.` is deemed out of scope for vrs-python, a simpler fix is to reject all `r.` inputs (the way `p.` protein inputs are rejected at [src/ga4gh/vrs/utils/hgvs_tools.py:397-399](https://github.com/ga4gh/vrs-python/blob/v3/src/ga4gh/vrs/utils/hgvs_tools.py#L397-L399) on the reverse path). That is a stricter but less surgical change and should be decided separately by the project maintainers.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.