Optimización de Hiperparámetros con Optuna¶

Esta documentación reemplaza la guía extensa que antes vivía comentada dentro de configs/pipelines_config.yml. La idea es que el YAML quede corto y operativo, mientras que aquí quede explicada con detalle toda la lógica de la sección hyperparameter_optimization.

Script¶

python scripts/run_optimize_lgbm_hyperparameters.py --config configs/pipelines_config.yml

Overrides disponibles por CLI:

--trials
--cv-folds
--min-recall
--min-accuracy
--timeout

Qué hace este pipeline¶

El script run_optimize_lgbm_hyperparameters.py ejecuta estudios de Optuna sobre modelos LightGBM para encontrar una mejor combinación de hiperparámetros para:

detección binaria PFM,
clasificación multiclass PFM (size, location),
regresión PFM (leakflow),
detección/regresión OBSERVER,
regresión OBSERVER (size, location).

Durante la optimización:

toma el dataset de features,
determina qué pipeline real está optimizando a partir de pipeline_type + label_column,
hereda la configuración base del pipeline de entrenamiento correspondiente,
aplica los parámetros específicos de hyperparameter_optimization,
ejecuta Optuna con validación cruzada,
guarda los mejores parámetros y un resumen del estudio.

Artefactos generados¶

En output_folder se escriben:

optimized_params.json: mejores hiperparámetros encontrados.
optuna_study.json: resumen del estudio, trials y métricas agregadas.
optuna_run_metadata.json: hash de configuración para idempotencia.
Opcionalmente, schemas reducidos de features si se activa feature selection antes o después de Optuna.

Configuración mínima recomendada¶

Después de simplificar pipelines_config.yml, el bloque mínimo recomendado queda así:

hyperparameter_optimization:
  pipeline_type: "PFM"
  input_path: "data/features/supe/diesel/data/features_dataset.parquet"
  features_schema_file: "data/features/supe/diesel/metadata/features_schema.json"
  output_folder: "models/supe/3transmitters/diesel/PFM/tunning/lgbm_location"
  label_column: "LEAK_LOCATION_m"
  overfitting_penalty_alpha: 3.0
  min_accuracy: 0.55
  n_trials: 50
  cv_folds: 5
  timeout: 3600

Parámetros requeridos¶

Los siguientes parámetros deben venir explícitamente en hyperparameter_optimization:

Parámetro	Requerido	Qué define
`pipeline_type`	Sí	Familia del pipeline: `PFM` u `OBSERVER`.
`input_path`	Sí	Dataset `.parquet` de features, archivo o carpeta.
`features_schema_file`	Sí	Schema JSON de features a usar durante la optimización.
`output_folder`	Sí	Carpeta donde se guardan resultados de Optuna.
`label_column`	Sí	Target que determina qué pipeline concreto se optimiza.

Cómo indicar qué pipeline optimizar¶

La combinación de pipeline_type y label_column es la que le dice al script qué problema debe resolver. No basta con indicar solo el dataset; Optuna necesita saber si está optimizando:

detección binaria,
clasificación multiclass de tamaño,
clasificación multiclass de ubicación,
regresión de flujo,
o las variantes OBSERVER equivalentes.

Valores admitidos:

pipeline_type: PFM u OBSERVER
label_column: null, label, LEAK_SIZE_in, LEAK_LOCATION_m o LEAK_FLOW_kg_s

Interpretación importante:

label_column: null se normaliza como label.
label_column: "label" y label_column: null significan exactamente lo mismo para el resolver interno del pipeline.

Cómo se resuelve el pipeline base¶

El script no optimiza “en abstracto”. Primero identifica qué sección de entrenamiento debe usar como base para heredar configuración y comportamiento.

`pipeline_type`	`label_column`	Pipeline base resuelto
`PFM`	`label`	`training_pfm_detection_pipeline`
`PFM`	`LEAK_SIZE_in`	`training_pfm_size_pipeline`
`PFM`	`LEAK_LOCATION_m`	`training_pfm_location_pipeline`
`PFM`	`LEAK_FLOW_kg_s`	`training_pfm_leakflow_pipeline`
`OBSERVER`	`label`	`training_observer_detection_pipeline`
`OBSERVER`	`LEAK_FLOW_kg_s`	`training_observer_detection_pipeline`
`OBSERVER`	`LEAK_SIZE_in`	`training_observer_size_pipeline`
`OBSERVER`	`LEAK_LOCATION_m`	`training_observer_location_pipeline`

Notas importantes:

