domains / science / genomic-interval-ml / geniml

geniml

Skill card

combined

The three copies cover the same high-level domain (Geniml for genomic interval ML) but diverge significantly in scope, safety, and technical detail. The K-Dense-AI copy is a rigorous, safety-focused operational guide with specific version pins (geniml 0.8.4, gtars 0.10.0), a 'safety gate' for data validation, and explicit warnings about Zarr/AnnData incompatibility. The aipoch and FreedomIntelligence copies are broader feature overviews that include BEDspace (which K-Dense omits in the visible text) and provide different installation advice (unpinned vs pinned). The FreedomIntelligence copy contains a syntax error in its install command (`uv uv pip`). Because the K-Dense copy has critical safety and compatibility constraints that the others lack, and the others have feature coverage (BEDspace) and workflow examples that K-Dense lacks or truncates, no single copy is a complete reproduction of the others. Combining them yields a skill that is both safe and comprehensive.

Repositories

Other copies

Combined skill

---
name: geniml
description: "Supports audited local Geniml genomic-interval workflows: validate BED and universe contracts, plan Region2Vec, BEDspace, 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. Bundled planners are dependency-free and local-only.
allowed-tools: Read Write Edit Bash Glob
metadata:
  version: "1.5"
  skill-author: "Combined"
  upstream-version: "0.8.4"
---

# 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.

## Safety Gate

Before importing Geniml or running an external binary:
1. Work only with explicit local regular files. Reject URLs, FIFOs, devices, and symlinks.
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, or biological replicate—not by BED row or cell alone.
5. Inventory and checksum the universe, tokenizer, model, config, inputs, and metadata.
6. Obtain explicit approval before any BEDbase or Hugging Face download.
7. Keep logs aggregate and bounded to protect sensitive genomic data.

## Coordinate and Assembly Contract

BED intervals are **0-based, half-open** `[start, end)`. Do not mix with 1-based closed coordinates (VCF/GFF). Record assembly, contig naming, and coordinate convention for every corpus. Reject negative coordinates, `end <= start`, and unknown contigs.

## Install Reproducibly

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

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

For Region2Vec/scEmbed recipes, add:

```bash
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 consensus recipes, add `pyBigWig==0.3.26` and `hmmlearn==0.3.3`. For BEDspace, ensure StarSpace binary is available. Never force incompatible installations with `--no-deps`.

## Core Workflows

### 1. Region2Vec (Region Embeddings)

Train unsupervised embeddings of genomic regions using word2vec-style learning.

```python
from geniml.tokenization import hard_tokenization
from geniml.region2vec import region2vec
from geniml.evaluation import evaluate_embeddings

# 1) Tokenize BED files against the universe
hard_tokenization(
    src_folder="bed_files/",
    dst_folder="tokens/",
    universe_file="universe.bed",
    p_value_threshold=1e-9,
)

# 2) Train Region2Vec
region2vec(
    token_folder="tokens/",
    save_dir="model/",
    num_shufflings=1000,
    embedding_dim=100,
)

# 3) Evaluate
metrics = evaluate_embeddings(
    embeddings_file="model/embeddings.npy",
    labels_file="metadata.csv",
)
```

### 2. BEDspace (Joint Region + Label Embeddings)

Learn a shared vector space for region sets and metadata labels using StarSpace.

**Workflow:**
1. Preprocess regions and metadata.
2. Train BEDspace model.
3. Compute distances and query across regions and labels.

### 3. scEmbed (Single-Cell ATAC-seq)

Train embeddings for single-cell ATAC-seq data, compatible with Scanpy.

```python
import scanpy as sc
from geniml.scembed import ScEmbed
from geniml.io import tokenize_cells

# 1) Load AnnData
adata = sc.read_h5ad("scatac_data.h5ad")

# 2) Tokenize cells
tokenize_cells(
    adata="scatac_data.h5ad",
    universe_file="universe.bed",
    output="tokens.parquet",
)

# 3) Train scEmbed
model = ScEmbed(embedding_dim=100)
model.train(dataset="tokens.parquet", epochs=100)

# 4) Encode and attach to AnnData
embeddings = model.encode(adata)
adata.obsm["scembed_X"] = embeddings

# 5) Cluster with Scanpy
sc.pp.neighbors(adata, use_rep="scembed_X")
sc.tl.leiden(adata)
sc.tl.umap(adata)
```

### 4. Consensus Peaks (Universe Building)

Build reference peak sets from multiple BED files.

```bash
# Generate coverage
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/

# Build universe (Coverage Cutoff method)
geniml universe build cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50
```

**Methods:** CC (Coverage Cutoff), CCF (Flexible), ML (Maximum Likelihood), HMM (Hidden Markov Model).

## Utilities

- **Tokenization**: Hard/soft tokenization patterns.
- **Evaluation**: Silhouette, Davies-Bouldin metrics.
- **BEDshift**: Region randomization/null-model generation.
- **BBClient**: Caching for repeated BED access.
- **Text2BedNN**: Neural search backend.