UltrasonicGuard

Español | English

Prototipo de IA abierta para la detección temprana de degradación en rodamientos de maquinaria industrial, orientado a planificar mantenimiento preventivo antes del fallo.

Prueba de concepto sobre datos públicos; pendiente de validación en entorno industrial real.

---

Tabla de contenidos

1. Descripción
2. Alcance actual y evolución prevista
3. Stack tecnológico
4. Estructura del repositorio
5. Instalación y uso
6. Datos
7. Modelo
8. Métricas
9. Limitaciones conocidas
10. Uso responsable y supervisión humana
11. Licencia

Anexo: Alineamiento voluntario con la Guía 15 de AESIA

---

1. Descripción

UltrasonicGuard analiza señales procedentes de rodamientos en servicio y emite un aviso cuando el sistema estima que se aproxima un fallo. El objetivo operativo es habilitar el reemplazo del rodamiento durante una ventana de parada planificada, evitando paradas no programadas.

Important

El sistema no toma decisiones automáticas de parada ni de intervención: actúa como apoyo informativo al equipo de mantenimiento, que decide cuándo intervenir.

Salida del sistema:

• Clasificación del estado del rodamiento en niveles de gravedad.
• Recomendación operativa asociada a cada nivel (seguir monitorizando, programar sustitución en próximo paro, intervenir de forma prioritaria).
• Probabilidad asociada a la predicción para facilitar la interpretación.

2. Alcance actual y evolución prevista

Alcance del prototipo (TRL 2): trabaja exclusivamente con señales de vibración procedentes del dataset público IEEE PHM 2012 (ver sección 5). Demuestra la viabilidad técnica del enfoque sobre datos de banco de ensayo.

Evolución prevista (fuera del alcance del hackathon):

• Incorporación de señales de ultrasonidos, que permiten detectar la degradación en fases más tempranas que la vibración.
• Validación sobre datos de maquinaria minera real.
• Integración con sistemas de gestión de mantenimiento (CMMS).

3. Stack tecnológico

Componente	Tecnología
Modelo de clasificación	XGBoost
Procesamiento de datos	pandas, NumPy, SciPy, PyArrow
Modelado y persistencia	XGBoost, scikit-learn, joblib
Experimentación	Jupyter Notebook
Dashboard	Streamlit, Plotly
Visualización en notebooks	Matplotlib, Seaborn
Lenguaje	Python 3.10+

4. Estructura del repositorio

ultrasonicguard/
├── src/                   # módulos de carga, features, modelo y alertas
│   ├── loader.py
│   ├── features.py
│   ├── model.py
│   ├── alerts.py
│   └── paths.py
├── scripts/               # ejecución del pipeline de notebooks
│   ├── execute_notebook.py
│   └── run_notebook_pipeline.py
├── notebooks/             # pipeline exploración, analítico, features y entrenamiento
├── data/                  # datos (no versionados; ver sección 6)
├── features/              # features generadas por el pipeline (no versionados; ver sección 5)
├── models/                # artefactos del modelo entrenado
├── assets/                # recursos estáticos del dashboard (CSS)
├── dashboard.py           # dashboard Streamlit
├── requirements.txt
├── LICENSE
└── README.md

5. Instalación y uso

git clone <repo>
cd ultrasonicguard
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Pipeline de notebooks: antes de abrir el dashboard, ejecutar el pipeline analítico completo:

python scripts/run_notebook_pipeline.py

Este script ejecuta en orden los notebooks 00 a 04:

1. construcción de parquets por rodamiento;
2. exploración visual de señal;
3. extracción de features;
4. etiquetado heurístico de severidad;
5. entrenamiento y exportación del clasificador XGBoost.

El pipeline genera los artefactos necesarios en data/processed/, features/ y models/. Si ya existen parquets procesados, se reutilizan.

Dashboard:

streamlit run dashboard.py

6. Datos

Los datos proceden del IEEE PHM 2012 Prognostic Challenge Dataset, redistribuido en:

• https://github.com/Lucky-Loek/ieee-phm-2012-data-challenge-dataset

Warning

Aviso sobre la fuente: el repositorio redistribuye datos cuya fuente original (web del reto IEEE PHM 2012) ya no está disponible. El repositorio no especifica licencia explícita pero solicita citación. Al no existir una licencia clara, el uso en este proyecto se realiza con fines de investigación en el marco del hackathon y se incluye la atribución solicitada. Cualquier reutilización aguas abajo debe valorar este punto.

Cita:

