geniml

Par mkurman · zorai

Cette skill doit être utilisée pour travailler avec des données d'intervalles génomiques (fichiers BED) dans le cadre de tâches de machine learning. À utiliser pour l'entraînement d'embeddings de régions (Region2Vec, BEDspace), l'analyse scATAC-seq en cellule unique (scEmbed), la construction de pics consensus (universes), ou toute analyse ML de régions génomiques. S'applique aux collections de fichiers BED, aux données scATAC-seq, aux jeux de données d'accessibilité de la chromatine et à l'apprentissage de features génomiques basé sur les régions.

npx skills add https://github.com/mkurman/zorai --skill geniml

Geniml: Machine Learning sur Intervalles Génomiques

Aperçu

Geniml est un package Python pour construire des modèles de machine learning sur des données d'intervalles génomiques à partir de fichiers BED. Il fournit des méthodes non supervisées pour apprendre des embeddings de régions génomiques, de cellules isolées et d'étiquettes de métadonnées, permettant des recherches de similarité, du clustering et des tâches ML en aval.

Installation

Installez geniml avec uv :

uv uv pip install geniml

Pour les dépendances ML (PyTorch, etc.) :

uv uv pip install 'geniml[ml]'

Version de développement depuis GitHub :

uv uv pip install git+https://github.com/databio/geniml.git

Capacités Principales

Geniml fournit cinq capacités primaires, chacune détaillée dans des fichiers de référence dédiés :

1. Region2Vec: Embeddings de Régions Génomiques

Entraîner des embeddings non supervisés de régions génomiques en utilisant l'apprentissage de type word2vec.

À utiliser pour : Réduction de dimensionnalité de fichiers BED, analyse de similarité de régions, vecteurs de features pour le ML en aval.

Workflow :

  1. Tokeniser les fichiers BED en utilisant une référence univers
  2. Entraîner le modèle Region2Vec sur les tokens
  3. Générer les embeddings pour les régions

Référence : Consultez references/region2vec.md pour le workflow détaillé, les paramètres et les exemples.

2. BEDspace: Embeddings Conjoints de Régions et Métadonnées

Entraîner des embeddings partagés pour les ensembles de régions et les étiquettes de métadonnées en utilisant StarSpace.

À utiliser pour : Recherches sensibles aux métadonnées, requêtes multi-modales (région→étiquette ou étiquette→région), analyse conjointe du contenu génomique et des conditions expérimentales.

Workflow :

  1. Prétraiter les régions et métadonnées
  2. Entraîner le modèle BEDspace
  3. Calculer les distances
  4. Interroger les régions et étiquettes

Référence : Consultez references/bedspace.md pour le workflow détaillé, les types de recherche et les exemples.

3. scEmbed: Embeddings d'Accessibilité Chromatinienne Mono-cellulaires

Entraîner des modèles Region2Vec sur des données scATAC-seq pour les embeddings au niveau cellulaire.

À utiliser pour : Clustering scATAC-seq, annotation de types cellulaires, réduction de dimensionnalité de cellules isolées, intégration avec des workflows scanpy.

Workflow :

  1. Préparer AnnData avec les coordonnées de pics
  2. Pré-tokeniser les cellules
  3. Entraîner le modèle scEmbed
  4. Générer les embeddings cellulaires
  5. Clusteriser et visualiser avec scanpy

Référence : Consultez references/scembed.md pour le workflow détaillé, les paramètres et les exemples.

4. Consensus Peaks: Construction d'Univers

Construire des ensembles de pics de référence (univers) à partir de collections de fichiers BED en utilisant plusieurs méthodes statistiques.

À utiliser pour : Créer des références de tokenisation, standardiser les régions entre des datasets, définir les features consensuelles avec une rigueur statistique.

Workflow :

  1. Combiner les fichiers BED
  2. Générer les pistes de couverture
  3. Construire l'univers en utilisant la méthode CC, CCF, ML ou HMM

