gangchen/epiage-skill

Calculatrice d'horloges épigénétiques

Calcule les horloges de vieillissement par méthylation de l'ADN à partir d'un fichier de bêtas. 25 horloges sont disponibles ; GrimAge est la plus importante.

Autonome. Nécessite uniquement pandas + numpy — pas de biolearn, torch, seaborn, scipy ni network. Les coefficients et références des horloges sont fournis dans data/ (extraits de la bibliothèque open-source biolearn, réduits aux CpGs utilisés par les horloges, ~1 Mo au total). scripts/compute_clocks.py réimplémente fidèlement les GrimageModel, LinearMethylationModel et la normalisation quantile de DunedinPACE de biolearn (avec un rankdata uniquement numpy), reproduisant les sorties de biolearn pour les 25 horloges (vérifié à <0,005, soit l'arrondi uniquement).

Les horloges (lancez --list-clocks pour la liste dynamique)

famille	horloges	unité
GrimAge (2e génération, mortalité)	grimagev1, grimagev2	années (nécessite âge+sexe)
1re génération chronologique	horvath, horvath2, hannum, lin, vidalbralo, weidner, garagnani, bocklandt	années
2e génération âge biologique	phenoage, hrsinchphenoage	années
Ying 2022 (causalité)	yingcausage, yingdamage, yingadaptage	années
stochastique	stoch, stocp, stocz	années
spécifique au tissu	pedbe (buccal pédiatrique), cortical (cerveau)	années
3e génération rythme de vieillissement	dunedinpace, dunedinpoam	années/an
autres marqueurs	dnamtl (télomères kb), zhang (mortalité), epitoc1 (mitotique)	variable

Alias de groupes pour --clocks : all, grimage, core (par défaut), firstgen, secondgen, thirdgen.

dunedinpace nécessite ~20 000 CpGs de fond pour sa normalisation quantile (pas seulement ses 173 CpGs du modèle). Sur une entrée clairsemée, il s'impute automatiquement les CpGs de fond manquants à partir de la référence standard ; si sa couverture rapportée est bien inférieure à ~90 %, le résultat est dominé par la référence et n'est pas fiable — mentionnez-le. Une exportation EPIC/450K complète le couvre parfaitement.

Faits clés sur GrimAge (pour une interprétation correcte)

GrimAge est de deuxième génération, entraînée sur la mortalité : il estime des substituts ADNm de 7 protéines plasmatiques + les années-paquets de tabagisme (V2 ajoute ADNm A1C et CRP), puis les combine avec l'âge chronologique et le sexe dans un modèle de survie. L'âge et le sexe alimentent directement la formule, donc les deux sont requis pour toute horloge grimage*. Les autres horloges ne les nécessitent pas, mais passer --age permet à l'outil de rapporter l'accélération.

Flux de travail

1. Inspecter le fichier d'entrée

Formats détectés automatiquement : Long (deux colonnes : ID CpG + bêta) ou Matrice (première colonne ID CpG, colonnes restantes = échantillons). Les bêtas sont des flottants dans [0,1]. Notez le nombre de lignes ; la couverture des CpGs de chaque horloge est rapportée par horloge.

2. Obtenir l'âge et le sexe

Requis pour GrimAge. Si seule une tranche d'âge est connue, utilisez le point médian et lancez --sensitivity pour que l'utilisateur voie à quel point la réponse dépend de l'âge exact.

3. Vérifier les dépendances (uniquement pandas + numpy)

python3 -c "import pandas, numpy" 2>/dev/null && echo OK || pip install pandas numpy

Pas besoin de venv, biolearn, torch ou réseau.

4. Lancer

python3 <skill-dir>/scripts/compute_clocks.py \
  --input "<betas.csv>" --age <ans> --sex <m|f> \
  --clocks all                 # ou : core (par défaut), grimage, firstgen, secondgen, ou clés spécifiques
  # --sensitivity 40 42 47 49  # optionnel, quand l'âge exact est incertain
python3 <skill-dir>/scripts/compute_clocks.py --list-clocks   # voir toutes les clés

Le script impute les CpGs d'horloge manquants à partir de la référence de population data/sesame_450k_median.csv (réduite) fournie, exécute chaque modèle, et affiche un tableau de la valeur, de l'accélération (pour les horloges en années), de la couverture, ainsi qu'une ligne JSON pour une utilisation en aval.

5. Rapporter et interpréter

Commencez par GrimAge, puis la comparaison. Transmettez toujours ces mises en garde :

• Réimplémentation open-source, pas la calculatrice officielle. Les valeurs suivent de près le serveur officiel d'Horvath / Clock Foundation mais ne constituent pas un nombre certifié. Pour une valeur pouvant être citée, orientez vers la calculatrice d'âge ADNm Horvath ou un fournisseur commercial.
• « Accélération » ici = horloge − âge chronologique, une simple différence. L'AgeAccel académique (résidu par rapport à une cohorte du même âge) nécessite un échantillon de population et ne peut pas être calculé pour une personne — donc +8 signifie « l'âge épigénétique prédit est 8 ans au-dessus de l'âge chronologique », pas « 8 ans de plus que les pairs ».
• Les générations diffèrent. Les horloges de 1re génération (Horvath/Hannum/Lin/…) ciblent l'âge chronologique et tendent à se situer près de l'âge réel. Les horloges de 2e génération (GrimAge/PhenoAge) ciblent les résultats de santé et prédisent mieux la mortalité/le vieillissement — elles peuvent diverger de l'âge réel par conception. Ne lisez pas GrimAge comme « paraît N ans » ; c'est un score de risque en années.
• Les horloges non annuelles (dunedinpoam rythme, dnamtl télomères kb, zhang/stocz risque de mortalité, epitoc1 mitotique) ne sont pas des âges — aucune accélération n'est affichée.
• Couverture / imputation : quelques CpGs d'horloge manquants remplis par une médiane de population sont normaux ; signalez les horloges dont la couverture descend en dessous de ~90 %. La colonne n_lowconf de la sortie compte les CpGs imputés dont l'écart-type de référence sanguine > 0,08 (remplissages à ne pas fiabiliser) — un signal plus précis par CpG que la seule couverture. Une horloge avec beaucoup de remplissages n_lowconf n'est pas fiable sur cet échantillon même si elle a « fonctionné ».
• Conception exclusivement sanguine. Cette compétence suppose du SANG TOTAL HUMAIN. Les horloges sont appliquées sur du sang ; la référence d'imputation est le sang. Ne l'utilisez pas sur d'autres tissus.
• Imputation des CpGs manquants — methyLImp par défaut. Les CpGs d'horloge manquants (par exemple CpGs entraînés sur EPIC absents d'une exportation MSA/WeGene) sont imputés avec methyLImp : régression à rang réduit (PCA) qui prédit chaque CpG manquant à partir des CpGs observés de l'échantillon en utilisant la structure de corrélation inter-CpG d'un panel sanguin complet — plus précis qu'une médiane plate (~30 % de RMSE en moins lorsque le tissu correspond). Les CpGs absents du panel retombent sur la médiane sanguine ; n_lowconf (écart-type sanguin > 0,08) signale les remplissages peu fiables. Le mode actif est affiché au démarrage de l'exécution.
  • Le panel se trouve dans data/blood_panel.npz et est fourni (~5 Mo ; préconstruit à partir de GSE40279 = 656 échantillons sanguins 450K, réduits aux CpGs des horloges + 50 PCs sanguins + médiane/écart-type par CpG). Ainsi, methyLImp est actif dès la sortie de la boîte — il réduit l'RMSE d'imputation de ~10 % par rapport à une médiane plate sur un benchmark de CpGs retenus. Pour reconstruire/personnaliser, exécutez scripts/build_blood_panel.py. Si le fichier vient à manquer, l'outil passe en douceur à la médiane globale et le signale.
  • Vérification : methyLImp améliore principalement les horloges fortement imputées. Les horloges à haute couverture (GrimAge/Horvath/PhenoAge) imputent peu de CpGs, donc leurs valeurs bougent de <0,2 an — l'indicateur de confiance est le gain pratique le plus important.
• Pas un avis médical — utilisation pour la recherche/éducation uniquement.

Remarques

• Entrée matricielle → une ligne de résultat par échantillon par horloge.
• Exclus délibérément (ne peuvent pas être reproduits fidèlement sans outils plus lourds, ou ne sont pas des horloges de vieillissement) :
  • Les PC-horloges (PCHorvath…), AltumAge, GPAge — nécessitent rotation PCA / réseaux de neurones.
  • Les horloges gestationnelles (Knight, Lee, Mayne, Bohlin) — pour sang de cordon / nouveau-nés.
  • Les prédicteurs de traits et maladies (IMC, cholestérol, tabagisme, alcool, Alzheimer, MCV, …) — ce sont des modèles de biomarqueurs, pas des horloges de vieillissement. Si un utilisateur a spécifiquement besoin de l'un de ceux-ci, dites-lui que cela nécessite l'installation complète de biolearn.
• Provenance. Les coefficients sont ceux de biolearn (MIT), qui réimplémente les horloges publiées. GrimAge a des restrictions d'utilisation commerciale (UCLA TDG / Clock Foundation) pour les cosmétiques et l'assurance-vie.