feat: add dataset analysis

[leomaurodesenv]

🔍 Pull Request Review: Dataset Analysis Features

Overview

This PR introduces comprehensive dataset analysis capabilities with support for multiple QA datasets, configurable splits, and detailed statistical analysis. The changes span across dataset loading, analysis functions, and command-line interface improvements.

1. Well-Structured Dataset Architecture

• Clean abstraction: The AbstactDataset class provides a solid foundation with proper inheritance patterns
• Flexible split handling: Good implementation of DatasetSplit enum with train/validation/test options
• Consistent interface: All dataset classes follow the same pattern with _columns, _metadata, and _get_answers methods

2. Robust Analysis Functions

• Comprehensive metrics: Covers length distributions, question types, and dataset overview statistics
• WH-word analysis: Smart detection of question types using interrogative words
• Empty answer handling: Proper detection and filtering of questions without answers

3. Good Code Quality

• Type hints: Proper use of type annotations throughout
• Error handling: Graceful handling of missing columns and edge cases
• Documentation: Clear docstrings and comments explaining functionality

[leomaurodesenv]

Tests

➜  qasports-dataset-scripts git:(feat/qasports-analysis) ✗ uv run -m experiments.doc_reader --dataset QASports --sport RUGBY
Dataset: Dataset.QASports // Sport: rugby
Model: deepset/bert-base-uncased-squad2
Resolving data files: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 109.06it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 18236.10it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 17920.55it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 90200.09it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 83220.32it/s]
Resolving data files: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 142179.80it/s]
## QASports Dataset (validation, non-empty=True) ##
Columns: Index(['qa_id', 'question', 'answer', 'context', 'context_id', 'context_url',
       'context_title', 'context_categories'],
      dtype='object')
Rows: 84
Inferencing Samples: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:01<00:00,  1.10s/ Batches]
Inferencing Samples: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  3.14 Batches/s]
...
Inferencing Samples: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  2.94 Batches/s]
Inferencing Samples: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  3.08 Batches/s]
{'Reader': {'exact_match': 0.8690476190476191, 'f1': 0.9427746856318284, 'num_examples_for_eval': 84.0}}

➜  qasports-dataset-scripts git:(feat/qasports-analysis) ✗ uv run -m experiments.doc_retriever --dataset QASports --sport RUGBY
Dataset: Dataset.QASports // Sport: rugby
Model: DocRetriever.BM25 // Top-K: 1
Resolving data files: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 40.12it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 24679.64it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 21280.08it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 21013.55it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 22151.06it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 22086.91it/s]
## QASports Dataset (validation, non-empty=True) ##
Columns: Index(['qa_id', 'question', 'answer', 'context', 'context_id', 'context_url',
       'context_title', 'context_categories'],
      dtype='object')
Rows: 84
Updating BM25 representation...: 100%|████████████████████████████████████████████████████████████████████████████████████████████████| 79/79 [00:00<00:00, 72632.62 docs/s]
Retriever: <haystack.nodes.retriever.sparse.BM25Retriever object at 0x70aa0547fd00>
{'Retriever': {'recall_multi_hit': 0.9166666666666666, 'recall_single_hit': 0.9166666666666666, 'precision': 0.9166666666666666, 'map': 0.9166666666666666, 'mrr': 0.9166666666666666, 'ndcg': 0.9166666666666666}}

➜  qasports-dataset-scripts git:(feat/qasports-analysis) ✗ uv run -m experiments.dataset_analysis --dataset QASports --sport RUGBY
Dataset: Dataset.QASports // Sport: rugby // Split: train
Resolving data files: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 101.22it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 24056.81it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 21715.27it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 23444.96it/s]
Resolving data files: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 116025.01it/s]
Resolving data files: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████| 20/20 [00:00<00:00, 23510.67it/s]
## QASports Dataset (train, non-empty=False) ##
Columns: Index(['qa_id', 'question', 'answer', 'context', 'context_id', 'context_url',
       'context_title', 'context_categories'],
      dtype='object')
Rows: 927

🔍 Analyzing dataset...
Overall statistics
{'total_examples': 927, 'unique_contexts': 418, 'unique_questions': 924, 'questions_without_answers': 319, 'percentage_without_answers': 34.41208198489752}

Length distributions
{'context': {'count': 927, 'mean': 39.325782092772386, 'median': 42.0, 'min': 1, 'max': 53, 'std': 9.740849926477914}, 'question': {'count': 927, 'mean': 9.56957928802589, 'median': 9.0, 'min': 1, 'max': 26, 'std': 3.554364674205633}, 'answer': {'count': 927, 'mean': 1.3451995685005393, 'median': 1.0, 'min': 0, 'max': 13, 'std': 1.64796502214632, 'empty_count': 319, 'empty_percentage': 34.41208198489752}}

Question type analysis
{'who': {'count': 123, 'percentage': 13.268608414239482, 'empty_answers': 46, 'empty_percentage': 37.39837398373984}, 'when': {'count': 112, 'percentage': 12.081984897518879, 'empty_answers': 22, 'empty_percentage': 19.642857142857142}, 'how': {'count': 139, 'percentage': 14.994606256742179, 'empty_answers': 34, 'empty_percentage': 24.46043165467626}, 'what': {'count': 389, 'percentage': 41.963322545846815, 'empty_answers': 162, 'empty_percentage': 41.645244215938305}, 'where': {'count': 57, 'percentage': 6.148867313915858, 'empty_answers': 12, 'empty_percentage': 21.052631578947366}, 'none': {'count': 85, 'percentage': 9.169363538295578, 'empty_answers': 35, 'empty_percentage': 41.17647058823529}, 'which': {'count': 17, 'percentage': 1.8338727076591153, 'empty_answers': 5, 'empty_percentage': 29.411764705882355}, 'why': {'count': 5, 'percentage': 0.5393743257820928, 'empty_answers': 3, 'empty_percentage': 60.0}}