geniml – Data & Science skill for AI agents

Geniml

Use Geniml for machine learning and statistical workflows over genomic interval

sets. Treat coordinates, assemblies, token vocabularies, model artifacts, and

sample grouping as explicit contracts. The bundled scripts validate or plan;

they do not import Geniml, contact services, deserialize models, or execute

training.

Bash is declared only for explicit, user-approved uv, Python, Geniml,

Gtars, Git, and native CLI commands shown in this guide; bundled Python helpers

do not spawn subprocesses. Example paths under data/, refs/, work/, and

models/ are user-provided project placeholders, not missing bundled files.

Verified release snapshot

• Latest stable PyPI release on 2026-10-01: geniml==0.8.4 (2026-01-14).
• PyPI does not declare Requires-Python; its classifiers list Python

3.10-3.14. The current recipes below were tested on Python 3.12.

• geniml==0.8.4 accepts gtars>=0.2.5; the verified base smoke used current

gtars==0.10.0 (2026-09-05, Python >=3.10).

• Extras are ml and test. The base install omits Torch, Gensim, Scanpy,

Hugging Face Hub, pyBigWig, and HMM dependencies.

• Upstream documentation contains stale examples. Release source and installed

--help output take precedence where they conflict.

Install reproducibly

Use a separate project environment. The tested CPU stack uses Python 3.12:

uv venv --python 3.12
uv pip install "geniml==0.8.4" "gtars==0.10.0"

For the Region2Vec/scEmbed recipes tested here, add only their required libraries:

uv pip install "torch==2.14.1" "gensim==4.4.0" "huggingface-hub==2.0.0" \
  "scanpy==1.12.4" "anndata==0.12.19" "zarr==2.18.7"

For the consensus recipes, also install pyBigWig==0.3.26 and

hmmlearn==0.3.3. For a durable project, use the same requirements with

uv add and retain uv.lock.

Geniml requires Zarr <3. AnnData 0.13 requires Zarr >=3, so current AnnData

cannot share this environment. Keep AnnData 0.12.19 here; transfer H5AD files

between separate environments when newer AnnData features are needed. Never

force an incompatible installation with --no-deps.

The full geniml[ml]==0.8.4 extra includes additional, older pinned components.

Its resolution was checked with anndata==0.12.19 and gtars==0.10.0, but

that full stack was not executed; it selected Scanpy 1.11.5 and Transformers

4.57.6. It is unnecessary for the workflows above.

Do not install an unpinned Git branch. Record Python, OS/architecture, the

resolved lockfile, and the PyPI artifact digest. Geniml itself is BSD-2-Clause;

the MIT frontmatter value licenses this skill's content.

Start with the safety gate

Before importing Geniml or running an external binary:

1. Work only with explicit local regular files. Reject URLs, FIFOs, devices,

and symlinks unless the user deliberately changes that policy.

2. Validate BED structure and the declared assembly against a trusted local

chromosome-sizes file.

3. Bound file count, bytes, rows, workers, epochs, and output size.

4. Separate train/validation/test by patient, donor, biological replicate, or

other independent unit—not by BED row or cell alone.

5. Inventory and checksum the universe, tokenizer, model, config, inputs,

metadata manifest, and native binaries.

6. Obtain explicit approval before any BEDbase or Hugging Face download. Never

infer approval from a model ID or BEDbase identifier.

7. Keep logs aggregate and bounded. BED filenames, sample IDs, phenotypes,

labels, barcodes, and genomic intervals may be sensitive.

Coordinate and assembly contract

BED intervals are normally 0-based, half-open [start, end): start is

included, end is excluded, and length is end - start. Do not mix them with

1-based closed coordinates from VCF/GFF or user-facing genome browsers.

For every corpus and artifact, record:

• assembly and patch/accession where possible (for example GRCh38 versus

GRCh38.p14), plus the chromosome-sizes checksum;

• contig naming convention (chr1 versus 1), alt/random/decoy policy, and

mitochondrial naming;

• coordinate convention, sorting order, duplicate/overlap policy, and whether

BED strand is meaningful;

• liftover tool, chain digest, source/target assemblies, unmapped fraction, and

post-liftover validation.

Reject negative coordinates, end <= start, integer overflow, unknown

