randonneuring-intelligence 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,9 @@
1
+ """Randonneuring Intelligence - Data processing and analysis for randonneuring cycling events"""
2
+
3
+ __version__ = "0.1.0"
4
+ __author__ = "Randonneuring Intelligence Team"
5
+
6
+ from . import audax_india
7
+ from . import lrm
8
+
9
+ __all__ = ["audax_india", "lrm", "__version__"]
@@ -0,0 +1,88 @@
1
+ """Audax India Data Processing Package"""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ from .data_loader import (
6
+ load_events,
7
+ load_event_details,
8
+ get_events_metadata,
9
+ get_event_details_metadata,
10
+ merge_events_with_details,
11
+ get_all_participants
12
+ )
13
+ from .filters import (
14
+ filter_events_by_year,
15
+ filter_events_by_club,
16
+ filter_events_by_location,
17
+ filter_events_by_state,
18
+ filter_events_by_distance,
19
+ filter_events_by_status,
20
+ filter_events_by_type,
21
+ filter_participants_by_name,
22
+ filter_participants_by_club,
23
+ filter_participants_by_result_status,
24
+ filter_participants_by_medal,
25
+ filter_participants_by_fee_paid
26
+ )
27
+ from .aggregations import (
28
+ get_event_statistics,
29
+ get_club_statistics,
30
+ get_participant_statistics,
31
+ get_completion_rate_by_distance,
32
+ get_state_statistics,
33
+ get_yearly_trends
34
+ )
35
+ from .queries import (
36
+ get_unique_clubs,
37
+ get_unique_locations,
38
+ get_unique_states,
39
+ get_unique_distances,
40
+ get_unique_years,
41
+ get_unique_participants,
42
+ get_unique_participant_clubs,
43
+ get_unique_rider_numbers
44
+ )
45
+
46
+ __all__ = [
47
+ # Data loaders
48
+ 'load_events',
49
+ 'load_event_details',
50
+ 'get_events_metadata',
51
+ 'get_event_details_metadata',
52
+ 'merge_events_with_details',
53
+ 'get_all_participants',
54
+
55
+ # Event filters
56
+ 'filter_events_by_year',
57
+ 'filter_events_by_club',
58
+ 'filter_events_by_location',
59
+ 'filter_events_by_state',
60
+ 'filter_events_by_distance',
61
+ 'filter_events_by_status',
62
+ 'filter_events_by_type',
63
+
64
+ # Participant filters
65
+ 'filter_participants_by_name',
66
+ 'filter_participants_by_club',
67
+ 'filter_participants_by_result_status',
68
+ 'filter_participants_by_medal',
69
+ 'filter_participants_by_fee_paid',
70
+
71
+ # Aggregations
72
+ 'get_event_statistics',
73
+ 'get_club_statistics',
74
+ 'get_participant_statistics',
75
+ 'get_completion_rate_by_distance',
76
+ 'get_state_statistics',
77
+ 'get_yearly_trends',
78
+
79
+ # Queries
80
+ 'get_unique_clubs',
81
+ 'get_unique_locations',
82
+ 'get_unique_states',
83
+ 'get_unique_distances',
84
+ 'get_unique_years',
85
+ 'get_unique_participants',
86
+ 'get_unique_participant_clubs',
87
+ 'get_unique_rider_numbers'
88
+ ]
@@ -0,0 +1,281 @@
1
+ """Aggregation and statistics functions for Audax India data"""
2
+
3
+ from typing import List, Dict, Any
4
+ from collections import defaultdict
5
+
6
+
7
+ def _parse_time_to_minutes(time_str: str) -> float:
8
+ """Convert time string like '09h 42m' to minutes (582)"""
9
+ if not time_str or time_str.upper() in ['DNS', 'DNF']:
10
+ return 0.0
11
+ try:
12
+ parts = time_str.lower().replace('h', ':').replace('m', '').strip().split(':')
13
+ hours = float(parts[0]) if parts[0] else 0.0
14
+ minutes = float(parts[1].strip()) if len(parts) > 1 and parts[1].strip() else 0.0
15
+ return hours * 60 + minutes
16
+ except (ValueError, IndexError):
17
+ return 0.0
18
+
19
+
20
+ def get_event_statistics(events: List[Dict[str, Any]], calendar_id: str = None) -> Dict[str, Any]:
21
+ """
22
+ Get statistics for a specific event or all events.
23
+
24
+ Args:
25
+ events: List of event dictionaries (preferably merged with details)
26
+ calendar_id: Specific calendar_id (optional)
27
+
28
+ Returns:
29
+ Dictionary with event statistics
30
+ """
31
+ if calendar_id:
32
+ event_list = [e for e in events if e.get('calendar_id') == calendar_id]
33
+ if not event_list:
34
+ return {'calendar_id': calendar_id, 'found': False}
35
+
36
+ event = event_list[0]
37
+ participants = event.get('participants', [])
38
+ completed = [p for p in participants if p.get('result', 'DNS') not in ['DNS', 'DNF']]
39
+
40
+ times = [_parse_time_to_minutes(p.get('result', '')) for p in completed if _parse_time_to_minutes(p.get('result', '')) > 0]
41
+
42
+ return {
43
+ 'calendar_id': calendar_id,
44
+ 'found': True,
45
+ 'year': event.get('year'),
46
+ 'event_date': event.get('event_date'),
47
+ 'distance': event.get('distance'),
48
+ 'club_name': event.get('club_name'),
49
+ 'location': event.get('location'),
50
+ 'state': event.get('state'),
51
+ 'status': event.get('status'),
52
+ 'total_participants': len(participants),
53
+ 'completed': len(completed),
54
+ 'dns': len([p for p in participants if p.get('result') == 'DNS']),
55
+ 'dnf': len([p for p in participants if p.get('result') == 'DNF']),
56
+ 'completion_rate': (len(completed) / len(participants) * 100) if participants else 0,
57
+ 'average_time_minutes': sum(times) / len(times) if times else 0,
58
+ 'fastest_time_minutes': min(times) if times else 0,
59
+ 'slowest_time_minutes': max(times) if times else 0
60
+ }
61
+ else:
62
+ # Summary of all events
63
+ total_events = len(events)
64
+ events_with_participants = [e for e in events if e.get('participants')]
65
+
66
+ return {
67
+ 'total_events': total_events,
68
+ 'events_with_participant_data': len(events_with_participants),
69
+ 'homologated': len([e for e in events if e.get('status') == 'Homologated']),
70
+ 'cancelled': len([e for e in events if e.get('status') == 'Cancelled'])
71
+ }
72
+
73
+
74
+ def get_club_statistics(events: List[Dict[str, Any]], club_name: str = None) -> Dict[str, Any]:
75
+ """
76
+ Get statistics for a specific club or all clubs.
77
+
78
+ Args:
79
+ events: List of event dictionaries
80
+ club_name: Name of the club (optional)
81
+
82
+ Returns:
83
+ Dictionary with club statistics
84
+ """
85
+ if club_name:
86
+ club_events = [e for e in events if club_name.lower() in e.get('club_name', '').lower()]
87
+
88
+ if not club_events:
89
+ return {'club': club_name, 'found': False}
90
+
91
+ distances = [int(e.get('distance', 0)) for e in club_events if e.get('distance')]
92
+ years = sorted(set(e.get('year') for e in club_events))
93
+
94
+ return {
95
+ 'club': club_events[0].get('club_name'),
96
+ 'found': True,
97
+ 'total_events': len(club_events),
98
+ 'years_active': years,
99
+ 'total_years': len(years),
100
+ 'distances_offered': sorted(set(distances)),
101
+ 'homologated': len([e for e in club_events if e.get('status') == 'Homologated']),
102
+ 'cancelled': len([e for e in club_events if e.get('status') == 'Cancelled']),
103
+ 'locations': list(set(e.get('location') for e in club_events if e.get('location')))
104
+ }
105
+ else:
106
+ # All clubs summary
107
+ club_data = defaultdict(list)
108
+ for e in events:
109
+ club = e.get('club_name', '')
110
+ if club:
111
+ club_data[club].append(e)
112
+
113
+ club_stats = []
114
+ for club, club_events in club_data.items():
115
+ club_stats.append({
116
+ 'club': club,
117
+ 'total_events': len(club_events),
118
+ 'homologated': len([e for e in club_events if e.get('status') == 'Homologated'])
119
+ })
120
+
121
+ return {
122
+ 'total_clubs': len(club_stats),
123
+ 'clubs': sorted(club_stats, key=lambda x: x['total_events'], reverse=True)
124
+ }
125
+
126
+
127
+ def get_participant_statistics(participants: List[Dict[str, Any]], name: str = None,
128
+ rider_number: str = None) -> Dict[str, Any]:
129
+ """
130
+ Get statistics for a specific participant.
131
+
132
+ Args:
133
+ participants: List of participant dictionaries (with calendar_id attached)
134
+ name: Participant name (optional)
135
+ rider_number: Rider number (optional)
136
+
137
+ Returns:
138
+ Dictionary with participant statistics
139
+ """
140
+ if rider_number:
141
+ rider_participations = [p for p in participants if p.get('rider_number') == rider_number]
142
+ elif name:
143
+ rider_participations = [p for p in participants if name.lower() in p.get('name', '').lower()]
144
+ else:
145
+ return {'error': 'Must provide either name or rider_number'}
146
+
147
+ if not rider_participations:
148
+ return {'found': False, 'query': name or rider_number}
149
+
150
+ completed = [p for p in rider_participations if p.get('result', 'DNS') not in ['DNS', 'DNF']]
151
+ times = [_parse_time_to_minutes(p.get('result', '')) for p in completed if _parse_time_to_minutes(p.get('result', '')) > 0]
152
+
153
+ return {
154
+ 'found': True,
155
+ 'name': rider_participations[0].get('name'),
156
+ 'rider_number': rider_participations[0].get('rider_number'),
157
+ 'club': rider_participations[0].get('club'),
158
+ 'total_events': len(rider_participations),
159
+ 'completed': len(completed),
160
+ 'dns': len([p for p in rider_participations if p.get('result') == 'DNS']),
161
+ 'dnf': len([p for p in rider_participations if p.get('result') == 'DNF']),
162
+ 'completion_rate': (len(completed) / len(rider_participations) * 100) if rider_participations else 0,
163
+ 'medals': len([p for p in rider_participations if p.get('medal')]),
164
+ 'average_time_minutes': sum(times) / len(times) if times else 0,
165
+ 'fastest_time_minutes': min(times) if times else 0,
166
+ 'slowest_time_minutes': max(times) if times else 0,
167
+ 'participations': rider_participations
168
+ }
169
+
170
+
171
+ def get_completion_rate_by_distance(events: List[Dict[str, Any]]) -> Dict[str, Any]:
172
+ """
173
+ Get completion rates grouped by distance.
174
+
175
+ Args:
176
+ events: List of event dictionaries (with participants)
177
+
178
+ Returns:
179
+ Dictionary with completion rates by distance
180
+ """
181
+ distance_data = defaultdict(lambda: {'total': 0, 'completed': 0, 'dns': 0, 'dnf': 0})
182
+
183
+ for event in events:
184
+ distance = event.get('distance', 'Unknown')
185
+ participants = event.get('participants', [])
186
+
187
+ for p in participants:
188
+ distance_data[distance]['total'] += 1
189
+ result = p.get('result', 'DNS')
190
+ if result == 'DNS':
191
+ distance_data[distance]['dns'] += 1
192
+ elif result == 'DNF':
193
+ distance_data[distance]['dnf'] += 1
194
+ else:
195
+ distance_data[distance]['completed'] += 1
196
+
197
+ stats = []
198
+ for distance, data in distance_data.items():
199
+ completion_rate = (data['completed'] / data['total'] * 100) if data['total'] > 0 else 0
200
+ stats.append({
201
+ 'distance': distance,
202
+ 'total_participants': data['total'],
203
+ 'completed': data['completed'],
204
+ 'dns': data['dns'],
205
+ 'dnf': data['dnf'],
206
+ 'completion_rate': completion_rate
207
+ })
208
+
209
+ return {
210
+ 'statistics': sorted(stats, key=lambda x: int(x['distance']) if x['distance'].isdigit() else 0)
211
+ }
212
+
213
+
214
+ def get_state_statistics(events: List[Dict[str, Any]]) -> Dict[str, Any]:
215
+ """
216
+ Get event statistics grouped by state.
217
+
218
+ Args:
219
+ events: List of event dictionaries
220
+
221
+ Returns:
222
+ Dictionary with statistics by state
223
+ """
224
+ state_data = defaultdict(lambda: {'events': 0, 'clubs': set()})
225
+
226
+ for event in events:
227
+ state = event.get('state', 'Unknown')
228
+ if state:
229
+ state_data[state]['events'] += 1
230
+ club = event.get('club_name')
231
+ if club:
232
+ state_data[state]['clubs'].add(club)
233
+
234
+ stats = []
235
+ for state, data in state_data.items():
236
+ stats.append({
237
+ 'state': state,
238
+ 'total_events': data['events'],
239
+ 'unique_clubs': len(data['clubs'])
240
+ })
241
+
242
+ return {
243
+ 'total_states': len(stats),
244
+ 'statistics': sorted(stats, key=lambda x: x['total_events'], reverse=True)
245
+ }
246
+
247
+
248
+ def get_yearly_trends(events: List[Dict[str, Any]]) -> Dict[str, Any]:
249
+ """
250
+ Get yearly event trends.
251
+
252
+ Args:
253
+ events: List of event dictionaries
254
+
255
+ Returns:
256
+ Dictionary with yearly statistics
257
+ """
258
+ year_data = defaultdict(lambda: {'total': 0, 'homologated': 0, 'cancelled': 0})
259
+
260
+ for event in events:
261
+ year = event.get('year', 'Unknown')
262
+ year_data[year]['total'] += 1
263
+
264
+ status = event.get('status', '')
265
+ if status == 'Homologated':
266
+ year_data[year]['homologated'] += 1
267
+ elif status == 'Cancelled':
268
+ year_data[year]['cancelled'] += 1
269
+
270
+ stats = []
271
+ for year, data in year_data.items():
272
+ stats.append({
273
+ 'year': year,
274
+ 'total_events': data['total'],
275
+ 'homologated': data['homologated'],
276
+ 'cancelled': data['cancelled']
277
+ })
278
+
279
+ return {
280
+ 'statistics': sorted(stats, key=lambda x: x['year'])
281
+ }
@@ -0,0 +1,163 @@
1
+ """Data loading utilities for Audax India data"""
2
+
3
+ import json
4
+ from typing import Dict, List, Any, Optional
5
+ from pathlib import Path
6
+
7
+
8
+ def load_events(file_path: str) -> List[Dict[str, Any]]:
9
+ """
10
+ Load Audax India events data from JSON file.
11
+
12
+ Args:
13
+ file_path: Path to the events.json file
14
+
15
+ Returns:
16
+ List of event dictionaries
17
+
18
+ Raises:
19
+ FileNotFoundError: If the file doesn't exist
20
+ json.JSONDecodeError: If the file is not valid JSON
21
+ """
22
+ path = Path(file_path)
23
+ if not path.exists():
24
+ raise FileNotFoundError(f"Events file not found: {file_path}")
25
+
26
+ with open(path, 'r', encoding='utf-8') as f:
27
+ data = json.load(f)
28
+
29
+ return data.get('records', [])
30
+
31
+
32
+ def load_event_details(file_path: str) -> List[Dict[str, Any]]:
33
+ """
34
+ Load Audax India event details data from JSON file.
35
+
36
+ Args:
37
+ file_path: Path to the event_details.json file
38
+
39
+ Returns:
40
+ List of event detail dictionaries (with participants)
41
+
42
+ Raises:
43
+ FileNotFoundError: If the file doesn't exist
44
+ json.JSONDecodeError: If the file is not valid JSON
45
+ """
46
+ path = Path(file_path)
47
+ if not path.exists():
48
+ raise FileNotFoundError(f"Event details file not found: {file_path}")
49
+
50
+ with open(path, 'r', encoding='utf-8') as f:
51
+ data = json.load(f)
52
+
53
+ return data.get('events', [])
54
+
55
+
56
+ def get_events_metadata(file_path: str) -> Dict[str, Any]:
57
+ """
58
+ Get metadata from events JSON file.
59
+
60
+ Args:
61
+ file_path: Path to the events.json file
62
+
63
+ Returns:
64
+ Dictionary containing source, last_updated, and record_count
65
+ """
66
+ path = Path(file_path)
67
+ if not path.exists():
68
+ raise FileNotFoundError(f"Events file not found: {file_path}")
69
+
70
+ with open(path, 'r', encoding='utf-8') as f:
71
+ data = json.load(f)
72
+
73
+ return {
74
+ 'source': data.get('source'),
75
+ 'last_updated': data.get('last_updated'),
76
+ 'record_count': data.get('record_count')
77
+ }
78
+
79
+
80
+ def get_event_details_metadata(file_path: str) -> Dict[str, Any]:
81
+ """
82
+ Get metadata from event details JSON file.
83
+
84
+ Args:
85
+ file_path: Path to the event_details.json file
86
+
87
+ Returns:
88
+ Dictionary containing source, last_updated, and total_events
89
+ """
90
+ path = Path(file_path)
91
+ if not path.exists():
92
+ raise FileNotFoundError(f"Event details file not found: {file_path}")
93
+
94
+ with open(path, 'r', encoding='utf-8') as f:
95
+ data = json.load(f)
96
+
97
+ return {
98
+ 'source': data.get('source'),
99
+ 'last_updated': data.get('last_updated'),
100
+ 'total_events': data.get('total_events')
101
+ }
102
+
103
+
104
+ def merge_events_with_details(events: List[Dict[str, Any]],
105
+ event_details: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
106
+ """
107
+ Merge events with their detailed information (including participants).
108
+
109
+ Args:
110
+ events: List of event dictionaries from events.json
111
+ event_details: List of event detail dictionaries from event_details.json
112
+
113
+ Returns:
114
+ List of merged event dictionaries with details and participants
115
+ """
116
+ # Create a lookup dictionary for event details by calendar_id
117
+ details_lookup = {detail['calendar_id']: detail for detail in event_details}
118
+
119
+ merged = []
120
+ for event in events:
121
+ calendar_id = event.get('calendar_id')
122
+ merged_event = event.copy()
123
+
124
+ # Add details if available
125
+ if calendar_id in details_lookup:
126
+ detail = details_lookup[calendar_id]
127
+ merged_event['description'] = detail.get('description', '')
128
+ merged_event['participants'] = detail.get('participants', [])
129
+ merged_event['scraped_at'] = detail.get('scraped_at', '')
130
+ merged_event['has_details'] = True
131
+ else:
132
+ merged_event['description'] = ''
133
+ merged_event['participants'] = []
134
+ merged_event['scraped_at'] = ''
135
+ merged_event['has_details'] = False
136
+
137
+ merged.append(merged_event)
138
+
139
+ return merged
140
+
141
+
142
+ def get_all_participants(event_details: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
143
+ """
144
+ Extract all participants from event details with event context.
145
+
146
+ Args:
147
+ event_details: List of event detail dictionaries
148
+
149
+ Returns:
150
+ List of participant dictionaries with calendar_id attached
151
+ """
152
+ all_participants = []
153
+
154
+ for event in event_details:
155
+ calendar_id = event.get('calendar_id')
156
+ participants = event.get('participants', [])
157
+
158
+ for participant in participants:
159
+ participant_with_event = participant.copy()
160
+ participant_with_event['calendar_id'] = calendar_id
161
+ all_participants.append(participant_with_event)
162
+
163
+ return all_participants