D3VILAni/event-period-ner-bert

Event-Period NER BERT Model

This model extracts events (spike/dip) and time periods (months, quarters, years) from natural language queries.

Model Description

• Model Type: BERT for Token Classification
• Base Model: bert-base-cased
• Training Data: 15,000 synthetic examples
• Labels: 5 classes (O, B-EVENT_SPIKE, B-EVENT_DIP, B-PERIOD, I-PERIOD)
• Test Accuracy: 99.97%

Intended Use

This model is designed to extract structured information from business analytics queries:

• Event types: spike, rise, surge, dip, drop, decline, etc.
• Time periods: February, Dec 2024, Q1, 2025-03, etc.
• Transitions: "from June to July", "between Q1 to Q2"

Usage

from transformers import pipeline

# Load the model
ner = pipeline(
    "token-classification",
    model="D3VILAni/event-period-ner-bert",
    aggregation_strategy="simple"
)

# Extract events and periods
result = ner("spike in December 2024")

# Output:
# [
#   {'word': 'spike', 'entity_group': 'EVENT_SPIKE', 'score': 0.98},
#   {'word': 'December 2024', 'entity_group': 'PERIOD', 'score': 0.96}
# ]

Supported Query Patterns

Single Events

• "spike in February"
• "dip in December 2024"
• "growth in Q1"

Transitions

• "rise from June to July"
• "decline from March 2024 to April 2025"
• "dip between August to September"

Multiple Events

• "spike in Feb, dip in June"
• "rise from Jan to Feb, drop in March"

No Event Word

• "from February to March" → Extracts periods only

Labels

Label	Description	Example
O	Outside (irrelevant tokens)	"in", "from", "to"
B-EVENT_SPIKE	Positive event	spike, rise, surge, jump, increase, growth
B-EVENT_DIP	Negative event	dip, drop, decline, decrease, fall, down
B-PERIOD	Beginning of time period	February, Q1, 2024
I-PERIOD	Inside multi-token period	In "December 2024", "2024" is I-PERIOD

Training Details

• Training Data: 15,000 examples across 12 template categories
• Train/Val/Test Split: 70% / 15% / 15%
• Epochs: 4
• Batch Size: 16
• Learning Rate: 2e-5
• Optimizer: AdamW with warmup

Performance

Overall Metrics

• Test Accuracy: 99.97%

Per-Label Performance

• O: 99.94%
• B-EVENT_SPIKE: 100.00%
• B-EVENT_DIP: 99.92%
• B-PERIOD: 100.00%
• I-PERIOD: 100.00%

Limitations

• Event vocabulary: Model is trained on specific spike/dip synonyms. May not generalize to very different terminology.
• Year formats: Best with standard formats (2024, '24). Less reliable with unusual formats.
• Business context: Extracts text as-written. Quarter expansion (Q1 → Jan/Feb/Mar) requires post-processing.

Post-Processing

For production use, implement post-processing to:

1. Normalize periods: "Feb" → "February", "'24" → "2024"
2. Expand quarters: "Q1" → ["January", "February", "March"]
3. Infer years: "December to January" → detect year boundary crossing
4. Resolve relative periods: "last month" → actual month name

Citation

@misc{event-period-ner-bert,
  author = {Your Name},
  title = {{Event-Period NER BERT Model}},
  year = {2025},
  publisher = {{Hugging Face}},
  url = {{https://huggingface.co/{username}/{CONFIG['repo_name']}}}
}

Model Card Contact

For questions or feedback, please open an issue on the model repository.