contigs, ends beyond contig length, malformed columns, mixed assemblies, and

silent contig renaming. Sorting and normalization never repair an assembly

mismatch. BED3 has no strand; when column 6 is present, preserve +, -, or

. unless the assay contract says otherwise.

Run a bounded validation and normalization plan before analysis:

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

The validator reports proposed actions but never rewrites the BED file.

Current API map

Region and tokenizer I/O

Prefer Gtars for new interval/tokenizer code:

from gtars.models import Region, RegionSet
from gtars.tokenizers import Tokenizer

regions = RegionSet("data/peaks.bed")
tokenizer = Tokenizer.from_bed("refs/universe.bed")
encoded = tokenizer(regions)
input_ids = encoded["input_ids"]

RegionSet and Tokenizer also accept remote inputs in some constructors;

this skill permits local paths only unless network access is explicitly

approved. geniml.io.RegionSet(regions, backed=False) remains available as a

legacy Python implementation; backed sets are iterable but not indexable.

geniml.io.Region uses stop, while gtars.models.Region uses end.

With gtars 0.10.0, seven special tokens are added to a BED vocabulary. Therefore

len(tokenizer) is not simply the number of universe rows. Preserve universe

row order and the exact special-token map.

Region2Vec

The modern class lives at a concrete module path:

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

tokenizer = Tokenizer.from_bed("refs/universe.bed")
dataset = Region2VecDataset("work/tokens.parquet", shuffle=True, convert_to_str=True)
model = Region2VecExModel(tokenizer=tokenizer, embedding_dim=100)
model.train(dataset, epochs=10, window_size=5, num_cpus=4, seed=42)

The Parquet input must contain one list-valued tokens column, one document

per row. Record token frequencies and min_count: in the

[0.8.4 training implementation](https://github.com/databio/geniml/blob/v0.8.4/geniml/region2vec/main.py),

only Gensim-retained token IDs receive trained weights. Universe membership

alone therefore does not prove a token has a learned embedding. Report the

fraction of inference tokens excluded by training-frequency filtering and

exclude or explicitly flag their embeddings in downstream comparisons. See [references/region2vec.md](references/region2vec.md) for export,

encoding, legacy CLI, and evaluation details.

scEmbed

Import ScEmbed from geniml.scembed.main. AnnData .var must contain

chr, start, and end; rows are cells and nonzero features identify

accessible regions. The released tokenize_anndata and ScEmbed.encode

fail with Gtars 0.10.0. Use the tested explicit Region construction and token

projection in the scEmbed reference; preserve cell order and reject empty,

unmatched, or untrained token sets. See

[references/scembed.md](references/scembed.md).

BEDspace

BEDspace remains in 0.8.4 and invokes an external StarSpace executable.

StarSpace is archived and upstream Geniml does not pin a compatible revision.

Treat BEDspace as a legacy reproduction path, not the default for new systems.

Its preprocessing also returns blank documents with Gtars 0.10.0 after

catching a tokenizer API error. See [references/bedspace.md](references/bedspace.md)

for the source contract and reproduction limitations.

Consensus universes and assessment

The installed 0.8.4 CLI uses:

geniml build-universe {cc,ccf,ml,hmm} ...
geniml assess-universe ...
geniml eval {gdst,npt,ctt,rct,bin-gen} ...

CC/CCF/ML/HMM consume precomputed coverage bigWigs. Do not concatenate or

generate coverage until all BED files pass the same assembly contract.

Assessment and embedding metrics are distinct: assess-universe measures fit

of a universe to interval collections, while eval implements CTT, RCT, GDST,

and NPT for embeddings. See

[references/consensus_peaks.md](references/consensus_peaks.md) and

[references/utilities.md](references/utilities.md).

Important 0.8.4 migration notes

• The 0.7.0 changelog moved new RegionSet/tokenizer work toward Gtars.
• The 0.4.0 names TreeTokenizer and AnnDataTokenizer are historical; the

current Gtars API exposes Tokenizer.

• In the 0.8.4 wheel, geniml.region2vec and geniml.scembed do not re-export

their modern classes/functions. Use the concrete module paths above.

• geniml tokenize and `geniml re

… (full content is in the download package)