README.md

---
language: es
license: cc-by-4.0
tags:
  - spacy
  - token-classification
  - named-entity-recognition
  - spanish
  - music
  - digital-humanities
  - historical-text
  - bert
base_model: dccuchile/bert-base-spanish-wwm-cased
datasets:
  - custom
widget:
  - text: "Beethoven fue interpretado anoche por la Orquesta Nacional con María Barrientos como solista"
    example_title: "Ejemplo musical"
  - text: "La soprano Conchita Supervía actuó en el Teatro Real acompañada de la Banda Municipal"
    example_title: "Crónica de concierto"
model-index:
  - name: LexiMus-BETO-per-v1
    results:
      - task:
          type: token-classification
          name: Named Entity Recognition
        metrics:
          - type: precision
            value: 0.943
            name: Precision (validación humana)
---

# LexiMus-BETO-per-v1

Modelo NER especializado en la detección de **personas y agrupaciones musicales** en prensa musical española histórica (1918–1935), desarrollado en el marco del proyecto **LexiMus** (PID2022-139589NB-C33).

Basado en [BETO](https://huggingface.co/dccuchile/bert-base-spanish-wwm-cased) (`dccuchile/bert-base-spanish-wwm-cased`) y ajustado con spaCy 3 sobre un corpus de textos de *El Sol* y *ONDAS* (prensa musical española, 1918–1935).

---

## Entidades reconocidas

| Etiqueta | Descripción | Ejemplo |
|---|---|---|
| `COMPOSITOR` | Compositor de música | *Beethoven*, *Manuel de Falla*, *Wagner* |
| `INTERPRETE` | Intérprete instrumental | *Pablo Casals*, *Joaquín Turina* |
| `CANTANTE` | Cantante lírico o de cualquier género | *Conchita Supervía*, *Fleta* |
| `AGRUPACION` | Agrupación musical (orquesta, banda, coro, cuarteto...) | *Orquesta Filarmónica*, *Cuarteto Francés* |

---

## Rendimiento

### Precisión validada manualmente
Evaluación sobre **1.183 predicciones** revisadas por expertos humanos:

| Clase | TP | FP | Precisión |
|---|---|---|---|
| COMPOSITOR | ~318 | ~19 | ~94.4% |
| INTERPRETE | ~220 | ~17 | ~92.8% |
| CANTANTE | ~217 | ~24 | ~90.0% |
| AGRUPACION | ~293 | ~6 | ~98.0% |
| **GLOBAL** | **1.115** | **68** | **94.3%** |

> **Nota sobre F1:** La evaluación automática contra anotaciones gold parciales arroja F1 = 0.40, cifra que **subestima severamente** el rendimiento real del modelo. Las anotaciones de referencia solo marcan un subconjunto de las entidades presentes en cada texto (el corpus fue anotado parcialmente, no de forma exhaustiva). La precisión del 94.3% obtenida por revisión humana directa es la métrica representativa del sistema.

### Sistema completo: NER + Entity Ruler

El sistema combina el modelo transformer con un **Entity Ruler léxico** (1.035 patrones de nombres propios frecuentes en el corpus). El ruler actúa **sin sobreescribir** las predicciones del NER (`overwrite_ents=False`).

| Fuente | Entidades | % del total |
|---|---|---|
| NER (transformer) | 1.913 | 79.6% |
| Entity Ruler (léxico) | 490 | 20.4% |
| **Total** | **2.403** | **100%** |

---

## Uso

### Requisitos
```bash
pip install spacy>=3.8,<3.9
pip install spacy-transformers
```

### Carga del modelo completo (NER + Entity Ruler)

```python
import spacy
import csv
from pathlib import Path

def cargar_leximus(ruta_modelo: str, ruta_csv: str):
    """Carga el modelo LexiMus con Entity Ruler integrado."""
    nlp = spacy.load(ruta_modelo)

    # Reconstruir Entity Ruler desde el CSV de patrones
    if "entity_ruler" in nlp.component_names:
        nlp.remove_pipe("entity_ruler")

    patrones = []
    vistos = set()
    etiquetas_validas = {"COMPOSITOR", "INTERPRETE", "CANTANTE", "AGRUPACION"}

    with open(ruta_csv, encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for fila in reader:
            etq = fila["etiqueta"]
            if etq not in etiquetas_validas:
                continue
            textos_patron = {fila["texto"].strip()}
            if fila.get("variante_limpia", "").strip():
                textos_patron.add(fila["variante_limpia"].strip())
            notas = fila.get("notas", "")
            if "Apodo:" in notas:
                apodo = notas.split("Apodo:")[-1].split("|")[0].strip()
                if apodo:
                    textos_patron.add(apodo)
            for t in textos_patron:
                if not t or len(t) < 2:
                    continue
                clave = (t.lower(), etq)
                if clave in vistos:
                    continue
                vistos.add(clave)
                patrones.append({"label": etq, "pattern": t})

    ruler = nlp.add_pipe("entity_ruler", last=True, config={"overwrite_ents": False})
    ruler.add_patterns(patrones)
    print(f"Sistema listo: NER transformer + Entity Ruler ({len(ruler)} patrones)")
    return nlp


# Ejemplo de uso
nlp = cargar_leximus(
    ruta_modelo="LexiMus-BETO-per-v1",
    ruta_csv="entidades_ner_leximus.csv"
)

texto = "Anoche actuó la Orquesta Filarmónica de Madrid bajo la batuta de Bartolomé Pérez Casas, con el violinista Francesc Costa como solista."
doc = nlp(texto)

for ent in doc.ents:
    if ent.label_ in {"COMPOSITOR", "INTERPRETE", "CANTANTE", "AGRUPACION"}:
        print(f"  [{ent.label_}] {ent.text}")
```

Salida esperada:
```
Sistema listo: NER transformer + Entity Ruler (1035 patrones)
  [AGRUPACION] Orquesta Filarmónica de Madrid
  [INTERPRETE] Bartolomé Pérez Casas
  [INTERPRETE] Francesc Costa
```

---

## Archivos del repositorio

```
LexiMus-BETO-per-v1/
├── README.md                    # Este archivo
├── entidades_ner_leximus.csv    # Patrones del Entity Ruler (1.035 entradas)
├── cargar_modelo.py             # Script de ejemplo completo
└── [carpetas del modelo spaCy]  # config.cfg, meta.json, ner/, transformer/, etc.
```

---

## Datos de entrenamiento

- **Corpus**: Prensa musical española histórica — *El Sol* (1918–1935) y *ONDAS* (1925–1926)
- **Período**: 1918–1935
- **Idioma**: Español histórico (ortografía de época)
- **Anotación**: Manual + revisión asistida por LLM (Gemini)
- **Tamaño del conjunto de validación**: 1.200 textos (combinación de ejemplos positivos y negativos)

---

## Limitaciones

- Optimizado para **prensa musical española de los años 1918–1935**. El rendimiento puede degradarse en textos contemporáneos o de otros dominios.
- La distinción **INTERPRETE / CANTANTE** puede ser ambigua en contextos sin información de rol explícita.
- Nombres propios no incluidos en el Entity Ruler pueden no reconocerse si son poco frecuentes o presentan variantes ortográficas de época.
- El modelo no reconoce entidades fuera de las 4 clases definidas (lugares, obras, fechas, etc.).

---

## Cita

Si usas este modelo en tu investigación, por favor cita:

```bibtex
@misc{leximus-beto-per-v1,
  title        = {LexiMus-BETO-per-v1: NER para personas y agrupaciones musicales en prensa española histórica},
  author       = {{Grupo LexiMus, Universidad de Salamanca}},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/LexiMusUSAL/LexiMus-BETO-per-v1}},
  note         = {Proyecto PID2022-139589NB-C33, financiado por MCIN/AEI/10.13039/501100011033}
}
```

---

## Proyecto LexiMus

**LexiMus: Léxico y ontología de la música en español** (PID2022-139589NB-C33)  
Financiado por: Ministerio de Ciencia e Innovación / Agencia Estatal de Investigación  
Instituciones: Universidad de Salamanca · Instituto Complutense de Ciencias Musicales · Universidad de La Rioja

---

*Modelo entrenado con [spaCy](https://spacy.io) 3.8 y [spacy-transformers](https://github.com/explosion/spacy-transformers). Base: [BETO](https://huggingface.co/dccuchile/bert-base-spanish-wwm-cased).*