IEEE PHM 2012 Prognostic Challenge Dataset (FEMTO-ST Institute), redistribuido en el repositorio de Lucky-Loek en GitHub.

Los datos consisten en mediciones de aceleración de rodamientos sometidos a degradación acelerada hasta el fallo, en distintas condiciones de operación.

7. Modelo

• Tipo: clasificador multiclase XGBoost (multi:softprob, 3 clases). Aunque el algoritmo es supervisado, las etiquetas de entrenamiento (Sano/Degradado/Crítico) no están anotadas por un experto: se generan automáticamente por reglas sobre los ratios suavizados respecto a la línea basal de cada rodamiento y un detector de inicio de degradación (src/features.py:label_bearing_features).
• Entrada: características extraídas de las señales de vibración (estadísticos en dominio temporal y frecuencial mediante FFT y descriptores como RMS, energía, picos y frecuencias dominantes).
• Variable objetivo: nivel de gravedad de la degradación del rodamiento.
• Salida: clase predicha más probabilidad asociada.

8. Métricas

Las métricas reportadas en el conjunto de validación se documentan en el notebook de evaluación. Incluyen, como mínimo:

• Precisión, recall y F1 por clase.
• Matriz de confusión.
• Análisis del coste asimétrico entre falso negativo (fallo no anticipado → parada no planificada) y falso positivo (mantenimiento adelantado innecesariamente).

9. Limitaciones conocidas

• Madurez TRL 2: el sistema es una prueba de concepto. No ha sido validado en entorno industrial real.
• Dataset de laboratorio: los datos provienen de un banco de ensayos (FEMTO-ST), no de maquinaria minera. La transferencia a condiciones de campo requiere validación adicional.
• Solo vibración: el prototipo no incorpora aún ultrasonidos, pese a estar en el nombre del proyecto; ver sección 2.
• Dominio acotado: entrenado sobre rodamientos y condiciones de carga específicas; fuera de ese dominio el rendimiento no está garantizado.
• Granularidad fija de la salida: el sistema reporta exactamente tres niveles de gravedad (Sano, Degradado, Crítico), definidos como constante (STATE_LABELS en src/features.py). Cualquier escalado intermedio o adicional requiere modificar código y reentrenar.
• No sustituye a la inspección física ni a otros sistemas de monitorización condicional.

10. Uso responsable y supervisión humana

• Toda alerta del sistema debe ser revisada por personal de mantenimiento antes de programar una intervención.
• El sistema reporta probabilidad asociada a cada predicción; valores cercanos al umbral deben tratarse como casos de baja confianza.
• El dashboard expone las features que más han contribuido a cada alerta para facilitar la interpretación.

11. Licencia

Código del proyecto: Apache License 2.0. Ver el fichero LICENSE.

Los datos de entrada se rigen por las condiciones descritas en la sección 6.

---

Anexo A — Alineamiento voluntario con la Guía 15 de AESIA (Documentación Técnica)

UltrasonicGuard no es un sistema de IA de alto riesgo según el Anexo III del Reglamento Europeo de IA: el mantenimiento predictivo industrial no figura entre los ámbitos clasificados como alto riesgo, y el sistema no toma decisiones automatizadas sobre personas.

Por tanto, las obligaciones de documentación técnica del Artículo 11 y Anexo IV del Reglamento no aplican formalmente. No obstante, en el marco del Reto IA Responsable y Abierta en Industria se adopta de forma voluntaria la estructura propuesta en la Guía 15. Documentación técnica del sandbox español de IA (AESIA), por considerarla buena práctica. El nivel de detalle aplicado es proporcional al estado TRL 2 del prototipo.

Correspondencia entre la guía y este README:

Apartado Anexo IV / Guía AESIA	Ubicación en este proyecto
1. Descripción general del sistema	Secciones 1, 2 y 3
2(a)–(c). Métodos, diseño y arquitectura	Sección 7 y src/
2(d). Requisitos en materia de datos	Sección 6 y notebook de preparación
2(e). Supervisión humana	Sección 10
2(g). Validación y prueba	Sección 8 y notebook de evaluación
3. Seguimiento, capacidades y limitaciones	Secciones 8 y 9
4. Idoneidad de los parámetros de rendimiento	Sección 8
5. Gestión de riesgos	No formalizada (no aplica al no ser alto riesgo); riesgos relevantes en sección 9
6. Control de cambios	Historial de Git
7. Normas armonizadas	No aplica
8. Declaración UE de conformidad	No aplica
9. Vigilancia poscomercialización	No aplica