Detecta si tu modelo de materiales hace trampa con la “huella bibliográfica”

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 Materials para descubrirlo.

El problema: cuando el modelo lee el membrete, no la ciencia

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.

Qué hace la herramienta

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):

1. Clasificador de metadata — ¿se puede predecir la bibliografía (autor/revista/año) a partir de los descriptores químicos? Si es above-chance, hay una señal bibliográfica presente.
2. Huella bibliográfica — ¿un modelo que usa solo la metadata predicha se acerca al modelo con descriptores? Entonces el dataset no descarta hacer “trampa” por bibliografía.
3. Split por grupo/tiempo — ¿colapsa el rendimiento si separas por autor/año en vez de al azar?
4. Veredicto — un score low / medium / high de riesgo de confounding.

El rigor que exige el test (para especialistas)

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.

Cómo usarlo

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.

Por qué no basta con Giskard

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.

Estado y verificación

• Tests: 17 passed (suite rápida) + sweep de semillas marcado como lento.
• Calidad: ruff limpio, cobertura ~88%.
• Licencia: AGPL-3.0-or-later.

Referencias

• Jablonka et al. (2026) — Clever Materials: el test de falsificación y las cinco tareas.
• Huang & Cole (2020) — Battery Materials Database, Scientific Data
• Nandy et al. (2022) — MOFSimplify, Scientific Data
• Huang & Cole (2024) — TADF database, Scientific Data
• Shabih et al. / Jacobsson (2021) — Perovskite Database

Repositorio: https://github.com/amurlaniakea/materials-confounding-check — Licencia AGPL-3.0-or-later, Pedro Sordo Martínez.