En OBSERVER, label_column: "LEAK_FLOW_kg_s" y label_column: "label" terminan resolviendo el pipeline de detección/regresión de flujo.
El script usa esa sección base para heredar parámetros que no están en hyperparameter_optimization.

Mapeo conceptual por familia¶

PFM¶

label_column: null o label: detection binaria.
label_column: LEAK_SIZE_in: problema multiclass de tamaño; el valor continuo se discretiza en clases antes de entrenar.
label_column: LEAK_LOCATION_m: problema multiclass de ubicación; el valor continuo se discretiza en clases antes de entrenar.
label_column: LEAK_FLOW_kg_s: regresión pura de flujo de fuga.

OBSERVER¶

label_column: null o label: detección basada en una regresión de flujo con umbral posterior.
label_column: LEAK_SIZE_in: regresión continua de tamaño.
label_column: LEAK_LOCATION_m: regresión continua de ubicación.
label_column: LEAK_FLOW_kg_s: también se trata como detección/regresión de flujo con umbral, usando el pipeline OBSERVER detection.

Diferencias clave entre PFM y OBSERVER¶

Las mismas columnas pueden representar problemas distintos según pipeline_type.

`LEAK_SIZE_in`¶

En PFM, se trata como clasificación multiclass: el valor continuo se agrupa en clases discretas y la optimización busca hiperparámetros para clasificar esas clases.
En OBSERVER, se trata como regresión: el modelo predice directamente el valor continuo de tamaño.

`LEAK_LOCATION_m`¶

En PFM, se trata como clasificación multiclass: la ubicación se discretiza en clases.
En OBSERVER, se trata como regresión: el modelo predice la ubicación continua.

`LEAK_FLOW_kg_s`¶

En PFM, es una regresión directa de flujo.
En OBSERVER, se usa como parte del flujo de detección: se entrena una regresión y luego se aplica un umbral para obtener decisión binaria.

Qué se hereda automáticamente del pipeline base¶

Aunque el bloque de optimización ahora es mínimo, el script sigue reutilizando configuración del pipeline de entrenamiento correspondiente:

test_size, random_state y shuffle.
lgbm_params base: sobre todo objective, metric y cualquier parámetro que quieras dejar fijo.
deviation_percentage para PFM multiclass (size y location) si no se sobrescribe.
filtros de regresión como filter_zero_flow, filter_zero_size, filter_zero_location y min_label.
num_boost_round, early_stopping_rounds y min_improvement del pipeline base cuando:
optimize_training_params es false, y
num_boost_round_fixed, early_stopping_rounds_fixed o min_improvement_fixed están en null.
configuración auxiliar de feature_selection_pipeline cuando se activa selección de features pre o post Optuna.

Importante sobre `robustness`¶

Aunque la configuración base del pipeline pueda traer robustness, el script de Optuna la desactiva intencionalmente durante la búsqueda:

Optuna busca hiperparámetros sobre datos limpios.
La augmentación/robustness puede sesgar la búsqueda hacia configuraciones que compensen ruido artificial.
El objetivo es optimizar primero el modelo base; la robustez se aplica en entrenamiento final, no en la búsqueda.

Parámetros opcionales y defaults internos del script¶

Los siguientes parámetros ya no necesitan quedar escritos en pipelines_config.yml, porque el script ahora los completa por defecto con estos valores:

Control general de la optimización¶

Parámetro	Default	Qué hace
`enable_feature_selection_after_tuning`	`true`	Ejecuta feature selection al final usando el mejor modelo de Optuna.
`enable_feature_selection_before_tuning`	`false`	Si se activa, corre feature selection antes de Optuna y usa el schema reducido en todos los trials.
`overfitting_penalty_alpha`	`3.0`	Intensidad de penalización por gap train/validation.
`min_accuracy`	`0.55`	Constraint duro para pipelines multiclass.
`n_trials`	`50`	Cantidad de trials de Optuna.
`cv_folds`	`5`	Folds de validación cruzada.
`timeout`	`3600`	Límite máximo en segundos para el estudio.
`optimize_training_params`	`false`	Si `true`, Optuna también busca `num_boost_round`, `early_stopping_rounds` y `min_improvement`.
`optuna_subsample_ratio`	`0.3`	Fracción del dataset usada por trial para acelerar la búsqueda.

Parámetros de entrenamiento a optimizar o heredar¶

