# 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

python

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

python

# 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

bash

# 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

python

# 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

bibtex

@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.