Méthodes :

  • CC (Coverage Cutoff) : Simple basée sur un seuil
  • CCF (Coverage Cutoff Flexible) : Intervalles de confiance pour les limites
  • ML (Maximum Likelihood) : Modélisation probabiliste des positions
  • HMM (Hidden Markov Model) : Modélisation d'états complexes

Référence : Consultez references/consensus_peaks.md pour la comparaison des méthodes, les paramètres et les exemples.

5. Utilities: Outils de Support

Outils supplémentaires pour la mise en cache, la randomisation, l'évaluation et la recherche.

Utilities disponibles :

  • BBClient : Mise en cache de fichiers BED pour un accès répété
  • BEDshift : Randomisation préservant le contexte génomique
  • Evaluation : Métriques pour la qualité des embeddings (silhouette, Davies-Bouldin, etc.)
  • Tokenization : Utilitaires de tokenisation de régions (durs, souples, basés sur univers)
  • Text2BedNN : Backends de recherche neurale pour les requêtes génomiques

Référence : Consultez references/utilities.md pour l'utilisation détaillée de chaque utility.

Workflows Courants

Pipeline d'Embedding de Régions de Base

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

# Étape 1 : Tokeniser les fichiers BED
hard_tokenization(
    src_folder='bed_files/',
    dst_folder='tokens/',
    universe_file='universe.bed',
    p_value_threshold=1e-9
)

# Étape 2 : Entraîner Region2Vec
region2vec(
    token_folder='tokens/',
    save_dir='model/',
    num_shufflings=1000,
    embedding_dim=100
)

# Étape 3 : Évaluer
metrics = evaluate_embeddings(
    embeddings_file='model/embeddings.npy',
    labels_file='metadata.csv'
)

Pipeline d'Analyse scATAC-seq

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

# Étape 1 : Charger les données
adata = sc.read_h5ad('scatac_data.h5ad')

# Étape 2 : Tokeniser les cellules
tokenize_cells(
    adata='scatac_data.h5ad',
    universe_file='universe.bed',
    output='tokens.parquet'
)

# Étape 3 : Entraîner scEmbed
model = ScEmbed(embedding_dim=100)
model.train(dataset='tokens.parquet', epochs=100)

# Étape 4 : Générer les embeddings
embeddings = model.encode(adata)
adata.obsm['scembed_X'] = embeddings

# Étape 5 : Clusteriser avec scanpy
sc.pp.neighbors(adata, use_rep='scembed_X')
sc.tl.leiden(adata)
sc.tl.umap(adata)

Construction et Évaluation d'Univers

# Générer la couverture
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/

# Construire l'univers avec seuil de couverture
geniml universe build cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50

# Évaluer la qualité de l'univers
geniml universe evaluate \
  --universe universe.bed \
  --coverage-folder coverage/ \
  --bed-folder bed_files/

Référence CLI

Geniml fournit des interfaces en ligne de commande pour les opérations majeures :

# Entraînement Region2Vec
geniml region2vec --token-folder tokens/ --save-dir model/ --num-shuffle 1000

# Prétraitement BEDspace
geniml bedspace preprocess --input regions/ --metadata labels.csv --universe universe.bed

# Entraînement BEDspace
geniml bedspace train --input preprocessed.txt --output model/ --dim 100

# Recherche BEDspace
geniml bedspace search -t r2l -d distances.pkl -q query.bed -n 10

# Construction univers
geniml universe build cc --coverage-folder coverage/ --output universe.bed --cutoff 5

# Randomisation BEDshift
geniml bedshift --input peaks.bed --genome hg38 --preserve-chrom --iterations 100

Quand utiliser Quel Outil

Utiliser Region2Vec quand :

  • Travailler avec des données génomiques en masse (ChIP-seq, ATAC-seq, etc.)
  • Besoin d'embeddings non supervisés sans métadonnées
  • Comparer des ensembles de régions entre expériences
  • Construire des features pour un apprentissage supervisé en aval

Utiliser BEDspace quand :

  • Des étiquettes de métadonnées disponibles (types cellulaires, tissus, conditions)
  • Besoin d'interroger les régions par métadonnées ou vice-versa
  • Vouloir un espace d'embedding conjoint pour régions et étiquettes
  • Construire des bases de données génomiques interrogeables