Parámetro	Default	Comportamiento
`num_boost_round_fixed`	`null`	Si `optimize_training_params=false`, hereda `num_boost_round` del pipeline base.
`num_boost_round_min`	`200`	Límite inferior si se optimiza `num_boost_round`.
`num_boost_round_max`	`10000`	Límite superior si se optimiza `num_boost_round`.
`num_boost_round_step`	`100`	Paso de búsqueda para `num_boost_round`.
`early_stopping_rounds_fixed`	`null`	Si `optimize_training_params=false`, hereda `early_stopping_rounds` del pipeline base.
`early_stopping_rounds_min`	`30`	Límite inferior si se optimiza `early_stopping_rounds`.
`early_stopping_rounds_max`	`200`	Límite superior si se optimiza `early_stopping_rounds`.
`early_stopping_rounds_step`	`10`	Paso de búsqueda para `early_stopping_rounds`.
`min_improvement_fixed`	`null`	Si `optimize_training_params=false`, hereda `min_improvement` del pipeline base.
`min_improvement_min`	`1e-7`	Límite inferior si se optimiza `min_improvement`.
`min_improvement_max`	`1e-4`	Límite superior si se optimiza `min_improvement`.

Defaults adicionales por tipo de problema¶

Además de los defaults anteriores, el script mantiene estas reglas:

Detection binario: si no defines min_recall, usa 0.995.
Multiclass (size, location): si no defines deviation_percentage, se usa el del pipeline base; si no existe allí, cae en 5.0.
Regresión: min_accuracy puede seguir existiendo en la config, pero se ignora.

Explicación detallada de la estrategia de Optuna¶

1. TPE (Tree-structured Parzen Estimator)¶

Optuna no hace grid search ni random search puro. Usa TPE, que aprende de los trials anteriores para proponer nuevas combinaciones más prometedoras.

La lógica es:

observa qué combinaciones funcionaron bien,
modela una distribución de configuraciones buenas,
modela otra distribución de configuraciones malas,
propone el siguiente trial donde la probabilidad de mejora sea mayor.

2. Fase aleatoria + fase guiada¶

La búsqueda no arranca guiada desde el primer segundo. El script usa el comportamiento estándar de TPE con una fase inicial de exploración:

n_startup_trials = max(5, n_trials / 3)
con n_trials=50, los primeros ~16 trials son mayormente exploratorios;
luego TPE empieza a guiar activamente la búsqueda.

3. TPE multivariante¶

La configuración usa TPE con enfoque multivariante. Eso significa que Optuna no aprende cada parámetro aislado, sino sus relaciones conjuntas.

Ejemplo de correlaciones que sí puede aprender:

learning_rate bajo suele requerir más rounds o árboles más expresivos,
num_leaves alto puede necesitar más regularización,
subsample y colsample_bytree afectan conjuntamente la capacidad del modelo.

4. MedianPruner¶

El pruner cancela trials malos antes de que terminen todos sus folds.

En la práctica:

sin pruning: costo máximo = n_trials × cv_folds,
con pruning: muchos trials malos mueren en los primeros folds,
eso reduce entre 30% y 60% del trabajo en escenarios reales.

5. Subsampling por trial¶

optuna_subsample_ratio controla qué fracción del dataset usa cada trial.

Con el default actual:

optuna_subsample_ratio = 0.3
cada trial usa aproximadamente 30% del dataset de entrenamiento,
el ranking relativo entre configuraciones suele mantenerse,
el tiempo por trial baja mucho, lo que permite explorar más combinaciones en el mismo presupuesto de tiempo.

Estrategia anti-overfitting implementada¶

La optimización no busca solo la mejor métrica bruta. También penaliza configuraciones que memorizan o que son inestables entre folds.

Capa 1: separación por `case_id`¶

Cuando el dataset trae case_id, el script usa GroupKFold o GroupShuffleSplit para evitar fuga de información entre ventanas del mismo caso.

Esto es crítico porque múltiples ventanas del mismo caso pueden parecer distintas, pero comparten estructura temporal y física.

Capa 2: penalización por gap train/validation¶

Se mide el gap entre train y validation:

multiclass: típicamente F1_train - F1_val,
detection: típicamente Precision_train - Precision_val.

La penalización usa overfitting_penalty_alpha.

Ejemplo:

si alpha = 3.0 y el gap es 0.10, el castigo suma 0.30 al loss,
un modelo ligeramente peor en validación pero mucho más estable puede terminar siendo preferido.

Capa 3: penalización por inestabilidad entre folds¶

No basta con una media alta. También importa que el modelo sea consistente.

Se penaliza la desviación estándar entre folds. Un modelo con resultados muy dispares entre folds se considera menos confiable que otro con rendimiento ligeramente menor pero estable.

