gangchen/epiage-skill

Calculadora de Relojes Epigenéticos

Calcula relojes de envejecimiento basados en metilación del ADN a partir de un archivo de valores beta. 25 relojes están disponibles; GrimAge es el principal.

Autónomo. Solo necesita pandas + numpy — no requiere biolearn, torch, seaborn, scipy ni network. Los coeficientes y referencias de los relojes están incluidos en data/ (extraídos de la biblioteca de código abierto biolearn, recortados a los CpG que usan los relojes, ~1 MB en total). scripts/compute_clocks.py reimplementa fielmente GrimageModel, LinearMethylationModel y la normalización por cuantiles de DunedinPACE de biolearn (con un rankdata solo con numpy), reproduciendo los resultados de biolearn para los 25 relojes (verificado con diferencia <0.005, es decir, solo errores de redondeo).

Los relojes (ejecute --list-clocks para la lista actual)

familia	relojes	unidad
GrimAge (2.ª gen., mortalidad)	grimagev1, grimagev2	años (necesita edad+sexo)
1.ª gen. cronológicos	horvath, horvath2, hannum, lin, vidalbralo, weidner, garagnani, bocklandt	años
2.ª gen. edad biológica	phenoage, hrsinchphenoage	años
Ying 2022 (causalidad)	yingcausage, yingdamage, yingadaptage	años
estocásticos	stoch, stocp, stocz	años
específicos de tejido	pedbe (bucal pediátrico), cortical (cerebro)	años
3.ª gen. ritmo de envejecimiento	dunedinpace, dunedinpoam	años/año
otros marcadores	dnamtl (telómero kb), zhang (mortalidad), epitoc1 (mitótico)	varía

Alias de grupo para --clocks: all, grimage, core (predeterminado), firstgen, secondgen, thirdgen.

dunedinpace necesita ~20k CpG de fondo para su normalización por cuantiles (no solo sus 173 CpG del modelo). Con una entrada dispersa, auto-imputa el fondo faltante a partir de la referencia estándar; si la cobertura reportada es muy inferior a ~90%, el resultado está dominado por la referencia y no es fiable. Una exportación completa de EPIC/450K lo cubre bien.

Datos clave sobre GrimAge (para interpretarlo correctamente)

GrimAge es de segunda generación, entrenado para mortalidad: estima sustitutos de metilación del ADN (DNAm) de 7 proteínas plasmáticas + años de tabaquismo (V2 añade DNAm A1C y CRP), luego los combina con la edad cronológica y el sexo en un modelo de supervivencia. La edad y el sexo alimentan directamente la fórmula, por lo que ambos son necesarios para cualquier reloj grimage*. Los demás relojes no los necesitan, pero pasar --age permite que la herramienta informe la aceleración.

Flujo de trabajo

1. Inspeccionar el archivo de entrada

Formatos detectados automáticamente: Largo (dos columnas: ID de CpG + beta) o Matriz (primera columna ID de CpG, columnas restantes = muestras). Los betas son flotantes en [0,1]. Anote el número de filas; la cobertura de los CpG de cada reloj se informa por reloj.

2. Obtener edad y sexo

Necesarios para GrimAge. Si solo se conoce un rango de edad, use el punto medio y ejecute --sensitivity para que el usuario vea cuánto depende la respuesta de la edad exacta.

3. Verificar dependencias (solo pandas + numpy)

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

No se necesita venv, biolearn, torch ni red.

4. Ejecutar

python3 <skill-dir>/scripts/compute_clocks.py \
  --input "<betas.csv>" --age <años> --sex <m|f> \
  --clocks all                 # o: core (predet.), grimage, firstgen, secondgen, o claves específicas
  # --sensitivity 40 42 47 49  # opcional, cuando la edad exacta es incierta
python3 <skill-dir>/scripts/compute_clocks.py --list-clocks   # ver todas las claves

El script imputa cualquier CpG faltante de los relojes a partir de la referencia poblacional incluida (recortada) data/sesame_450k_median.csv, ejecuta cada modelo y muestra una tabla con el valor, la aceleración (para relojes en años) y la cobertura, además de una línea JSON para uso posterior.

5. Informar e interpretar

Lidere con GrimAge, luego la comparación. Siempre transmita estas advertencias:

