TEC Calibration

The tec_calibration module implements the core scientific logic for estimating and removing instrumental biases from GNSS observations. The calibration process is based on the algorithm described by Ciraolo et al. (2007). To account for the magnetic control of the ionosphere, the module takes into account Modified Dip latitude (MoDip), which provides a more physically accurate representation of ionospheric structures than standard geographic latitude.

Key Stages

1. Arc identification & levelling: cycle slips and loss-of-lock events are detected to extract continuous observation "arcs"; phase measurements are then levelled to the (unambiguous) code measurements to reduce noise while maintaining continuity.
2. Bias estimation: a polynomial expansion in a MoDip/Longitude frame is evaluated and the resulting system is solved using via QR decomposition to separate the ionospheric signal from the combined satellite-receiver biases.
3. Calibrated output: estimated biases are removed to provide the calibrated slant (sTEC) and vertical (vTEC) TEC values.

---

API Reference

extract_arcs(df, ctx, threshold_abs=5.0, threshold_std=5.0, min_arc_length=30, max_gap=None, threshold_jump=10.0)

Extract continuous TEC arcs and fix GNSS linear combinations for multiple constellations.

The function performs the following steps: 1. Detects loss-of-lock events and cycle slips per constellation. 2. Identifies valid arcs, discarding short ones. 3. Removes cycle-slip jumps within valid arcs. 4. Corrects significant jumps between consecutive epochs. 5. Calculates arc-levelled GFLC values.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame containing GNSS observations.	required
ctx	GNSSContext	Execution context containing system configurations and frequency metadata.	required
threshold_abs	float	Absolute threshold for detecting cycle slips; default is 5.	5.0
threshold_std	float	Standard deviation multiplier threshold for cycle slips; default is 5.	5.0
min_arc_length	int	Minimum number of consecutive valid observations for an arc; default is 30.	30
max_gap	timedelta	Maximum allowed time gap before declaring Loss-of-Lock.	None
threshold_jump	float	Threshold for detecting significant jumps between epochs; default is 10.	10.0

Returns:

Type	Description
DataFrame	DataFrame with arc identifiers and levelled GFLC values.

calculate_tec(df, ctx, max_polynomial_degree=3, batch_size_epochs=30)

Compute slant and vertical TEC (sTEC, vTEC) after per-arc bias estimation.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame containing GNSS observations, including: - gflc_levelled: leveled sTEC measurements - id_arc_valid: valid arc identifiers - ele: satellite elevation angles	required
ctx	GNSSContext	Execution context containing receiver position and IPP height.	required
max_polynomial_degree	int	Maximum degree of polynomial expansion used in calibration.	3
batch_size_epochs	int	Number of epochs per batch for calibration.	30

Returns:

Type	Description
DataFrame	DataFrame with additional columns: - bias: estimated arc-level bias - stec: bias-corrected slant TEC - vtec: vertical TEC after mapping function correction

extract_modip(coords, year, coord_type)

Interpolate MoDip values for given ECEF or geodetic (longitude/latitude) coordinates. The function interpolates MoDip values from precomputed grids, if available.

Parameters:

Name	Type	Description	Default
coords	tuple, sequence, or np.ndarray	Input coordinates, in one of the following forms: - (lon, lat) tuple of arrays - (x, y, z) tuple of arrays - Sequence of (lon, lat) tuples - Sequence of (x, y, z) tuples - np.ndarray of shape (N, 2) or (N, 3)	required
year	int	Year for which the MoDip grid is used.	required
coord_type	Literal['ecef', 'geo']	Type of input coordinates: - "ecef" for ECEF coordinates. - "geo" for geographic coordinates; lon, lat expected.	required

Returns:

Type	Description
ndarray	Interpolated MoDip values for the specified coordinates