geopulse.sources.supermag

SuperMAG CSV / ASCII loader.

SuperMAG (https://supermag.jhuapl.edu) provides ground-magnetometer data from a global network of observatories in a consistent frame (baseline- subtracted N/E/Z, geographic components in nT).

Their common CSV export has:

  • #-prefixed comment lines at the top (metadata),

  • one header row naming columns: at minimum Date_UTC, IAGA, N, E, Z (may also include GEOLAT, GEOLON, MAGLAT, MAGLON, MLT, SZA, ...),

  • one row per (station, timestamp).

If the file contains multiple stations, a specific one can be selected by passing iaga= or station_id= at load time; otherwise the first station encountered is used.

References

  • Gjerloev, J. W. (2012). The SuperMAG data processing technique. Journal of Geophysical Research: Space Physics, 117(A9).

Classes

SuperMAGSource(file_path[, iaga])

Loader for SuperMAG station CSV data.
class geopulse.sources.supermag.SuperMAGSource(file_path, iaga=None)[source]

Bases: BFieldSource

Loader for SuperMAG station CSV data.

Parameters:

  • file_path (str) – Path to the SuperMAG-format CSV file.

  • iaga (str | None) – IAGA station code to select when the file contains multiple stations. Case-insensitive. If None, uses the first station encountered.

Examples

>>> src = SuperMAGSource("supermag_may2024.csv", iaga="OTT")
>>> b = src.load(start_s=0, end_s=86400)
>>> b.station_id
'OTT'
load(start_s=-inf, end_s=inf, dt_s=1.0, station_id='')[source]

Load a SuperMAG CSV file into a standardised BFieldTimeSeries.

Parameters:

  • start_s (float) – Time window in UNIX epoch seconds (UTC). Defaults are open.

  • end_s (float) – Time window in UNIX epoch seconds (UTC). Defaults are open.

  • dt_s (float) – Ignored — the file’s native sampling rate is used.

  • station_id (str) – Override for the returned station_id field. If empty, the IAGA code found in the file is used.

Return type:

BFieldTimeSeries

Returns:

BFieldTimeSeries – N/E/Z channels mapped directly to Bx (north) / By (east) / Bz (down), converted from nT to Tesla.

Raises:

DataError – If the file is missing required columns or contains no rows for the selected station in the requested window.