Un modelo de ML puede predecir la propiedad de un material sin entender la química: basta con que "aprenda" qué autores, revistas o años suelen ir con cada resultado. Esta herramienta aplica el test de falsificación de
Clever Materialspara descubrirlo.
Imagina que entrenas un modelo para predecir si un material es estable. El modelo no mira la química: descubre que los artículos del grupo X (publicados en la revista Y, en torno al año Z) casi siempre reportan "estable". Así que aprende a clasificar por el membrete bibliográfico, no por la estructura. Funciona en el papel y se rompe en la práctica.
A esto se le llama confounding bibliográfico (o leakage por metadata). No es un error de código: es una señal espuria que el modelo aprovecha. El paper Clever Materials (Jablonka et al., 2026) mostró que este patrón está generalizado en cinco tareas reales de materials science.
materials-confounding-check
es una CLI (mcc check
) que corre cuatro sub-tests de falsificación sobre tu dataset (descriptores químicos + metadata bibliográfica + propiedad objetivo):
low
/ medium
/ high
de riesgo de confounding.El punto delicado de cualquier "test de significancia" es fijar el umbral a mano. Si ajustas el margen hasta que tu fixture pase, el test no prueba nada: es el anti-patrón Clever-Hans que el propio proyecto detecta.
Por eso el núcleo estadístico usa una distribución nula de N=100 permutaciones de la metadata (deterministas por semilla) y decide por percentil-95, no por un margen fijo. Y el test de detección (AC-4) usa un fixture con confounding inyectado independientemente, así el veredicto no sale de las propias reglas del tester. El veredicto (spurious → high
, clean → low
) se mantiene estable en un sweep de 4 semillas distintas.
pip install -e .
mcc check --in dataset.csv --out reporte.json
Opciones: --seed
(determinismo), --n-perm
(permutaciones de la distribución nula, por defecto 100), --group-by
(year|author), --no-metadata-enrich
(offline). El reporte JSON trae los cuatro bloques y el veredicto final.
Herramientas como Giskard cubren leakage tabular genérico, pero su scanner tabular (v2) está sin mantenimiento activo y no corre el test de huella bibliográfica específico de materials science. Ese es el hueco que esta herramienta llena.
ruff
limpio, cobertura ~88%.Repositorio: https://github.com/amurlaniakea/materials-confounding-check — Licencia AGPL-3.0-or-later, Pedro Sordo Martínez.