docs/DATASETS.md

Datasets para YouTube Boost AI

Este documento explica los datasets reales que actualmente entrenan el modelo y cómo agregar más en el futuro.

1. Datasets actualmente integrados

data/raw/ contiene dos datasets reales de Kaggle:

1.1 daily_trending_videos.csv

• Origen: scrap diario de YouTube Trending por región.
• Tamaño: ~100 MB, 674.141 filas crudas.
• Cobertura: 92 países, periodo 2025-01 → 2025-07.
• Columnas: video_id, title, channel, country, views, likes, comments, published_at, fetch_date.
• Limitaciones: sin description, sin tags, sin category_id, sin duration_seconds. Cada video_id se repite varias veces (uno por día en trending).

1.2 youtube_trending_in_kaggle_datasnaek_2017_2018.csv

• Origen: Kaggle datasnaek/youtube-new (Trending YouTube Video Statistics).
• Tamaño: ~67 MB, 37.352 filas crudas.
• Cobertura: India (sólo región IN), periodo 2017-2018.
• Columnas: video_id, title, description, tags, category_id, views, likes, dislikes, comments, published_at, region, country, ....
• Limitaciones: duration_seconds=0 siempre (la fuente no la trae); duplicados por video_id para apariciones diarias.

2. Pipeline de ingesta

Cuando ejecutas python -m src.train:

1. Carga ambos CSV concatenados → 711.493 filas crudas.
2. Normaliza columnas con src.features.normalize_training_dataframe (vectorizado, ~20s).
3. Deduplica por video_id, quedándose con la fila de máximo views → 68.526 filas únicas.
4. Etiqueta boost_candidate por percentil 70 del organic_performance_score.
5. Guarda dataset procesado en data/processed/youtube_training_dataset.csv.
6. Genera outputs/eda_summary.{md,json} con estadísticas reales del corpus.
7. Entrena 3-4 modelos (HGB es opt-in con ENABLE_HGB=1).
8. Persiste el mejor en models/best_model.joblib y metadata en models/model_metadata.json con "dataset_kind": "real_kaggle".

3. Verificación

Después de entrenar:

# Confirmar origen real
python -c "import json; print(json.load(open('models/model_metadata.json'))['dataset_kind'])"
# → real_kaggle

# Ver EDA generado
head -30 outputs/eda_summary.md

4. Métricas obtenidas

Con percentil del target = 0.70 (clase positiva ≈ 30%):

Modelo	F1	ROC-AUC	Recall	Precision
LogisticRegression (best)	0.521	0.733	0.567	0.482
RandomForest	0.472	0.744	0.378	0.628
LinearSVC calibrado	0.425	0.735	0.301	0.722
HistGradientBoosting	0.390	0.755	0.255	0.826

Nota metodológica importante: estas métricas son honestas porque el set de features de entrenamiento excluye deliberadamente las variables que componen el target (engagement_rate, views_per_day, text_power_score, etc.). Sin esta exclusión el modelo tendría F1 ≈ 0.99, pero solo estaría memorizando su propia etiqueta. Ver sección "Anti-leakage" en docs/ANALISIS_METODOLOGICO.md.

5. Sesgo de selección a declarar en defensa

Ambos datasets contienen únicamente videos que estuvieron en trending. El modelo aprende a distinguir "muy buenos" del resto, no "buenos" de "malos". Implicaciones:

• Las probabilidades del modelo tienden a ser altas incluso para inputs débiles.
• La regla del recomendador (ajustar antes de impulsar cuando faltan señales) compensa esta tendencia.
• Para una versión sin sesgo se necesitaría una muestra aleatoria de YouTube (no disponible públicamente).

6. Cómo agregar más datasets

Cualquier CSV agregado a data/raw/ se ingiere automáticamente. Las columnas reconocidas (con autorenombrado):

Columna canónica	Variantes aceptadas
views	view_count, views_count
likes	like_count, likes_count
comments	comment_count, comments_count
published_at	publishedAt, publish_time
category_id	categoryId
channel_title	channelTitle, channel

Si tu CSV usa otros nombres, agrégalos al diccionario rename_candidates en src/features.py::normalize_training_dataframe.

Datasets adicionales recomendados

Slug Kaggle	Contenido	Tamaño
rsrishav/youtube-trending-video-dataset	Trending diario, 10+ regiones	~150 MB
nelgiriyewithana/global-youtube-statistics-2023	Estadísticas globales de canales top	~1 MB

Para descargar automáticamente con credenciales Kaggle:

pip install kaggle
mkdir -p ~/.kaggle && mv kaggle.json ~/.kaggle/ && chmod 600 ~/.kaggle/kaggle.json
python scripts/download_kaggle_datasets.py
python -m src.train

7. Subset rápido para iterar

Si quieres entrenar más rápido sobre un subset (estratificado por clase):

MAX_TRAIN_ROWS=10000 python -m src.train

8. Cuándo regenerar el modelo

• Tras agregar un nuevo CSV a data/raw/.
• Tras modificar NUMERIC_COLS, CATEGORICAL_COLS o TEXT_COL en src/train.py.
• Tras modificar la lógica de normalize_training_dataframe en src/features.py.
• Tras modificar la fórmula de organic_performance_score en create_boost_candidate_target.