Capa 4: regularización buscada por Optuna¶

Optuna explora explícitamente hiperparámetros que controlan complejidad y regularización:

reg_alpha
reg_lambda
min_child_samples
min_data_in_leaf
min_split_gain
subsample
colsample_bytree

La regularización no es un “parche”. Es parte central del espacio de búsqueda.

Capa 5: early stopping en cada fold¶

Cada entrenamiento interno usa early stopping. Eso:

reduce tiempo,
evita sobreajuste dentro del fold,
hace que num_boost_round sea un máximo y no una obligación.

Fórmula conceptual de la función objetivo multiclass¶

De forma simplificada, la lógica es:

loss = -F1_val_media
     + alpha × max(0, F1_train_media - F1_val_media)
     + 0.1 × std(F1_val entre folds)
     + 1000 × max(0, min_accuracy - accuracy_media)

Optuna minimiza ese loss.

Interpretación:

el primer término quiere maximizar validación,
el segundo castiga overfitting,
el tercero castiga inestabilidad,
el cuarto aplica una restricción dura si no se alcanza min_accuracy.

Explicación detallada de las claves más importantes¶

`pipeline_type`¶

Selecciona la familia del pipeline base:

PFM
OBSERVER

Es obligatorio porque afecta:

la detección del pipeline real,
la sección base que se hereda,
la interpretación de label_column.

`label_column`¶

También es obligatorio porque define el problema concreto:

label → detection,
LEAK_SIZE_in → size,
LEAK_LOCATION_m → location,
LEAK_FLOW_kg_s → leakflow o observer detection según pipeline_type.

`overfitting_penalty_alpha`¶

Controla cuánto castiga el script el gap train/validation.

Guía práctica:

0.0: sin penalización,
1.0–2.0: penalización suave,
3.0: buen equilibrio general,
5.0–10.0: muy conservador, útil solo si el overfitting es severo.

`min_accuracy`¶

Aplica solo a problemas multiclass.

No es una recomendación universal. El valor actual (0.55) corresponde al caso configurado actualmente (PFM + LEAK_LOCATION_m), donde una accuracy del orden de 0.62 se observó como baseline razonable y 0.55 funciona como umbral alcanzable.

Si cambias a otro problema, este valor debería revisarse:

size suele tolerar un umbral más alto,
detection usa min_recall,
regresión no usa min_accuracy.

`n_trials`¶

Define cuántas combinaciones se prueban.

Más trials:

exploran más,
mejoran la probabilidad de encontrar un buen óptimo,
cuestan más tiempo.

Con pruning y subsampling, 50 suele ser una buena búsqueda inicial.

`cv_folds`¶

Más folds implican una estimación más robusta, pero más costo computacional.

5 folds es un buen punto intermedio para evitar tomar decisiones por ruido.

`timeout`¶

Evita que el estudio se extienda sin control.

Aunque queden trials pendientes, Optuna se detiene al llegar al timeout.

`enable_feature_selection_before_tuning`¶

Si se activa:

corre feature selection antes de Optuna,
genera un schema reducido,
todos los trials usan ese schema.

Útil cuando tienes muchas features y quieres bajar costo antes de optimizar.

`enable_feature_selection_after_tuning`¶

Si se activa:

Optuna encuentra el mejor modelo,
se calculan importancias sobre ese modelo,
se genera un schema final reducido para entrenamiento posterior.

Es muy útil para dejar listo un schema RFE o equivalente después de la optimización.

`optimize_training_params`¶

Define si Optuna también busca la mejor configuración de entrenamiento:

false: mantiene fijo el schedule de entrenamiento,
true: también explora num_boost_round, early_stopping_rounds y min_improvement.

Recomendación:

empezar con false,
usar true solo en refinamiento final.

`num_boost_round_fixed`, `early_stopping_rounds_fixed`, `min_improvement_fixed`¶

Cuando optimize_training_params es false:

si estos valores están en null, el script hereda los del pipeline base,
si defines un valor explícito, ese valor se usa fijo para todos los trials.

Cuando optimize_training_params es true:

null significa “deja que Optuna lo busque en el rango”.

Idempotencia¶

Si ya existen:

optimized_params.json
optuna_run_metadata.json

y el config_hash coincide con la configuración actual, el script no vuelve a ejecutar el estudio.

Soporte S3¶

input_path, output_folder y features_schema_file pueden apuntar a S3 si el entorno tiene soporte configurado (s3fs / extras S3 del proyecto).