/geniml

name: geniml
description: "Supports audited local Geniml genomic-interval workflows: validate BED and universe contracts, plan Region2Vec or scEmbed runs, inspect model/tokenizer compatibility, and assess consensus universes."
license: MIT
compatibility: Requires Python 3.12 and uv for the tested geniml 0.8.4 / gtars 0.10.0 stack; scEmbed needs AnnData 0.12.19 with Zarr 2.18.7 and the listed ML packages. Bundled planners and inspectors are dependency-free, local-only, and make no network requests.
allowed-tools: Read Write Edit Bash Glob
metadata:
  version: "1.4"
  skill-author: "K-Dense Inc."
  upstream-version: "0.8.4"
  last-reviewed: "2026-10-01"

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 remo