ContextQMD
Back to Claude Scientific Skills

Region2Vec

skills/geniml/references/region2vec.md

2.55.09.9 KB
Original Source

Region2Vec

Verified against geniml==0.8.4 release source and the official BEDbase documentation on 2026-07-23.

What the method does

Region2Vec learns vectors for genomic regions from region co-occurrence within interval sets. The primary paper describes randomizing regions within each set to create word2vec-like contexts, then pooling region vectors to represent sets. Treat learned proximity as a property of the training corpus and universe, not as proof of a biological mechanism.

Primary method source: Gharavi et al. (2021), Embeddings of genomic region sets capture rich biological associations in low dimensions, doi:10.1093/bioinformatics/btab439.

Stable 0.8.4 API reality

Use concrete module paths:

python
from geniml.region2vec.main import Region2VecExModel
from geniml.region2vec.utils import Region2VecDataset
from gtars.tokenizers import Tokenizer

The release's geniml.region2vec.__init__ does not export Region2VecExModel or the legacy region2vec function. Consequently, from geniml.region2vec import region2vec and the installed geniml region2vec ... dispatch path are not reliable in 0.8.4. The old function still exists at geniml.region2vec.main_legacy.region2vec, but use it only to reproduce an existing workflow after a pinned smoke test.

Universe and tokenizer contract

Create the tokenizer from a validated local BED universe:

python
from gtars.tokenizers import Tokenizer

tokenizer = Tokenizer.from_bed("refs/universe.bed")

With verified gtars==0.9.2:

  • universe regions receive stable IDs in file order;
  • seven special tokens are added (unk, pad, mask, cls, eos, bos, and sep);
  • len(tokenizer) is universe row count plus special tokens;
  • tokenizer(region_set)["input_ids"] returns integer IDs.

Compatibility requires the exact universe bytes/order, assembly, contig policy, Gtars version, special-token map/IDs, and tokenization behavior. Re-sorting a universe changes IDs even when the interval set is mathematically identical. Never infer compatibility from a shared filename such as hg38.bed.

Before tokenizing:

  1. Validate BED as 0-based half-open intervals.
  2. Confirm a single assembly with a checksummed chromosome-sizes file.
  3. Resolve chr1/1, alt-contig, mitochondrial, and strand policies.
  4. Split by patient/donor before learning or evaluating representations.
  5. Record the universe SHA-256 and row count.

Run:

bash
python skills/geniml/scripts/bed_validator.py \
  --input refs/universe.bed \
  --assembly GRCh38 \
  --chrom-sizes refs/GRCh38.chrom.sizes

Prepare the token corpus

Region2VecDataset reads a Parquet file with one list-valued column named tokens; each row is one BED document, sample, or cell. IDs must come from the same tokenizer that initializes the model.

python
import pyarrow as pa
import pyarrow.parquet as pq
from gtars.models import RegionSet

documents = []
for local_bed in validated_local_beds:
    ids = tokenizer(RegionSet(local_bed))["input_ids"]
    documents.append(ids)

table = pa.table({"tokens": pa.array(documents, type=pa.list_(pa.int32()))})
pq.write_table(table, "work/tokens.parquet")

This example assumes validated_local_beds came from a bounded, local manifest. Do not discover arbitrary directory contents, follow symlinks, or log sample filenames. Ensure every token is an integer in [0, len(tokenizer)). Empty or unusually short documents need an explicit policy; do not silently discard them after splitting.

Region2VecDataset(path, shuffle=True, convert_to_str=False) loads the full Parquet tokens column into memory. Bound rows and total tokens before construction. shuffle=True mutates each document order when accessed; record the training seed, but do not assume every library/thread schedule is bitwise deterministic.

Train the modern model

python
from geniml.region2vec.main import Region2VecExModel
from geniml.region2vec.utils import Region2VecDataset

dataset = Region2VecDataset("work/tokens.parquet", shuffle=True)
model = Region2VecExModel(
    tokenizer=tokenizer,
    embedding_dim=100,
    pooling_method="mean",
    device="cpu",
)
model.train(
    dataset,
    window_size=5,
    epochs=10,
    min_count=10,
    num_cpus=4,
    seed=42,
)

Current source defaults are not fully consistent across legacy and modern modules. Pass every material setting explicitly. train uses Gensim Word2Vec, then copies learned weights into a Torch embedding matrix. load_from_checkpoint and per-epoch Gensim .model files deserialize Gensim artifacts; load only artifacts you created or independently trust.

