geopulse.io.iaga2002

IAGA-2002 magnetometer format parser.

IAGA-2002 is the standard geomagnetic observatory format used by INTERMAGNET and many observatories. Files have:

  • a fixed-width 12-line header (each line 69 chars, terminated with |),

  • optional #-prefixed comment lines,

  • one column-header line (also |-terminated),

  • data rows: YYYY-MM-DD HH:MM:SS.sss  DOY  <col1>  <col2>  <col3>  <col4>.

The header includes the IAGA station code, geodetic lat/lon, and a Reporting field naming the four data columns — typically XYZF (geographic X-north, Y-east, Z-down, total F, all in nT) or HDZF (horizontal, declination, vertical, total).

This module reads the file and returns raw arrays; the SI conversion and frame-standardisation (D → X, Y) happen in geopulse.sources.intermagnet.INTERMAGNETSource.

References

  • IAGA-2002 format specification, INTERMAGNET Technical Reference.

Functions

read_iaga2002(path)

Read an IAGA-2002 file.

Classes

Iaga2002File(station_code, latitude_deg, ...)

Parsed contents of a single IAGA-2002 file.
class geopulse.io.iaga2002.Iaga2002File(station_code, latitude_deg, longitude_deg, reporting, time_utc, col1_nT, col2_nT, col3_nT, col4_nT, header)[source]

Bases: object

Parsed contents of a single IAGA-2002 file.

Parameters:
station_code

3-letter IAGA observatory code (e.g. "OTT").

Type:

str

latitude_deg

Geodetic latitude, degrees north.

Type:

float

longitude_deg

Geodetic longitude, degrees east (0-360 in the file, normalised to [-180, 180] here).

Type:

float

reporting

4-character orientation string from the header (e.g. "XYZF").

Type:

str

time_utc

UNIX epoch seconds (UTC). Shape (n_samples,).

Type:

numpy.ndarray

col1_nT, col2_nT, col3_nT, col4_nT

The four data columns in nT (D columns remain in minutes of arc; the source adapter is responsible for angle interpretation). Sentinel values (99999, 88888) are replaced with NaN.

Type:

numpy.ndarray

header

Full raw header key/value pairs, keys lowercased and stripped.

Type:

dict

station_code: str
latitude_deg: float
longitude_deg: float
reporting: str
time_utc: ndarray
col1_nT: ndarray
col2_nT: ndarray
col3_nT: ndarray
col4_nT: ndarray
header: dict
geopulse.io.iaga2002.read_iaga2002(path)[source]

Read an IAGA-2002 file.

Parameters:

path (str | Path) – Path to the .iaga / .min / .sec file.

Return type:

Iaga2002File

Returns:

Iaga2002File – Parsed file contents. Component columns are in nT (with sentinels NaN’d); the reporting field tells you what the four columns actually represent (XYZF vs HDZF vs …).

Raises:

DataError – If the file is missing a required header field, has an unrecognised reporting orientation, or fails to parse.

Examples

>>> from geopulse.io.iaga2002 import read_iaga2002
>>> f = read_iaga2002("some_file.min")
>>> f.station_code
'OTT'