GNN sobre red de citas

Objetivo

Clasificar publicaciones científicas usando texto y enlaces de citas.

Dataset real

• Dataset: cora
• Fuente: PyTorch Geometric / Planetoid
• Referencia: https://pytorch-geometric.readthedocs.io/en/stable/generated/torch_geometric.datasets.Planetoid.html
• Licencia/condiciones: Consultar dataset original
• Uso: los datos se descargan desde la fuente; no hay ejemplos sintéticos ni archivos inventados.

Usa las máscaras públicas fijas de train, validación y test.

Fundamento matemático

H^(l+1)=σ(D^-1/2 Â D^-1/2 H^l W^l).

Protocolo experimental

1. Descargar y verificar la procedencia.
2. Conservar o crear una partición reproducible.
3. Ajustar transformaciones únicamente con train.
4. Seleccionar modelo e hiperparámetros usando validation.
5. Evaluar test una sola vez tras congelar la decisión.
6. Comparar con la línea base: MLP sin aristas.
7. Guardar configuración, entorno, métricas, predicciones, gráficos y modelo.

Ejecución

python labs/09_gnn_graphs/train.py --quick
python labs/09_gnn_graphs/train.py --config improved

Preparar únicamente el dataset:

python -m neural_labs.cli dataset --lab 09_gnn_graphs

Inferencia y exportación:

neural-labs predict --lab 09_gnn_graphs --run latest --input sample.json
neural-labs export --lab 09_gnn_graphs --run latest --format onnx --verify

Métricas

accuracy, macro_f1.

Archivos

• notebook.ipynb: recorrido completo y ejecutable.
• notebook_student.ipynb: actividades evaluables sin soluciones.
• notebook_solution.ipynb: resolución docente y pruebas de referencia.
• train.py: interfaz de terminal que usa el mismo código del cuaderno.
• configs/baseline.yaml: configuración base.
• configs/improved.yaml: configuración ampliada.
• data/dataset.yaml: procedencia, licencia y política de partición.

Ejercicios

• Cambiar una decisión experimental y justificarla.
• Analizar errores por clase o segmento.
• Comparar costo, precisión y latencia.
• Documentar sesgos, limitaciones y usos no recomendados.

Material formativo v3

• theory.md: fundamento, protocolo y riesgos de interpretación.
• experiments.md: hipótesis, variables controladas y tabla multi-semilla.
• assessment.md: preguntas y rúbrica de evaluación.
• lesson.yaml: resultados de aprendizaje, prerrequisitos y entregables.

Comandos profesionales

neural-labs quality --lab 09_gnn_graphs --quick
neural-labs benchmark --lab 09_gnn_graphs --quick --split-seed 42 --training-seeds 41 42 43
neural-labs leaderboard

Sellado del experimento

La partición se controla con split_seed; la inicialización y el entrenamiento con training_seed. El conjunto test se abre solamente después de seleccionar el checkpoint mediante validación y escribir experiment.lock.json.

🧠 Teoría

Teoría — GNN sobre red de citas

Propósito

Clasificar publicaciones científicas usando texto y enlaces de citas.

Idea central

Este laboratorio estudia propagación de mensajes sobre grafos usando cora, un dataset público real procedente de PyTorch Geometric / Planetoid.

Cora es una red de citas: cada nodo es un artículo científico descrito por un vector de palabras (bolsa de términos), y cada arista es una cita entre dos artículos. La hipótesis que da sentido al laboratorio es la homofilia: los artículos que se citan tienden a tratar temas afines, de modo que la estructura del grafo aporta información que el texto por sí solo no captura. Una red neuronal de grafos (GNN) explota esa estructura haciendo que cada nodo actualice su representación combinando la suya con la de sus vecinos. Al apilar varias capas, la información se propaga a vecinos de vecinos, y cada nodo termina con un embedding que resume su vecindario local en el grafo.

El mecanismo general se llama paso de mensajes (message passing): en cada capa, cada nodo (1) recibe "mensajes" de sus vecinos, (2) los agrega con una función permutación-invariante (suma, media, máximo o atención) y (3) actualiza su estado con esa agregación. La línea base del laboratorio —un MLP que ignora las aristas— sirve justo para cuantificar cuánto aporta la estructura de citaciones frente a usar solo el texto de cada artículo.

Fundamento matemático

La red convolucional de grafos (GCN) de Kipf & Welling define la actualización de una capa como:

H^(l+1) = σ( D̃^{−1/2} Ã D̃^{−1/2} H^(l) W^(l) )

Desglosemos cada símbolo. H^(l) ∈ ℝ^{N×d_l} apila las representaciones de los N nodos en la capa l (H^(0) son las características de entrada). Ã = A + I es la matriz de adyacencia con auto-lazos añadidos, para que cada nodo se incluya a sí mismo en la agregación y no pierda su propia información. D̃ es la matriz diagonal de grados de Ã, con D̃ᵢᵢ = Σⱼ Ãᵢⱼ. W^(l) es la matriz de pesos aprendible que transforma las características, y σ es una no linealidad (ReLU). El término D̃^{−1/2} Ã D̃^{−1/2} es la adyacencia normalizada simétricamente: propaga las representaciones a los vecinos pero reescalando cada mensaje por 1/√(dᵢ·dⱼ), de modo que los nodos de grado muy alto (muy citados) no dominen la suma ni disparen la escala de las activaciones.