Suggested run record:

  • Geniml, Gtars, Python, Torch, Gensim, NumPy, and PyArrow versions;
  • lockfile digest and platform;
  • universe/checkpoint/config/token-corpus/manifest SHA-256;
  • assembly, coordinate and contig contracts;
  • vocabulary and special-token sizes;
  • embedding dimension, window, epochs, min_count, workers, seed, shuffling, pooling, and device;
  • train/validation/test grouping and excluded documents.

Generate a bounded plan first:

bash
python skills/geniml/scripts/embedding_plan.py \
  --mode region2vec \
  --data work/tokens.parquet \
  --universe refs/universe.bed \
  --output-dir work/region2vec \
  --assembly GRCh38 \
  --embedding-dim 100 --epochs 10 --workers 4 --seed 42

Export and inspect artifacts

The 0.8.4 constants are:

  • checkpoint.pt
  • config.yaml
  • universe.bed

The config uses vocab_size and embedding_dim; embedding_size is accepted only for backward compatibility and is marked for future deprecation.

Important release-source caveat: model.export(path) calls export_region2vec_model, which writes the Torch checkpoint and YAML config but does not write the tokenizer's universe, despite the API docstring. Copy the exact validated universe into the bundle yourself, without changing row order, then create a checksum manifest.

python
from pathlib import Path
import shutil

bundle = Path("models/region2vec")
model.export(str(bundle))
shutil.copyfile("refs/universe.bed", bundle / "universe.bed")

Do not overwrite an existing bundle without preserving its prior manifest. Inspect without deserialization:

bash
python skills/geniml/scripts/model_artifact_inspector.py \
  --model-dir models/region2vec

python skills/geniml/scripts/tokenizer_compatibility.py \
  --model-dir models/region2vec \
  --universe refs/universe.bed \
  --assembly GRCh38

The checkpoint is a .pt file. Geniml's local loader uses torch.load(..., weights_only=True), which reduces but does not eliminate untrusted-artifact risks such as resource exhaustion, parser defects, or native-library vulnerabilities. Never use torch.load, Gensim load, pickle, or joblib merely to inspect metadata.

Load only after verification

Local bundle:

python
from geniml.region2vec.main import Region2VecExModel

model = Region2VecExModel.from_pretrained("models/region2vec")

Despite its name, this classmethod joins local filenames and makes no Hub request. In contrast:

python
model = Region2VecExModel(model_path="organization/model")

calls huggingface_hub.hf_hub_download for the checkpoint, universe, and config. Do not use that form without explicit network approval, a pinned Hub revision, an approved cache directory, and expected hashes.

The loader constructs the tokenizer from universe.bed, reads config.yaml with YAML safe_load, creates a model of vocab_size × embedding_dim, and loads checkpoint weights. A checksum match is necessary but not sufficient: also compare assembly, special tokens, shape, pooling, and software versions.

Encode intervals and sets

Region2VecExModel.encode accepts a local BED path, a Region, a sequence of regions, geniml.io.RegionSet, or gtars.models.RegionSet.

python
vectors = model.encode(
    "data/query.bed",
    pooling="mean",
    batch_size=64,
)

The method tokenizes each input region, projects its token IDs, and applies mean or max pooling. It returns one vector per input region. It does not validate assembly or repair malformed intervals. Validate first, and report aggregate shapes/statistics rather than raw genomic coordinates.

Evaluate without leakage

Geniml's eval module implements the paper's:

  • CTT: cluster tendency;
  • RCT: preservation of training-occurrence information;
  • GDST: relation between genomic and embedding distance;
  • NPT: preservation of genomic neighborhoods.

Source-backed CLI:

text
geniml eval ctt --model-path MODEL --embed-type region2vec
geniml eval gdst --model-path MODEL --embed-type region2vec
geniml eval npt --model-path MODEL --embed-type region2vec --K 10
geniml eval rct --model-path MODEL --embed-type region2vec \
  --bin-path BINARY_EMBEDDINGS

rct also requires binary embeddings from the same tokenized corpus. The official tutorial and eval bin-gen write pickle; treat that format as trusted local output only and never load a third-party pickle. Hold out independent patients/donors before universe selection, hyperparameter tuning, training, and metric selection. Report all metrics and baselines rather than selecting a single favorable score.

Primary evaluation source: Zheng et al. (2024), Methods for evaluating unsupervised vector representations of genomic regions, doi:10.1093/nargab/lqae086.

Official sources