Utiliser scEmbed quand :

  • Analyser des données scATAC-seq
  • Clusteriser les cellules par accessibilité chromatinienne
  • Annoter les types cellulaires à partir de scATAC-seq
  • L'intégration avec scanpy est souhaitée

Utiliser la Construction d'Univers quand :

  • Besoin d'ensembles de pics de référence pour la tokenisation
  • Combiner plusieurs expériences en consensus
  • Vouloir des définitions de régions statistiquement rigoureuses
  • Construire des références standards pour un projet

Utiliser les Utilities quand :

  • Besoin de mettre en cache les fichiers BED distants (BBClient)
  • Générer des modèles nuls pour les statistiques (BEDshift)
  • Évaluer la qualité des embeddings (Evaluation)
  • Construire des interfaces de recherche (Text2BedNN)

Bonnes Pratiques

Directives Générales

  • La qualité de l'univers est critique : Investir du temps dans la construction d'univers complets et bien construits
  • Validation de tokenisation : Vérifier la couverture (>80% idéal) avant l'entraînement
  • Ajustement des paramètres : Expérimenter avec les dimensions d'embedding, les taux d'apprentissage et les epochs d'entraînement
  • Évaluation : Toujours valider les embeddings avec plusieurs métriques et visualisations
  • Documentation : Enregistrer les paramètres et les seeds aléatoires pour la reproductibilité

Considérations de Performance

  • Pré-tokenisation : Pour scEmbed, toujours pré-tokeniser les cellules pour un entraînement plus rapide
  • Gestion mémoire : Les grands datasets peuvent nécessiter un traitement par batch ou un sous-échantillonnage
  • Ressources informatiques : Les méthodes d'univers ML/HMM sont informatiquement intensives
  • Mise en cache de modèle : Utiliser BBClient pour éviter les téléchargements répétés

Patterns d'Intégration

  • Avec scanpy : Les embeddings scEmbed s'intègrent facilement comme des entrées adata.obsm
  • Avec BEDbase : Utiliser BBClient pour accéder aux référentiels BED distants
  • Avec Hugging Face : Exporter les modèles entraînés pour le partage et la reproductibilité
  • Avec R : Utiliser reticulate pour l'intégration R (voir références utilities)

Projets Associés

Geniml fait partie de l'écosystème BEDbase :

  • BEDbase : Plateforme unifiée pour les régions génomiques
  • BEDboss : Pipeline de traitement pour fichiers BED
  • Gtars : Outils et utilitaires génomiques
  • BBClient : Client pour référentiels BEDbase

Ressources Supplémentaires

Dépannage

« Couverture de tokenisation trop faible » :

  • Vérifier la qualité et la complétude de l'univers
  • Ajuster le seuil de p-value (essayer 1e-6 au lieu de 1e-9)
  • S'assurer que l'univers correspond à l'assemblage génomique

« L'entraînement ne converge pas » :

  • Ajuster le taux d'apprentissage (essayer la plage 0,01-0,05)
  • Augmenter le nombre d'epochs d'entraînement
  • Vérifier la qualité des données et le prétraitement

« Erreurs de mémoire insuffisante » :

  • Réduire la taille du batch pour scEmbed
  • Traiter les données par chunks
  • Utiliser la pré-tokenisation pour données mono-cellulaires

« StarSpace non trouvé » (BEDspace) :

Pour un dépannage détaillé et les problèmes spécifiques à chaque méthode, consultez le fichier de référence approprié.

Skills similaires

eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

126
imaging-data-commons
mkurman / zorai

Interroger et télécharger des données d'imagerie médicale publiques depuis NCI IDC.

309
claude-api
anthropics / skills

Construire des applications LLM avec Claude via le SDK officiel adapté au langage.

146 952
gtars
mkurman / zorai

Analyser, tokeniser et manipuler des données génomiques avec des outils Rust haute performance.

309
ad-model-onboard
nvidia / skills

Automatiser l'intégration de modèles HuggingFace dans AutoDeploy avec tests et rapport.

1 033