• Reimplementación de código abierto, no la calculadora oficial. Los valores se aproximan a los del servidor oficial de Horvath / Clock Foundation, pero no son un número certificado. Para un valor citable, diríjase a la calculadora de Horvath DNAm Age o a un proveedor comercial.
• "Aceleración" aquí = reloj − edad cronológica, una diferencia simple. La AgeAccel académica (residual vs. una cohorte de la misma edad) necesita una muestra poblacional y no se puede calcular para una sola persona — así que +8 significa "la edad epigenética predicha es 8 años mayor que la edad cronológica", no "8 años mayor que sus pares".
• Las generaciones difieren. Los de 1.ª gen. (Horvath/Hannum/Lin/…) apuntan a la edad cronológica y tienden a acercarse a la edad real. Los de 2.ª gen. (GrimAge/PhenoAge) apuntan a resultados de salud y predicen mejor la mortalidad/envejecimiento — pueden divergir de la edad real por diseño. No interprete GrimAge como "parece de N años"; es una puntuación de riesgo en años.
• Los relojes sin unidad de años (dunedinpoam ritmo, dnamtl kb de telómeros, zhang/stocz riesgo de mortalidad, epitoc1 mitótico) no son edades — no se muestra aceleración.
• Cobertura / imputación: unos pocos CpG faltantes de los relojes rellenados con una mediana poblacional es normal; marque los relojes cuya cobertura caiga por debajo de ~90%. La columna n_lowconf de la salida cuenta los CpG imputados cuya desviación estándar de referencia en sangre > 0.08 (rellenos no fiables) — una señal por CpG más precisa que la cobertura sola. Un reloj con muchos rellenos n_lowconf no es fiable en esta muestra aunque "se haya ejecutado".
• Diseñado solo para sangre. Esta habilidad asume SANGRE COMPLETA humana. Los relojes se aplican en sangre; la referencia de imputación es sangre. No lo use en otros tejidos.
• Imputación de CpG faltantes — methyLImp por defecto. Los CpG faltantes de los relojes (p. ej., CpG entrenados en EPIC ausentes en una exportación de MSA/WeGene) se imputan con methyLImp: regresión de rango reducido (PCA) que predice cada CpG faltante a partir de los CpG observados de la muestra usando la estructura de correlación entre CpG de un panel de sangre completa — más preciso que una mediana plana (~30% menos RMSE cuando el tejido coincide). Los CpG que faltan en el panel recurren a la mediana de sangre; n_lowconf (SD sangre >0.08) marca rellenos no fiables. El modo activo se imprime al inicio de la ejecución.
  • El panel está en data/blood_panel.npz y está incluido (~5 MB; preconstruido a partir de GSE40279 = 656 muestras de sangre completa 450K, reducido a los CpG de los relojes + 50 PCs de sangre + mediana/SD por CpG). Así que methyLImp está activo desde el primer momento: reduce el RMSE de imputación ~10% frente a una mediana plana en un punto de referencia con CpG retenidos. Para reconstruir/personalizar, ejecute scripts/build_blood_panel.py. Si el archivo falta, la herramienta degrada suavemente a mediana global y lo indica.
  • Comprobación realista: methyLImp mejora principalmente los relojes muy imputados. Los relojes de alta cobertura (GrimAge/Horvath/PhenoAge) imputan pocos CpG, por lo que sus valores se mueven <0.2 años independientemente — la bandera de confianza es la ganancia práctica más importante.
• No es consejo médico — solo para uso investigativo/educativo.

Notas

• Entrada en matriz → una fila de resultado por muestra y por reloj.
• Excluidos deliberadamente (no se pueden reproducir fielmente sin maquinaria más pesada, o no son relojes de envejecimiento):
  • Relojes PC (PCHorvath…), AltumAge, GPAge — necesitan rotación PCA / redes neuronales.
  • Relojes gestacionales (Knight, Lee, Mayne, Bohlin) — para sangre de cordón / recién nacidos.
  • Predictores de rasgos y enfermedades (IMC, colesterol, tabaquismo, alcohol, Alzheimer, ECV, …) — son modelos de biomarcadores, no relojes de envejecimiento. Si un usuario necesita específicamente uno de estos, dígale que requiere la instalación completa de biolearn.
• Procedencia. Los coeficientes son de biolearn (MIT), que reimplementa los relojes publicados. GrimAge tiene restricciones de uso comercial (UCLA TDG / Clock Foundation) para cosméticos y seguros de vida.