Starter utilities for training, evaluating, and inspecting Named Entity Recognition (NER) models on UNER-style .iob2 data.
- Python >= 3.12
No third-party dependencies are required for utils.py — it only uses the standard library.
Utilities expect CoNLL-style, tab-separated .iob2 files:
# comment lines starting with '#' are ignored
1 To O
2 kendte O
3 russiske O
4 Andronik B-PER
5 Mirganjan I-PER
1 ...
- Columns:
token_id <TAB> token_form <TAB> label <TAB> [extra columns...] - Sentences are separated by blank lines.
- A line with fewer than 3 columns, or an empty label column, is treated as label
O.
| Function | Purpose |
|---|---|
parse_iob2_file(filepath) |
Parse an .iob2 file into a list of sentences, each a list of IOB2 labels (for scoring). |
parse_iob2_file_with_tokens(filepath) |
Same as above, but keeps (token, label) pairs per sentence (for inspecting examples). |
extract_entities(tags) |
Convert one sentence's IOB2 tags into a set of (entity_type, start, end) spans. |
entity_f1(gold_sentences, pred_sentences) |
Compute entity-level (span, exact-match) micro-averaged precision, recall, and F1 across a dataset. |
from utils import parse_iob2_file, parse_iob2_file_with_tokens, entity_f1
# For scoring: labels only
gold = parse_iob2_file("da_ddt-ud-test.iob2")
pred = parse_iob2_file("da_ddt-ud-test.predictions.iob2")
precision, recall, f1 = entity_f1(gold, pred)
print(f"P={precision:.3f} R={recall:.3f} F1={f1:.3f}")
# For inspection: tokens + labels together
sentences = parse_iob2_file_with_tokens("da_ddt-ud-test.iob2")
print(sentences[0][:5])
# [('To', 'O'), ('kendte', 'O'), ('russiske', 'O'), ('Andronik', 'B-PER'), ('Mirganjan', 'I-PER')]entity_f1 requires gold_sentences and pred_sentences to be aligned 1:1 (same order, same sentence boundaries). If the two inputs have different numbers of sentences, a UserWarning is raised and the extra sentences in the longer sequence are dropped.
See LICENSE.