Intuitivamente, cada fila de esa multiplicación calcula, para el nodo i, un promedio ponderado normalizado de las características transformadas de i y de sus vecinos: hᵢ^(l+1) = σ( Σ_{j∈𝒩(i)∪{i}} (1/√(d̃ᵢ d̃ⱼ)) · hⱼ^(l) W^(l) ). Apilar L capas equivale a difundir información hasta L saltos de distancia; con L=2, cada artículo "ve" a los artículos que cita y a los que citan a esos. Un exceso de capas provoca sobre-suavizado (over-smoothing): las representaciones de todos los nodos convergen y se vuelven indistinguibles, por lo que en la práctica las GCN son poco profundas.

Conectando con los cuatro elementos: la representación de entrada es la matriz H^(0) de vectores de palabras por nodo más la estructura del grafo en A; la función del modelo es el apilamiento de capas GCN que termina en un softmax sobre las 7 clases temáticas; la función de pérdida es la entropía cruzada calculada solo sobre los nodos de entrenamiento enmascarados, ℒ = −Σ_{i∈train} Σ_c y_{ic} log ŷ_{ic}; y la regla de actualización es descenso de gradiente (Adam), θ ← θ − η ∇_θ ℒ. Es un problema transductivo: el grafo completo (con todos los nodos y aristas) participa en cada forward, pero el gradiente solo usa las etiquetas de la máscara de train. El notebook muestra las dimensiones de los tensores (N, d_l) en cada capa y conserva la misma implementación que el script de terminal.

El laboratorio compara variantes del paso de mensajes. GraphSAGE (Hamilton et al.) reemplaza la agregación por una que muestrea un subconjunto de vecinos y concatena el estado propio con el agregado, lo que la hace inductiva (generaliza a nodos nuevos no vistos). GAT (Veličković et al.) sustituye los pesos fijos de normalización por coeficientes de atención aprendidos α_{ij} = softmax_j( LeakyReLU(aᵀ[W hᵢ ‖ W hⱼ]) ), de modo que cada nodo decide cuánto pesar a cada vecino en lugar de usar solo el grado. Comparar GCN, GraphSAGE y GAT ilustra cómo cambia el resultado según cómo se agregan los mensajes.

Protocolo científico

• Ajustar transformaciones, vocabulario, normalización y selección de variables solo con train.
• Usar validation para arquitectura, hiperparámetros, checkpoint y umbrales.
• Evaluar test una vez, después de congelar las decisiones.
• Comparar contra MLP sin aristas.
• Reportar variación entre semillas e intervalos de confianza; una métrica puntual no expresa toda la incertidumbre.

Riesgos de interpretación

Usa las máscaras públicas fijas de train, validación y test.

El dataset refleja su proceso de recolección y no representa automáticamente otros períodos, países o poblaciones. Una asociación predictiva no demuestra causalidad.

Pregunta crítica

¿Cuánto aporta la estructura de citaciones?

Las referencias apuntan a las obras; no se reproduce su contenido, la redacción es original.

🔗 Referencias

• Hamilton — Graph Representation Learning (Morgan & Claypool, 2020) — texto de referencia sobre embeddings de grafos, paso de mensajes y GNN.
• Kipf & Welling (2017), Semi-Supervised Classification with Graph Convolutional Networks, ICLR — la GCN y la normalización simétrica de la adyacencia usada en este laboratorio.
• Hamilton, Ying & Leskovec (2017), Inductive Representation Learning on Large Graphs (GraphSAGE), NeurIPS — agregación por muestreo de vecinos y aprendizaje inductivo.
• Veličković et al. (2018), Graph Attention Networks, ICLR — atención sobre vecinos para ponderar mensajes de forma aprendida.
• Fuente del dataset: https://pytorch-geometric.readthedocs.io/en/stable/generated/torch_geometric.datasets.Planetoid.html
• Consulte docs/experiment-protocol.md, docs/reproducibility.md y docs/ethics-and-licenses.md.

🔬 Experimentos

Plan de experimentos — GNN sobre red de citas

Hipótesis principal

Clasificar publicaciones científicas usando texto y enlaces de citas. La hipótesis debe aceptarse o rechazarse comparando el modelo con MLP sin aristas y no solo observando que la pérdida disminuye.

Experimento mínimo

1. Ejecutar baseline.yaml con tres semillas.
2. Ejecutar improved.yaml con las mismas semillas.
3. Mantener fija la partición de datos dentro de cada semilla.
4. Elegir la variante con validation.
5. Comparar la variante elegida contra la línea base en test.
6. Revisar intervalos de confianza, errores y costo computacional.

Experimento específico

Comparar con un mlp que ignore aristas.

Variables controladas

• Dataset y política de partición.
• Semillas declaradas.
• Presupuesto de épocas y criterio de parada.
• Métrica de selección: accuracy o la especificada en la configuración.
• Hardware y versiones registradas en environment.json.

Tabla que debe completarse

Criterio de conclusión

La conclusión debe declarar magnitud de la mejora, incertidumbre, costo adicional, errores relevantes y condiciones bajo las cuales el resultado podría no repetirse.

📝 Evaluación

Evaluación — GNN sobre red de citas

Evidencias obligatorias

• Dataset preparado y auditoría sin solapamientos.
• Notebook ejecutado sin celdas omitidas.
• Línea base y modelo neuronal comparados.
• Resultados de al menos tres semillas o justificación del costo.
• Análisis de errores y limitaciones.
• Model card actualizada.

Preguntas

1. Explique con sus palabras: H^(l+1)=σ(D^-1/2 Â D^-1/2 H^l W^l).
2. ¿Qué información del dataset solo puede utilizarse durante entrenamiento?
3. ¿Por qué la línea base MLP sin aristas es una comparación razonable?
4. ¿Cuánto aporta la estructura de citaciones?
5. ¿Qué cambiaría antes de usar este modelo fuera del laboratorio?

Rúbrica

La aprobación exige al menos 70% y cero errores críticos de fuga de datos.