swx-advisories 0.2.0__tar.gz
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.
- swx_advisories-0.2.0/.gitignore +46 -0
- swx_advisories-0.2.0/.gitlab-ci.yml +41 -0
- swx_advisories-0.2.0/CHANGELOG.md +37 -0
- swx_advisories-0.2.0/PKG-INFO +470 -0
- swx_advisories-0.2.0/README.md +441 -0
- swx_advisories-0.2.0/pyproject.toml +65 -0
- swx_advisories-0.2.0/src/swx_advisories/__init__.py +81 -0
- swx_advisories-0.2.0/src/swx_advisories/adapters/__init__.py +19 -0
- swx_advisories-0.2.0/src/swx_advisories/adapters/dataframe.py +431 -0
- swx_advisories-0.2.0/src/swx_advisories/fetchers/__init__.py +14 -0
- swx_advisories-0.2.0/src/swx_advisories/fetchers/base.py +66 -0
- swx_advisories-0.2.0/src/swx_advisories/fetchers/icao.py +161 -0
- swx_advisories-0.2.0/src/swx_advisories/fetchers/noaa.py +748 -0
- swx_advisories-0.2.0/src/swx_advisories/models/__init__.py +35 -0
- swx_advisories-0.2.0/src/swx_advisories/models/advisory.py +246 -0
- swx_advisories-0.2.0/src/swx_advisories/models/enums.py +136 -0
- swx_advisories-0.2.0/src/swx_advisories/models/location.py +128 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/__init__.py +11 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/icao/__init__.py +17 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/icao/event_builder.py +229 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/icao/location_parser.py +284 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/icao/text_parser.py +474 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/noaa/__init__.py +7 -0
- swx_advisories-0.2.0/src/swx_advisories/parsers/noaa/parser.py +494 -0
- swx_advisories-0.2.0/tests/conftest.py +83 -0
- swx_advisories-0.2.0/tests/fixtures/noaa_alerts_sample.json +1 -0
- swx_advisories-0.2.0/tests/fixtures/sample_icao_advisories.txt +631 -0
- swx_advisories-0.2.0/tests/test_adapters.py +316 -0
- swx_advisories-0.2.0/tests/test_fetchers.py +215 -0
- swx_advisories-0.2.0/tests/test_icao_parser.py +198 -0
- swx_advisories-0.2.0/tests/test_noaa_parser.py +239 -0
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
develop-eggs/
|
|
9
|
+
dist/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
|
|
23
|
+
# Virtual environments
|
|
24
|
+
.env
|
|
25
|
+
.venv
|
|
26
|
+
env/
|
|
27
|
+
venv/
|
|
28
|
+
ENV/
|
|
29
|
+
|
|
30
|
+
# IDE
|
|
31
|
+
.idea/
|
|
32
|
+
.vscode/
|
|
33
|
+
*.swp
|
|
34
|
+
*.swo
|
|
35
|
+
*~
|
|
36
|
+
|
|
37
|
+
# Testing
|
|
38
|
+
.pytest_cache/
|
|
39
|
+
.coverage
|
|
40
|
+
htmlcov/
|
|
41
|
+
.tox/
|
|
42
|
+
.nox/
|
|
43
|
+
|
|
44
|
+
# OS
|
|
45
|
+
.DS_Store
|
|
46
|
+
Thumbs.db
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
stages:
|
|
2
|
+
- test
|
|
3
|
+
- build
|
|
4
|
+
- publish
|
|
5
|
+
|
|
6
|
+
# Run tests on all pushes and merge requests
|
|
7
|
+
test:
|
|
8
|
+
stage: test
|
|
9
|
+
script:
|
|
10
|
+
- python3 -m pip install -e .[dev]
|
|
11
|
+
- python3 -m pytest tests/ -v --tb=short
|
|
12
|
+
rules:
|
|
13
|
+
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
14
|
+
- if: $CI_COMMIT_BRANCH
|
|
15
|
+
|
|
16
|
+
# Build package on tags
|
|
17
|
+
build:
|
|
18
|
+
stage: build
|
|
19
|
+
script:
|
|
20
|
+
- python3 -m pip install build
|
|
21
|
+
- python3 -m build
|
|
22
|
+
artifacts:
|
|
23
|
+
paths:
|
|
24
|
+
- dist/
|
|
25
|
+
expire_in: 1 week
|
|
26
|
+
rules:
|
|
27
|
+
- if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
|
|
28
|
+
|
|
29
|
+
# Publish to PyPI on version tags
|
|
30
|
+
publish-pypi:
|
|
31
|
+
stage: publish
|
|
32
|
+
script:
|
|
33
|
+
- python3 -m pip install twine
|
|
34
|
+
- python3 -m twine upload dist/*
|
|
35
|
+
dependencies:
|
|
36
|
+
- build
|
|
37
|
+
rules:
|
|
38
|
+
- if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
|
|
39
|
+
variables:
|
|
40
|
+
TWINE_USERNAME: __token__
|
|
41
|
+
TWINE_PASSWORD: $PYPI_TOKEN
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.2.0] - 2025-01-26
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- `FetchResult.events` property for ICAO fetcher - events are now built automatically during `fetch()` and available via `result.events`
|
|
12
|
+
- `build_events` parameter to `ICAOFetcher.fetch()` and `from_text()` to optionally disable event building
|
|
13
|
+
- `message_code` field to NOAA advisories (e.g., "ALTK06", "WATA50")
|
|
14
|
+
- `original_text` field to preserve raw advisory text
|
|
15
|
+
- `NOAAArchiveFetcher` for fetching from NOAA HTML and FTP archives
|
|
16
|
+
- Progress callbacks for long-running fetch operations
|
|
17
|
+
- All datetimes are now timezone-aware (UTC)
|
|
18
|
+
- Comprehensive documentation in README
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
- ICAO events are now built eagerly during `fetch()` instead of requiring separate `fetch_events()` call
|
|
22
|
+
- `ICAOEventBuilder` is no longer part of the public API (use `result.events` instead)
|
|
23
|
+
|
|
24
|
+
### Removed
|
|
25
|
+
- `ICAOFetcher.fetch_events()` method (use `result.events` instead)
|
|
26
|
+
- `ICAOFetcher.build_events()` public method (now private `_build_events()`)
|
|
27
|
+
|
|
28
|
+
## [0.1.0] - 2025-01-20
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
- Initial release
|
|
32
|
+
- ICAO advisory parsing (fnxx01/fnxx02 files)
|
|
33
|
+
- NOAA alert parsing from SWPC API
|
|
34
|
+
- Event chain building for ICAO advisories
|
|
35
|
+
- DataFrame adapters (flat, timeline, HAPI formats)
|
|
36
|
+
- Support for latitude bands and polygon coordinates
|
|
37
|
+
- G/S/R scale extraction for NOAA alerts
|
|
@@ -0,0 +1,470 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: swx-advisories
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Parse and process space weather advisories from ICAO and NOAA/SWPC
|
|
5
|
+
Project-URL: Homepage, https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories
|
|
6
|
+
Project-URL: Repository, https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories
|
|
7
|
+
Author-email: KNMI <eelco.doornbos@knmi.nl>
|
|
8
|
+
License-Expression: Apache-2.0
|
|
9
|
+
Keywords: ICAO,NOAA,SWPC,advisories,alerts,aviation,space-weather
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Requires-Dist: httpx>=0.25
|
|
21
|
+
Requires-Dist: pandas>=2.0
|
|
22
|
+
Requires-Dist: pydantic>=2.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: respx>=0.20; extra == 'dev'
|
|
27
|
+
Requires-Dist: ruff>=0.1; extra == 'dev'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# swx-advisories
|
|
31
|
+
|
|
32
|
+
A Python package for parsing and analyzing space weather advisories from ICAO and NOAA/SWPC sources.
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
- **ICAO Advisory Parsing**: Parse ICAO space weather advisories (fnxx01/fnxx02 files) with support for:
|
|
37
|
+
- Blank-line and ZCZC/NNNN delimited formats
|
|
38
|
+
- Latitude bands (HNH, MNH, EQN, EQS, MSH, HSH) and polygon coordinates
|
|
39
|
+
- Event chain building via NR RPLC linking
|
|
40
|
+
- HF COM and GNSS effect types with MOD/SEV severity
|
|
41
|
+
|
|
42
|
+
- **NOAA Alert Parsing**: Parse NOAA Space Weather Prediction Center alerts with:
|
|
43
|
+
- Live API fetching from services.swpc.noaa.gov
|
|
44
|
+
- G/S/R scale extraction (geomagnetic, solar radiation, radio blackout)
|
|
45
|
+
- Message type classification (ALERT, WARNING, WATCH, SUMMARY)
|
|
46
|
+
- K-index, X-ray class, and proton flux metrics
|
|
47
|
+
|
|
48
|
+
- **DataFrame Adapters**: Convert advisories to pandas DataFrames in multiple formats:
|
|
49
|
+
- Flat format (one row per advisory/event)
|
|
50
|
+
- Timeline format (time-indexed for visualization)
|
|
51
|
+
- HAPI format (Heliophysics API compatible)
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install swx-advisories
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or install from source:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git clone https://gitlab.com/KNMI-OSS/spaceweather/swx-advisories.git
|
|
63
|
+
cd swx-advisories
|
|
64
|
+
pip install -e .
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
### ICAO Advisories
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from swx_advisories import ICAOFetcher, to_dataframe
|
|
73
|
+
|
|
74
|
+
# Load advisories from a file or directory
|
|
75
|
+
fetcher = ICAOFetcher("/path/to/advisories/")
|
|
76
|
+
result = fetcher.fetch()
|
|
77
|
+
|
|
78
|
+
# Access advisories and events directly from the result
|
|
79
|
+
for advisory in result.advisories:
|
|
80
|
+
print(f"{advisory.advisory_id}: {advisory.effect}")
|
|
81
|
+
|
|
82
|
+
for event in result.events:
|
|
83
|
+
print(f"{event.event_id}: {event.effect} ({event.peak_severity})")
|
|
84
|
+
print(f" Duration: {event.duration}")
|
|
85
|
+
print(f" Advisories: {event.num_advisories}")
|
|
86
|
+
|
|
87
|
+
# Convert to DataFrames
|
|
88
|
+
df_advisories = to_dataframe(result.advisories)
|
|
89
|
+
df_events = to_dataframe(result.events)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### NOAA Alerts
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from swx_advisories import NOAAFetcher
|
|
96
|
+
|
|
97
|
+
# Fetch from live NOAA API
|
|
98
|
+
fetcher = NOAAFetcher()
|
|
99
|
+
result = fetcher.fetch()
|
|
100
|
+
|
|
101
|
+
for alert in result:
|
|
102
|
+
print(f"{alert.advisory_id}: {alert.event_type.value}")
|
|
103
|
+
print(f" Scale: {alert.noaa_scale}")
|
|
104
|
+
print(f" Severity: {alert.severity}")
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Convert to DataFrame
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from swx_advisories import ICAOFetcher, to_dataframe
|
|
111
|
+
|
|
112
|
+
fetcher = ICAOFetcher("/path/to/advisories/")
|
|
113
|
+
result = fetcher.fetch()
|
|
114
|
+
|
|
115
|
+
# Get pandas DataFrames
|
|
116
|
+
df_advisories = to_dataframe(result.advisories, format="flat")
|
|
117
|
+
df_events = to_dataframe(result.events, format="flat")
|
|
118
|
+
print(df_events[["event_id", "effect", "peak_severity", "duration_hours"]])
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## ICAO Advisories
|
|
122
|
+
|
|
123
|
+
ICAO space weather advisories are issued by designated Space Weather Centers (SWXCs) to warn aviation of space weather impacts on HF communications and GNSS navigation.
|
|
124
|
+
|
|
125
|
+
### Fetching Advisories
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from swx_advisories import ICAOFetcher
|
|
129
|
+
|
|
130
|
+
# From a single file
|
|
131
|
+
fetcher = ICAOFetcher("/path/to/fnxx01_advisory.txt")
|
|
132
|
+
result = fetcher.fetch()
|
|
133
|
+
|
|
134
|
+
# From a directory (searches for fnxx01*.txt and fnxx02*.txt)
|
|
135
|
+
fetcher = ICAOFetcher("/path/to/advisory_directory/")
|
|
136
|
+
result = fetcher.fetch()
|
|
137
|
+
|
|
138
|
+
# Access advisories
|
|
139
|
+
for advisory in result:
|
|
140
|
+
print(f"{advisory.advisory_id}: {advisory.effect} - {advisory.severity}")
|
|
141
|
+
|
|
142
|
+
# Check for errors
|
|
143
|
+
if not result.success:
|
|
144
|
+
print(f"Errors: {result.errors}")
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Building Event Chains
|
|
148
|
+
|
|
149
|
+
Advisories are linked via the `NR RPLC` field. The fetcher automatically builds these into event chains:
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
from swx_advisories import ICAOFetcher
|
|
153
|
+
|
|
154
|
+
fetcher = ICAOFetcher("/path/to/advisories/")
|
|
155
|
+
result = fetcher.fetch()
|
|
156
|
+
|
|
157
|
+
# Events are automatically built and available on result.events
|
|
158
|
+
for event in result.events:
|
|
159
|
+
print(f"\nEvent: {event.event_id}")
|
|
160
|
+
print(f" Effect: {event.effect}")
|
|
161
|
+
print(f" Peak severity: {event.peak_severity}")
|
|
162
|
+
print(f" Start: {event.issue_start}")
|
|
163
|
+
print(f" End: {event.issue_end}")
|
|
164
|
+
print(f" Duration: {event.duration}")
|
|
165
|
+
print(f" Centers: {', '.join(event.centers)}")
|
|
166
|
+
print(f" Advisories in chain: {event.num_advisories}")
|
|
167
|
+
|
|
168
|
+
# Skip event building if not needed
|
|
169
|
+
result = fetcher.fetch(build_events=False)
|
|
170
|
+
assert result.events is None
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Advisory Structure
|
|
174
|
+
|
|
175
|
+
Each `ICAOAdvisory` contains:
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
advisory.advisory_id # e.g., "2026/0042"
|
|
179
|
+
advisory.center # e.g., "PECASUS", "ACFJ"
|
|
180
|
+
advisory.effect # "HF COM" or "GNSS"
|
|
181
|
+
advisory.severity # "MOD", "SEV", or None
|
|
182
|
+
advisory.issue_time # datetime
|
|
183
|
+
advisory.observation # TemporalObservation with time and location
|
|
184
|
+
advisory.forecasts # List of 4 Forecast objects (+6h, +12h, +18h, +24h)
|
|
185
|
+
advisory.replaces_id # ID of advisory this replaces, or None if opening
|
|
186
|
+
advisory.is_opening # True if this starts a new event chain
|
|
187
|
+
advisory.remark # Free-text remarks
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Parsing Raw Text
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from swx_advisories import ICAOFetcher
|
|
194
|
+
|
|
195
|
+
text = """FNXX01 EFKL 201549
|
|
196
|
+
SWX ADVISORY
|
|
197
|
+
DTG: 20260120/1549Z
|
|
198
|
+
SWXC: PECASUS
|
|
199
|
+
SWX EFFECT: GNSS
|
|
200
|
+
ADVISORY NR: 2026/99
|
|
201
|
+
OBS SWX: 20/1542Z SEV N55 E055 - N85 E055 - N85 E005 - N55 E005 - N55 E055
|
|
202
|
+
FCST SWX +6 HR: 20/2200Z NOT AVBL
|
|
203
|
+
FCST SWX +12 HR: 21/0400Z NOT AVBL
|
|
204
|
+
FCST SWX +18 HR: 21/1000Z NOT AVBL
|
|
205
|
+
FCST SWX +24 HR: 21/1600Z NOT AVBL
|
|
206
|
+
RMK: SPACE WEATHER EVENT IN PROGRESS
|
|
207
|
+
NXT ADVISORY: NO FURTHER ADVISORIES=
|
|
208
|
+
"""
|
|
209
|
+
|
|
210
|
+
result = ICAOFetcher.from_text(text)
|
|
211
|
+
for adv in result:
|
|
212
|
+
print(f"{adv.advisory_id}: {adv.effect}")
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## NOAA Alerts
|
|
216
|
+
|
|
217
|
+
NOAA Space Weather Prediction Center (SWPC) issues alerts, warnings, and watches for space weather events using the G/S/R scale system.
|
|
218
|
+
|
|
219
|
+
### Fetching from API
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
from swx_advisories import NOAAFetcher
|
|
223
|
+
|
|
224
|
+
# Fetch all recent alerts from NOAA API
|
|
225
|
+
fetcher = NOAAFetcher()
|
|
226
|
+
result = fetcher.fetch()
|
|
227
|
+
|
|
228
|
+
print(f"Fetched {result.count} alerts")
|
|
229
|
+
for alert in result:
|
|
230
|
+
print(f"{alert.advisory_id}: {alert.event_type.value} ({alert.noaa_scale})")
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Fetching from Local File
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
from swx_advisories import NOAAFetcher
|
|
237
|
+
|
|
238
|
+
# Load from a local JSON file (same format as NOAA API)
|
|
239
|
+
fetcher = NOAAFetcher(from_file="/path/to/alerts.json")
|
|
240
|
+
result = fetcher.fetch()
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### Filtering Alerts
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
from swx_advisories import NOAAFetcher, EventType, MessageType
|
|
247
|
+
|
|
248
|
+
fetcher = NOAAFetcher()
|
|
249
|
+
|
|
250
|
+
# Filter by event type
|
|
251
|
+
geomag = fetcher.fetch_by_type(EventType.GEOMAGNETIC_STORM)
|
|
252
|
+
radio = fetcher.fetch_by_type(EventType.RADIO_BLACKOUT)
|
|
253
|
+
|
|
254
|
+
# Filter by message type
|
|
255
|
+
alerts = fetcher.fetch_active_alerts() # ALERT messages only
|
|
256
|
+
warnings = fetcher.fetch_warnings() # WARNING messages only
|
|
257
|
+
watches = fetcher.fetch_watches() # WATCH messages only
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### Alert Structure
|
|
261
|
+
|
|
262
|
+
Each `SpaceWeatherAdvisory` contains:
|
|
263
|
+
|
|
264
|
+
```python
|
|
265
|
+
alert.advisory_id # e.g., "ALTK06-690"
|
|
266
|
+
alert.event_type # EventType enum (GEOMAGNETIC_STORM, RADIO_BLACKOUT, etc.)
|
|
267
|
+
alert.message_type # MessageType enum (ALERT, WARNING, WATCH, SUMMARY)
|
|
268
|
+
alert.severity # Severity enum (MINOR, MODERATE, SEVERE, EXTREME)
|
|
269
|
+
alert.noaa_scale # e.g., "G2", "S1", "R3"
|
|
270
|
+
alert.issue_time # datetime
|
|
271
|
+
alert.begin_time # datetime (if available)
|
|
272
|
+
alert.end_time # datetime (if available)
|
|
273
|
+
alert.short_description # Brief description of the event
|
|
274
|
+
alert.potential_impacts # Description of potential impacts
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
### NOAA Scales
|
|
278
|
+
|
|
279
|
+
The package extracts NOAA space weather scales:
|
|
280
|
+
|
|
281
|
+
| Scale | Type | Levels |
|
|
282
|
+
|-------|------|--------|
|
|
283
|
+
| G | Geomagnetic Storm | G1 (Minor) to G5 (Extreme) |
|
|
284
|
+
| S | Solar Radiation Storm | S1 (Minor) to S5 (Extreme) |
|
|
285
|
+
| R | Radio Blackout | R1 (Minor) to R5 (Extreme) |
|
|
286
|
+
|
|
287
|
+
## DataFrame Adapters
|
|
288
|
+
|
|
289
|
+
Convert advisories and events to pandas DataFrames for analysis and visualization.
|
|
290
|
+
|
|
291
|
+
### Unified Interface
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
from swx_advisories import ICAOFetcher, NOAAFetcher, to_dataframe
|
|
295
|
+
|
|
296
|
+
# ICAO advisories and events to DataFrame
|
|
297
|
+
icao = ICAOFetcher("/path/to/advisories/")
|
|
298
|
+
result = icao.fetch()
|
|
299
|
+
df_advisories = to_dataframe(result.advisories, format="flat")
|
|
300
|
+
df_events = to_dataframe(result.events, format="flat")
|
|
301
|
+
|
|
302
|
+
# NOAA alerts to DataFrame
|
|
303
|
+
noaa = NOAAFetcher()
|
|
304
|
+
alerts = noaa.fetch().advisories
|
|
305
|
+
df = to_dataframe(alerts, format="flat")
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Output Formats
|
|
309
|
+
|
|
310
|
+
**Flat format** - One row per advisory or event:
|
|
311
|
+
|
|
312
|
+
```python
|
|
313
|
+
from swx_advisories import icao_advisories_to_dataframe, icao_events_to_dataframe
|
|
314
|
+
|
|
315
|
+
# Advisories DataFrame
|
|
316
|
+
df = icao_advisories_to_dataframe(advisories)
|
|
317
|
+
# Columns: advisory_id, center, effect, severity, issue_time, obs_time,
|
|
318
|
+
# lat_min, lat_max, lon_min, lon_max, replaces_id, ...
|
|
319
|
+
|
|
320
|
+
# Events DataFrame
|
|
321
|
+
df = icao_events_to_dataframe(events)
|
|
322
|
+
# Columns: event_id, effect, peak_severity, num_advisories, duration_hours,
|
|
323
|
+
# issue_start, issue_end, centers, ...
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
**Timeline format** - Time-indexed for visualization:
|
|
327
|
+
|
|
328
|
+
```python
|
|
329
|
+
from swx_advisories.adapters.dataframe import icao_timeline_dataframe
|
|
330
|
+
|
|
331
|
+
df = icao_timeline_dataframe(events)
|
|
332
|
+
# Columns: time, event_id, effect, severity, is_start, is_end
|
|
333
|
+
|
|
334
|
+
# With resampling to regular intervals
|
|
335
|
+
df = icao_timeline_dataframe(events, resample="1h")
|
|
336
|
+
# Columns: time, event_id, effect, severity, is_active
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**HAPI format** - Heliophysics API compatible:
|
|
340
|
+
|
|
341
|
+
```python
|
|
342
|
+
from swx_advisories.adapters.dataframe import to_hapi_format
|
|
343
|
+
|
|
344
|
+
df = to_hapi_format(events)
|
|
345
|
+
# Time-indexed DataFrame pivoted by event type
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### NOAA DataFrames
|
|
349
|
+
|
|
350
|
+
```python
|
|
351
|
+
from swx_advisories import noaa_alerts_to_dataframe
|
|
352
|
+
from swx_advisories.adapters.dataframe import noaa_timeline_dataframe
|
|
353
|
+
|
|
354
|
+
# Flat format
|
|
355
|
+
df = noaa_alerts_to_dataframe(alerts)
|
|
356
|
+
# Columns: advisory_id, event_type, message_type, severity, noaa_scale,
|
|
357
|
+
# issue_time, begin_time, end_time, short_description, ...
|
|
358
|
+
|
|
359
|
+
# Timeline format
|
|
360
|
+
df = noaa_timeline_dataframe(alerts)
|
|
361
|
+
# Columns: time, advisory_id, event_type, severity, noaa_scale, is_start, is_end
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
## Data Models
|
|
365
|
+
|
|
366
|
+
### Enums
|
|
367
|
+
|
|
368
|
+
```python
|
|
369
|
+
from swx_advisories import EventType, MessageType, Severity, Source
|
|
370
|
+
|
|
371
|
+
# Event types
|
|
372
|
+
EventType.HF_BLACKOUT # ICAO HF COM
|
|
373
|
+
EventType.GNSS_DEGRADATION # ICAO GNSS
|
|
374
|
+
EventType.GEOMAGNETIC_STORM # NOAA G-scale
|
|
375
|
+
EventType.SOLAR_RADIATION_STORM # NOAA S-scale
|
|
376
|
+
EventType.RADIO_BLACKOUT # NOAA R-scale
|
|
377
|
+
EventType.SOLAR_FLARE
|
|
378
|
+
EventType.CME
|
|
379
|
+
|
|
380
|
+
# Message types (NOAA)
|
|
381
|
+
MessageType.ALERT
|
|
382
|
+
MessageType.WARNING
|
|
383
|
+
MessageType.WATCH
|
|
384
|
+
MessageType.SUMMARY
|
|
385
|
+
|
|
386
|
+
# Severity levels
|
|
387
|
+
Severity.MINOR
|
|
388
|
+
Severity.MODERATE
|
|
389
|
+
Severity.SEVERE
|
|
390
|
+
Severity.EXTREME
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### Location Models
|
|
394
|
+
|
|
395
|
+
```python
|
|
396
|
+
from swx_advisories import GeographicRegion, LatitudeBand
|
|
397
|
+
|
|
398
|
+
# Latitude bands used in ICAO advisories
|
|
399
|
+
LatitudeBand.HNH # High Northern Hemisphere (60-90N)
|
|
400
|
+
LatitudeBand.MNH # Middle Northern Hemisphere (30-60N)
|
|
401
|
+
LatitudeBand.EQN # Equatorial Northern (0-30N)
|
|
402
|
+
LatitudeBand.EQS # Equatorial Southern (0-30S)
|
|
403
|
+
LatitudeBand.MSH # Middle Southern Hemisphere (30-60S)
|
|
404
|
+
LatitudeBand.HSH # High Southern Hemisphere (60-90S)
|
|
405
|
+
|
|
406
|
+
# Geographic region with bounds
|
|
407
|
+
region = GeographicRegion(
|
|
408
|
+
lat_min=-90, lat_max=90,
|
|
409
|
+
lon_min=-180, lon_max=180,
|
|
410
|
+
text="Global coverage"
|
|
411
|
+
)
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
## API Reference
|
|
415
|
+
|
|
416
|
+
### Fetchers
|
|
417
|
+
|
|
418
|
+
| Class | Description |
|
|
419
|
+
|-------|-------------|
|
|
420
|
+
| `ICAOFetcher(path)` | Load ICAO advisories from file or directory |
|
|
421
|
+
| `NOAAFetcher(from_file=None)` | Fetch NOAA alerts from API or local file |
|
|
422
|
+
| `FetchResult` | Container with advisories, metadata, and errors |
|
|
423
|
+
|
|
424
|
+
### Parsers
|
|
425
|
+
|
|
426
|
+
| Class | Description |
|
|
427
|
+
|-------|-------------|
|
|
428
|
+
| `ICAOTextParser` | Parse raw ICAO advisory text |
|
|
429
|
+
| `NOAAParser` | Parse NOAA JSON alert data |
|
|
430
|
+
|
|
431
|
+
### Adapters
|
|
432
|
+
|
|
433
|
+
| Function | Description |
|
|
434
|
+
|----------|-------------|
|
|
435
|
+
| `to_dataframe(data, format)` | Auto-detect and convert to DataFrame |
|
|
436
|
+
| `icao_advisories_to_dataframe(advisories)` | ICAO advisories to flat DataFrame |
|
|
437
|
+
| `icao_events_to_dataframe(events)` | ICAO events to flat DataFrame |
|
|
438
|
+
| `icao_timeline_dataframe(events, resample)` | ICAO events to timeline DataFrame |
|
|
439
|
+
| `noaa_alerts_to_dataframe(alerts)` | NOAA alerts to flat DataFrame |
|
|
440
|
+
| `noaa_timeline_dataframe(alerts)` | NOAA alerts to timeline DataFrame |
|
|
441
|
+
| `to_hapi_format(data)` | Convert to HAPI-compatible format |
|
|
442
|
+
|
|
443
|
+
## Development
|
|
444
|
+
|
|
445
|
+
### Running Tests
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
# Install dev dependencies
|
|
449
|
+
pip install -e ".[dev]"
|
|
450
|
+
|
|
451
|
+
# Run tests
|
|
452
|
+
pytest tests/ -v
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### Test Coverage
|
|
456
|
+
|
|
457
|
+
The package includes 96 tests covering:
|
|
458
|
+
- ICAO text parsing and event building
|
|
459
|
+
- NOAA message parsing and alert extraction
|
|
460
|
+
- Fetcher functionality
|
|
461
|
+
- DataFrame adapter conversions
|
|
462
|
+
|
|
463
|
+
## License
|
|
464
|
+
|
|
465
|
+
MIT License - see LICENSE file for details.
|
|
466
|
+
|
|
467
|
+
## Acknowledgments
|
|
468
|
+
|
|
469
|
+
- ICAO for the space weather advisory format specification
|
|
470
|
+
- NOAA Space Weather Prediction Center for the alerts API
|