ronsuez/pals-enhanced-irt-v1

PALS Simplified Enhanced IRT Model

Este es un modelo IRT (Item Response Theory) multidimensional mejorado para la evaluación de competencias matemáticas.

Descripción del Modelo

El modelo implementa una arquitectura IRT neural que evalúa 4 competencias matemáticas:

• Resolver: Capacidad de resolver problemas matemáticos
• Modelar: Habilidad para modelar situaciones matemáticamente
• Representar: Competencia en representación matemática
• Argumentar: Capacidad de argumentación matemática

Características Principales

• Arquitectura: Red neural con matriz de interacciones entre competencias
• Parámetros: 20,057 parámetros entrenables
• Performance: AUC = 0.8131
• Competencias: 4 dimensiones matemáticas

Innovaciones

1. Matriz de Interacciones: Aprende relaciones entre competencias matemáticas
2. Pesos BERTIN: Integración con clasificación automática de contenidos
3. Calibración Adaptativa: Soporte para evaluación adaptativa computarizada

Uso del Modelo

1. Instalación

# Instalar dependencias
pip install -r requirements.txt

# O desde el repositorio
pip install torch numpy pandas scikit-learn matplotlib seaborn tqdm scipy huggingface-hub transformers

2. Uso Básico del Modelo

import torch
from pals_irt import PALSIRTModelForHF

# Cargar modelo desde Hugging Face Hub
model_wrapper = PALSIRTModelForHF.from_pretrained("ronsuez/pals-enhanced-irt-v1")
model = model_wrapper.model

# Preparar datos de ejemplo
item_features = torch.randn(1, 12)  # Características del ítem
student_features = torch.randn(1, 11)  # Características del estudiante
comp_weights = torch.tensor([[0.3, 0.3, 0.2, 0.2]])  # Pesos BERTIN

# Predecir probabilidad de respuesta correcta
with torch.no_grad():
    prob, difficulty, abilities, discriminations = model(
        item_features, 
        student_features, 
        comp_weights=comp_weights
    )

print(f"Probabilidad de respuesta correcta: {prob.item():.3f}")
print(f"Dificultad del ítem: {difficulty.item():.3f}")
print(f"Habilidades del estudiante: {abilities.squeeze().tolist()}")

3. Sistema Completo de Calibración

# Importar el sistema de calibración completo
from pals_calibration.models.multidimensional_irt import MultidimensionalIRTModel
from pals_calibration.training.trainer_multidim import MultidimTrainer
from pals_calibration.data.dataset import PALSDataset
from pals_calibration.evaluation.visualizer import TrainingVisualizer

# Cargar datos
dataset = PALSDataset.from_csv("responses.csv", "questions.csv", "students.csv")

# Crear y entrenar modelo
model = MultidimensionalIRTModel(
    n_item_features=12,
    n_student_features=11,
    hidden_dim=64
)

trainer = MultidimTrainer(
    model=model,
    train_dataset=dataset.train,
    val_dataset=dataset.val,
    config=trainer_config
)

# Entrenar
trainer.train()

# Visualizar resultados
visualizer = TrainingVisualizer()
visualizer.plot_training_curves(trainer.history)
visualizer.plot_competency_interactions(model.competency_interaction)

4. Scripts de Entrenamiento

# Entrenar modelo multidimensional
python -m scripts.training.train_multidim --config config.yaml

# Calibrar banco de preguntas
python -m scripts.calibration.calibrate_questions --data_path data/ --output calibration_results/

# Ejecutar evaluación completa
python -m scripts.evaluation.evaluate --model_path experiments/best_model.pth

Ejemplo de Calibración

# Calibrar un banco de ítems
import numpy as np

# Generar características sintéticas para demostración
n_items = 100
item_features_batch = torch.randn(n_items, 12)
student_features_batch = torch.randn(1000, 11)

# Pesos BERTIN por ítem (distribución realista)
bertin_weights = torch.rand(n_items, 4)
bertin_weights = bertin_weights / bertin_weights.sum(dim=1, keepdim=True)

calibrated_difficulties = []

with torch.no_grad():
    for i in range(n_items):
        # Expandir características del ítem para todos los estudiantes
        item_feat_expanded = item_features_batch[i:i+1].expand(1000, -1)
        weights_expanded = bertin_weights[i:i+1].expand(1000, -1)
        
        # Calcular parámetros
        _, difficulties, _, _ = model(
            item_feat_expanded,
            student_features_batch,
            comp_weights=weights_expanded
        )
        
        calibrated_difficulties.append(difficulties.mean().item())

print(f"Rango de dificultades calibradas: {min(calibrated_difficulties):.3f} a {max(calibrated_difficulties):.3f}")

Estructura del Repositorio

/
├── config.json                      # Configuración del modelo
├── pytorch_model.bin               # Pesos del modelo PyTorch
├── requirements.txt                # Dependencias de Python
├── README.md                       # Esta documentación
├── scalers.pkl                     # Escaladores para normalización
├── model_metadata.json             # Metadatos adicionales
├── pals_calibration/               # Paquete completo de calibración
│   ├── __init__.py
│   ├── config.py                   # Configuración del sistema
│   ├── models/                     # Modelos IRT
│   │   ├── base.py                 # Modelo base
│   │   ├── simple_irt.py          # IRT unidimensional
│   │   └── multidimensional_irt.py # IRT multidimensional
│   ├── training/                   # Entrenadores
│   │   ├── trainer_simple.py      # Entrenador simple
│   │   └── trainer_multidim.py    # Entrenador multidimensional
│   ├── data/                       # Manejo de datos
│   │   └── dataset.py             # Datasets de PALS
│   ├── evaluation/                 # Evaluación y visualización
│   │   └── visualizer.py          # Visualizador de resultados
│   └── inference/                  # Inferencia y predicción
└── scripts/                        # Scripts de entrenamiento
    ├── training/                   # Scripts de entrenamiento
    ├── calibration/               # Scripts de calibración
    ├── evaluation/                # Scripts de evaluación
    └── end_to_end/                # Scripts end-to-end

Módulos Principales

pals_calibration.models

• MultidimensionalIRTModel: Modelo principal para 4 competencias matemáticas
• SimpleIRTModel: Modelo IRT clásico unidimensional
• BaseIRTModel: Clase base con funcionalidades comunes

pals_calibration.training

• MultidimTrainer: Entrenador especializado para modelos multidimensionales
• SimpleTrainer: Entrenador para modelos unidimensionales
• Soporte para early stopping, regularización y checkpoints

pals_calibration.data

• PALSDataset: Manejo de datos de respuestas, preguntas y estudiantes
• Preprocesamiento automático y división train/val/test
• Integración con pesos BERTIN

pals_calibration.evaluation

• TrainingVisualizer: Visualización de métricas de entrenamiento
• Gráficos de calibración, curvas ROC, matrices de interacciones
• Reportes de evaluación automáticos

Entrenamiento

• Fecha: 2025-09-11T10:40:08.122694
• Dataset: v1.0
• Época de convergencia: 0
• Arquitectura: Simplified Enhanced IRT

Citación

@misc{pals-enhanced-irt-2024,
  title={PALS Simplified Enhanced IRT Model},
  author={PALS Team},
  year={2024},
  howpublished={\url{https://huggingface.co/ronsuez/pals-enhanced-irt-v1}},
  note={Multidimensional IRT model for mathematics assessment}
}

Licencia

MIT License - Ver archivo LICENSE para detalles.

Contacto

Para preguntas sobre el modelo o colaboraciones, contactar al equipo PALS.