gpstec 1.0.0__py3-none-any.whl

gpstec/__init__.py

@@ -0,0 +1,7 @@
+"""gpstec: calibrated GPS total electron content from NovAtel GPStation-6 and other dual-frequency receivers.
+
+Copyright (c) 2026 Dipanjan Banerjee. See the LICENSE file for terms.
+"""
+__version__ = "1.0.0"
+__author__ = "Dipanjan Banerjee"
+__copyright__ = "Copyright (c) 2026 Dipanjan Banerjee"

gpstec/__main__.py

@@ -0,0 +1,112 @@
+"""Command line interface.
+
+  gpstec init                       write a station.toml template to edit
+  gpstec run -c station.toml -o results FILES...
+  gpstec install-convbin            build RTKLIB convbin (needed for .GPS input)
+  gpstec --version
+"""
+import argparse
+import glob
+import os
+import shutil
+import subprocess
+import sys
+from importlib import resources
+from pathlib import Path
+
+from . import __author__, __copyright__, __version__
+
+TEMPLATE = "station_template.toml"
+
+
+def _init(path, force=False):
+    path = Path(path)
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite).")
+        return 1
+    text = resources.files("gpstec").joinpath("data", TEMPLATE).read_text(encoding="utf-8")
+    path.write_text(text, encoding="utf-8")
+    print(f"Wrote {path}. Edit the [station] block (name, lat, lon, height, utc_offset_h), then run:")
+    print(f"  gpstec run -c {path} -o results  your_file.GPS")
+    return 0
+
+
+def _install_convbin(dest):
+    dest = Path(dest).expanduser()
+    dest.mkdir(parents=True, exist_ok=True)
+    for tool in ("git", "make", "gcc"):
+        if not shutil.which(tool):
+            print(f"'{tool}' is needed to build convbin. On Ubuntu/Debian: sudo apt install git build-essential")
+            return 1
+    src = Path.home() / ".cache" / "gpstec-rtklib"
+    if src.exists():
+        shutil.rmtree(src)
+    subprocess.run(["git", "clone", "--depth", "1", "https://github.com/rtklibexplorer/RTKLIB.git", str(src)],
+                   check=True)
+    build = src / "app" / "consapp" / "convbin" / "gcc"
+    subprocess.run(["make", "-C", str(build)], check=True)
+    shutil.copy2(build / "convbin", dest / "convbin")
+    print(f"convbin installed to {dest / 'convbin'}")
+    if str(dest) not in os.environ.get("PATH", "").split(os.pathsep):
+        print(f"Make sure {dest} is on your PATH, or set  convbin = \"{dest / 'convbin'}\"  in station.toml.")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="gpstec",
+        description="Calibrated GPS total electron content (TEC) from NovAtel GPStation-6 and other "
+                    "dual-frequency receivers.",
+        epilog=f"{__copyright__}. https://github.com/dipanjanbanerjee/gpstec",
+        formatter_class=argparse.RawTextHelpFormatter)
+    ap.add_argument("-V", "--version", action="version",
+                    version=f"gpstec {__version__}\n{__copyright__}\nAuthor: {__author__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("init", help="write a station.toml configuration template")
+    i.add_argument("path", nargs="?", default="station.toml")
+    i.add_argument("--force", action="store_true", help="overwrite an existing file")
+
+    c = sub.add_parser("install-convbin", help="download and build RTKLIB convbin (Linux/macOS)")
+    c.add_argument("--dest", default="~/.local/bin", help="where to put convbin (default ~/.local/bin)")
+
+    r = sub.add_parser("run", help="process .GPS receiver files or RINEX files")
+    r.add_argument("files", nargs="+", help=".GPS receiver files or RINEX observation files (wildcards OK)")
+    r.add_argument("-c", "--config", help="TOML config file (station position, settings)")
+    r.add_argument("-o", "--out", default="tec_output", help="output folder")
+    r.add_argument("--nav", help="navigation file (if not next to the observation file)")
+    r.add_argument("--sp3", nargs="*", help="precise orbit SP3 file(s) instead of broadcast")
+    r.add_argument("--dcb", nargs="*", help="CODE P1P2/P1C1 .DCB or Bias-SINEX files")
+    r.add_argument("--elev", type=float, help="elevation cut for VTEC output (default 50)")
+    r.add_argument("--rx-bias", help="receiver bias: lsq, minstd, gim or a number in TECU")
+    r.add_argument("--no-cmn", action="store_true", help="skip writing the large .Cmn-style file")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "init":
+        return _init(a.path, a.force)
+    if a.cmd == "install-convbin":
+        return _install_convbin(a.dest)
+
+    from . import config, pipeline          # heavy imports only when processing
+    print(f"gpstec {__version__}  ·  {__copyright__}")
+    station, settings = config.load(a.config)
+    if a.elev is not None:
+        settings.output_elevation = a.elev
+    if a.dcb:
+        settings.dcb_files = a.dcb
+        settings.sat_dcb = "file"
+    if a.rx_bias:
+        try:
+            settings.receiver_bias = float(a.rx_bias)
+        except ValueError:
+            settings.receiver_bias = a.rx_bias
+    files = []
+    for f in a.files:
+        files += sorted(glob.glob(f)) or [f]
+    pipeline.run([Path(f) for f in files], station, settings, a.out, nav=a.nav, sp3=a.sp3,
+                 write_cmn=not a.no_cmn)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gpstec/calibrate.py

@@ -0,0 +1,175 @@
+"""Removing the satellite and receiver code biases from leveled slant TEC.
+
+Convention: STEC = STEC_raw + B_sat[prn] + B_rx   (all in TECU)
+
+Satellite biases come from CODE DCB files when available, otherwise they are
+estimated from the data together with the receiver bias ("lsq").
+
+Receiver bias:
+  minstd  Pick the B_rx that makes the VTEC seen by different satellites at the
+          same moment agree best (smallest spread). This is the method used by
+          Gopi Seemala's GPS-TEC program (after Ma & Maruyama, 2003).
+  lsq     Fit STEC_raw = VTEC(t, ipp)/mf - B_sat - B_rx by least squares, with a
+          VTEC that is linear in pierce-point lat/lon in 15-minute blocks. Gives
+          satellite and receiver biases with no external files (sum of satellite
+          biases = 0, the same convention CODE uses).
+"""
+import numpy as np
+import pandas as pd
+from scipy import sparse
+from scipy.sparse.linalg import lsqr
+
+from .orbits import gps_seconds
+
+
+def apply_sat_bias(d, sat_bias):
+    d = d.copy()
+    d["b_sat"] = d["prn"].map(sat_bias).astype(float)
+    missing = sorted(d.loc[d["b_sat"].isna(), "prn"].unique())
+    if missing:
+        print(f"  warning: no satellite bias for PRN {missing}; those satellites are dropped")
+        d = d[d["b_sat"].notna()].copy()
+    d["stec_sat"] = d["stec_raw"] + d["b_sat"]
+    return d
+
+
+def _sample(d, el_min, step_s=30):
+    s = d[d["el"] >= el_min]
+    t = gps_seconds(s["time"].to_numpy())
+    return s[np.isclose(t % step_s, 0, atol=0.01)]
+
+
+def receiver_bias_minstd(d, el_min=30.0, step_s=30, search=(-150.0, 150.0)):
+    """Receiver bias (TECU) minimising the spread of simultaneous VTEC values."""
+    s = _sample(d, el_min, step_s)
+    if s.empty:
+        raise ValueError(f"No data above {el_min} deg elevation to estimate the receiver bias")
+    epoch = s["time"].to_numpy()
+    _, inv = np.unique(epoch, return_inverse=True)
+    stec = s["stec_sat"].to_numpy()
+    mf = s["mf"].to_numpy()
+    nep = inv.max() + 1
+    cnt = np.bincount(inv, minlength=nep)
+    ok = cnt[inv] >= 2
+
+    def cost(b):
+        v = (stec + b) * mf
+        m = np.bincount(inv, v, nep) / np.maximum(cnt, 1)
+        r = (v - m[inv]) ** 2
+        var = np.bincount(inv, np.where(ok, r, 0.0), nep) / np.maximum(cnt, 1)
+        return np.sqrt(var[cnt >= 2]).mean()
+
+    grid = np.arange(search[0], search[1] + 1e-9, 1.0)
+    c = np.array([cost(b) for b in grid])
+    b0 = grid[c.argmin()]
+    fine = np.arange(b0 - 1.0, b0 + 1.0 + 1e-9, 0.01)
+    cf = np.array([cost(b) for b in fine])
+    return float(fine[cf.argmin()]), float(cf.min())
+
+
+def sample_for_fit(d, el_min=30.0, step_s=30):
+    """The small subset of columns/rows the bias fit needs (to combine many days)."""
+    return _sample(d, el_min, step_s)[["time", "prn", "el", "mf", "ipp_lat", "ipp_lon", "stec_raw"]].copy()
+
+
+def biases_lsq(d, el_min=30.0, step_s=30, block_min=15.0, smooth=0.5, presampled=False):
+    """Joint least-squares estimate of satellite and receiver biases (TECU).
+
+    Returns (sat_bias dict, receiver_bias, rms of fit).
+    """
+    s = (d if presampled else _sample(d, el_min, step_s)).reset_index(drop=True)
+    if s.empty:
+        raise ValueError("No data for the bias fit")
+    t = gps_seconds(s["time"].to_numpy())
+    blk = ((t - t.min()) // (block_min * 60)).astype(int)
+    nb = blk.max() + 1
+    prns = np.sort(s["prn"].unique())
+    pidx = np.searchsorted(prns, s["prn"].to_numpy())
+    ns = len(prns)
+    lat0, lon0 = np.median(s["ipp_lat"]), np.median(s["ipp_lon"])
+    dlat = s["ipp_lat"].to_numpy() - lat0
+    dlon = s["ipp_lon"].to_numpy() - lon0
+    inv_mf = 1.0 / s["mf"].to_numpy()
+    y = s["stec_raw"].to_numpy()
+    n = len(s)
+    w = np.sin(np.radians(s["el"].to_numpy()))     # elevation weighting
+
+    # unknown layout: [a0 (nb), a1 (nb), a2 (nb), b_sat (ns), b_rx]
+    rows = np.arange(n)
+    cols, vals, rr = [], [], []
+    for off, coef in ((0, inv_mf), (nb, inv_mf * dlat), (2 * nb, inv_mf * dlon)):
+        rr.append(rows); cols.append(off + blk); vals.append(coef)
+    rr.append(rows); cols.append(3 * nb + pidx); vals.append(-np.ones(n))
+    rr.append(rows); cols.append(np.full(n, 3 * nb + ns)); vals.append(-np.ones(n))
+    nun = 3 * nb + ns + 1
+    A = sparse.csr_matrix((np.concatenate(vals) * np.tile(w, 5), (np.concatenate(rr), np.concatenate(cols))), shape=(n, nun))
+    yw = y * w
+
+    # constraints: sum of satellite biases = 0 (strong), smooth VTEC/gradients in time (weak)
+    extra_r, extra_c, extra_v, extra_y = [], [], [], []
+    r0 = 0
+    big = 1e3
+    extra_r += [r0] * ns; extra_c += list(range(3 * nb, 3 * nb + ns)); extra_v += [big] * ns; extra_y.append(0.0); r0 += 1
+    for off in (0, nb, 2 * nb):
+        for kk in range(nb - 1):
+            extra_r += [r0, r0]; extra_c += [off + kk, off + kk + 1]; extra_v += [smooth, -smooth]; extra_y.append(0.0); r0 += 1
+    C = sparse.csr_matrix((extra_v, (extra_r, extra_c)), shape=(r0, nun))
+    AA = sparse.vstack([A, C]).tocsr()
+    yy = np.concatenate([yw, extra_y])
+    sol = lsqr(AA, yy, atol=1e-12, btol=1e-12, iter_lim=20000)[0]
+    resid = A @ sol - yw
+    sat = {int(p): float(b) for p, b in zip(prns, sol[3 * nb:3 * nb + ns])}
+    return sat, float(sol[-1]), float(np.sqrt(np.mean((resid / w) ** 2)))
+
+
+def apply_receiver_bias(d, b_rx):
+    d = d.copy()
+    d["b_rx"] = b_rx
+    d["stec"] = d["stec_sat"] + b_rx
+    d["vtec"] = d["stec"] * d["mf"]
+    return d
+
+
+def receiver_bias_lsq_fixed_sats(d, sta_lat, sta_lon, el_min=20.0, step_s=30, block_min=15.0, smooth=0.5):
+    """Receiver bias (TECU) by least squares when satellite biases are already applied.
+
+    Fits stec_sat = VTEC(t, ipp)/mf - B_rx, with VTEC linear in pierce-point offset
+    in 15-minute blocks. Uses the change of the mapping factor with elevation to
+    separate B_rx from VTEC; best on night data, where gradients are weak.
+    """
+    s = _sample(d, el_min, step_s).reset_index(drop=True)
+    if len(s) < 50:
+        raise ValueError("Not enough data for the least-squares receiver bias")
+    t = gps_seconds(s["time"].to_numpy())
+    blk = ((t - t.min()) // (block_min * 60)).astype(int)
+    nb = blk.max() + 1
+    n = len(s)
+    r = np.arange(n)
+    inv = 1.0 / s["mf"].to_numpy()
+    dlat = s["ipp_lat"].to_numpy() - sta_lat
+    dlon = (s["ipp_lon"].to_numpy() - sta_lon) * np.cos(np.radians(sta_lat))
+    w = np.sin(np.radians(s["el"].to_numpy()))
+    rows = np.concatenate([r, r, r, r])
+    cols = np.concatenate([blk, nb + blk, 2 * nb + blk, np.full(n, 3 * nb)])
+    vals = np.concatenate([inv, inv * dlat, inv * dlon, -np.ones(n)]) * np.tile(w, 4)
+    nun = 3 * nb + 1
+    A = sparse.csr_matrix((vals, (rows, cols)), shape=(n, nun))
+    er, ec, ev = [], [], []
+    k = 0
+    for off in (0, nb, 2 * nb):
+        for j in range(nb - 1):
+            er += [k, k]; ec += [off + j, off + j + 1]; ev += [smooth, -smooth]; k += 1
+    C = sparse.csr_matrix((ev, (er, ec)), shape=(k, nun))
+    sol = lsqr(sparse.vstack([A, C]).tocsr(), np.r_[s["stec_sat"].to_numpy() * w, np.zeros(k)],
+               atol=1e-12, btol=1e-12, iter_lim=20000)[0]
+    return float(sol[-1])
+
+
+def receiver_bias_floor(d, el_min=10.0, pct=99.5):
+    """Smallest receiver bias that keeps (almost) every satellite's VTEC >= 0.
+
+    VTEC = (stec_sat + B_rx) * mf >= 0  <=>  B_rx >= -stec_sat. Using the 99.5th
+    percentile instead of the maximum ignores the noisiest 0.5 % of points.
+    """
+    s = d[d["el"] >= el_min]
+    return float(np.percentile(-s["stec_sat"].to_numpy(), pct)) if len(s) else -np.inf

gpstec/config.py

@@ -0,0 +1,85 @@
+"""Station and processing settings, loaded from a TOML file."""
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+try:
+    import tomllib
+except ImportError:          # Python < 3.11
+    import tomli as tomllib
+
+import numpy as np
+
+from .geometry import geodetic_to_ecef
+
+
+@dataclass
+class Station:
+    name: str = "stat"
+    lat: float = None             # degrees North   (required: the surveyed antenna position)
+    lon: float = None             # degrees East
+    height: float = 0.0           # metres above the WGS84 ellipsoid
+    utc_offset_h: float = 0.0     # for the local-time axis on plots (e.g. 5.5 for IST)
+
+    @property
+    def ecef(self):
+        return geodetic_to_ecef(self.lat, self.lon, self.height)
+
+
+@dataclass
+class Settings:
+    # geometry
+    shell_height_km: float = 350.0
+    # elevation limits (degrees)
+    mask_elevation: float = 10.0        # ignore anything lower, everywhere
+    level_elevation: float = 20.0       # phase-to-code levelling uses points above this
+    calib_elevation: float = 30.0       # receiver-bias estimation uses points above this
+    calib_night_lt: list = field(default_factory=lambda: [22.0, 6.0])  # local-time window for the
+                                        # receiver bias (quiet night: weak gradients); [] = whole day
+    output_elevation: float = 50.0      # VTEC products use points above this
+    # arcs
+    max_gap_s: float = 60.0
+    slip_threshold_m: float = 0.25
+    min_arc_s: float = 600.0
+    # signals
+    pair: str = "L1L2"
+    # biases
+    sat_dcb: str = "auto"               # "auto" | "file" | "estimate"
+    dcb_files: list = field(default_factory=list)   # CODE P1P2*.DCB / P1C1*.DCB (or .BSX)
+    dcb_dir: str = "dcb"                # cache for downloaded CODE files
+    receiver_bias: str = "lsq"          # "lsq" | "minstd" | "gim" | number in TECU
+    lsq_elevation: float = 20.0         # elevation cut-off for the least-squares receiver bias
+    receiver_bias_multiday: str = "per_day"  # "per_day" (each day on its own) | "median" over the run
+    enforce_nonnegative: bool = True    # raise the receiver bias if it would make VTEC negative
+    floor_percentile: float = 99.5      # ...ignoring the noisiest 0.5 % of points
+    gim: str = "auto"                   # CODE global ionosphere map as a reference: "auto" | "off"
+    gim_dir: str = "gim"
+    # daily products
+    bin_minutes: float = 1.0
+    clip_sigma: float = 2.0             # outlier clipping inside each bin
+    min_sats_per_bin: int = 1
+    smooth_knot_min: float = 60.0       # spacing of the smooth station-VTEC curve (minutes)
+    # figures
+    figure_formats: list = field(default_factory=lambda: ["png", "pdf"])  # also "svg", "eps", "tiff"
+    figure_dpi: int = 300               # raster resolution (PNG/TIFF)
+    figure_width_in: float = 7.2        # 7.2 in = full page width in most journals; 3.5 = one column
+    figure_titles: bool = True          # False: no title line (the caption goes in the paper)
+    # tools
+    convbin: str = "convbin"            # path to RTKLIB convbin(.exe)
+    convbin_format: str = "nov"         # NovAtel OEM6/OEM7 (GPStation-6)
+
+
+def load(path=None):
+    """Return (Station, Settings). Missing keys keep their defaults."""
+    st, se = Station(), Settings()
+    if path:
+        with open(path, "rb") as fh:
+            cfg = tomllib.load(fh)
+        for obj, sec in ((st, "station"), (se, "processing")):
+            known = {f.name for f in fields(obj)}
+            for key, val in cfg.get(sec, {}).items():
+                if key not in known:
+                    raise KeyError(f"Unknown setting [{sec}] {key} in {path}")
+                setattr(obj, key, val)
+    if st.lat is None or st.lon is None:
+        raise ValueError("The station position is not set. Run `gpstec init`, put your antenna's "
+                         "lat/lon/height in the [station] block of station.toml, and pass it with -c.")
+    return st, se

gpstec/constants.py

@@ -0,0 +1,24 @@
+"""Physical and GPS constants used across the package."""
+
+C = 299_792_458.0                 # speed of light (m/s)
+F1 = 1575.42e6                    # GPS L1 (Hz)
+F2 = 1227.60e6                    # GPS L2 (Hz)
+F5 = 1176.45e6                    # GPS L5 (Hz)
+LAMBDA1 = C / F1                  # L1 wavelength (m)
+LAMBDA2 = C / F2                  # L2 wavelength (m)
+LAMBDA5 = C / F5
+
+# 1 TECU = 1e16 electrons / m^2.  Ionospheric group delay on frequency f is
+# 40.3 * TEC / f^2 metres, so (P2 - P1) in metres converts to TECU with:
+K_L1L2 = F1**2 * F2**2 / (F1**2 - F2**2) / 40.3 / 1e16    # ~9.52 TECU per metre
+K_L1L5 = F1**2 * F5**2 / (F1**2 - F5**2) / 40.3 / 1e16    # ~7.76 TECU per metre
+TECU_PER_NS_L1L2 = K_L1L2 * C * 1e-9                      # ~2.85 TECU per ns of DCB
+
+# WGS-84
+WGS84_A = 6378137.0
+WGS84_F = 1 / 298.257223563
+WGS84_E2 = WGS84_F * (2 - WGS84_F)
+GM = 3.986005e14                  # IS-GPS-200 value
+OMEGA_E = 7.2921151467e-5         # Earth rotation rate (rad/s)
+
+RE_KM = 6371.0                    # mean Earth radius for the thin-shell model

gpstec/continuity.py

@@ -0,0 +1,97 @@
+"""Midnight continuity check between consecutive days.
+
+The receiver file of day X ends at 00:00:00 of day X+1 and the next file starts one
+second later, so the two files see the same satellites through the same patch of
+ionosphere at the same moment. The real VTEC cannot jump in one second, so any
+difference at midnight comes from the processing:
+
+  * the receiver bias, which each day estimates on its own, and
+  * the phase levelling of arcs that cross midnight, which is done separately in
+    each file with only part of the arc.
+
+For every satellite seen on both sides, each file's VTEC is fitted with a straight
+line over its last (or first) 10 minutes and evaluated at the boundary, and the
+two values are compared. The median over satellites is the "jump". The part that
+the receiver-bias difference explains is reported separately.
+"""
+import numpy as np
+import pandas as pd
+
+EDGE_MIN = 10.0
+MAX_GAP_S = 300.0
+
+
+def edges(d, el_min=30.0, edge_min=EDGE_MIN):
+    """Rows near the start and end of one file, kept for the boundary comparison."""
+    t0, t1 = d["time"].min(), d["time"].max()
+    w = pd.Timedelta(minutes=edge_min)
+    m = (d["el"] >= el_min) & d["vtec"].notna() & ((d["time"] <= t0 + w) | (d["time"] >= t1 - w))
+    cols = ["time", "prn", "el", "vtec", "stec", "arc"]
+    e = d.loc[m, [c for c in cols if c in d]].copy()
+    return {"start": t0, "end": t1, "rows": e}
+
+
+def _value_at(rows, t_ref):
+    """Linear fit of VTEC against time, evaluated at t_ref; None if too few points."""
+    if len(rows) < 20:
+        return None
+    x = (rows["time"] - t_ref).dt.total_seconds().to_numpy()
+    y = rows["vtec"].to_numpy()
+    if np.ptp(x) < 60:
+        return float(np.median(y))
+    a, b = np.polyfit(x, y, 1)
+    return float(b)
+
+
+def compare(prev, nxt, el_out, mf_out=0.9):
+    """Compare two consecutive files. ``prev``/``nxt`` are dicts with keys
+    edges (from :func:`edges`), b_rx, date_end_series, series (daily product DataFrames)."""
+    ea, eb = prev["edges"], nxt["edges"]
+    gap = (eb["start"] - ea["end"]).total_seconds()
+    if not (-3600 <= gap <= MAX_GAP_S):
+        return None
+    t_ref = ea["end"] + (eb["start"] - ea["end"]) / 2
+    w = pd.Timedelta(minutes=EDGE_MIN)
+    ra = ea["rows"][ea["rows"]["time"] >= ea["end"] - w]
+    rb = eb["rows"][eb["rows"]["time"] <= eb["start"] + w]
+    per = []
+    for prn in sorted(set(ra["prn"]) & set(rb["prn"])):
+        a, b = ra[ra["prn"] == prn], rb[rb["prn"] == prn]
+        va, vb = _value_at(a, t_ref), _value_at(b, t_ref)
+        if va is None or vb is None:
+            continue
+        el = float(np.median(np.r_[a["el"].to_numpy()[-5:], b["el"].to_numpy()[:5]]))
+        mf = float(np.median(np.r_[(a["vtec"] / a["stec"]).to_numpy()[-5:], (b["vtec"] / b["stec"]).to_numpy()[:5]]))
+        per.append({"prn": int(prn), "el": round(el, 1), "vtec_end_prev": round(va, 2),
+                    "vtec_start_next": round(vb, 2), "jump": round(vb - va, 2),
+                    "jump_from_rx_bias": round((nxt["b_rx"] - prev["b_rx"]) * mf, 2)})
+    per = pd.DataFrame(per)
+    res = {"boundary_ut": str(t_ref.floor("s")), "prev_date": prev["date"], "next_date": nxt["date"],
+           "file_gap_s": round(gap, 1), "n_sats_el30": int(len(per)),
+           "receiver_bias_prev": round(prev["b_rx"], 2), "receiver_bias_next": round(nxt["b_rx"], 2)}
+    if len(per):
+        hi = per[per["el"] >= el_out]
+        res["jump_median_el30"] = round(float(per["jump"].median()), 2)
+        res["jump_spread_el30"] = round(float(per["jump"].std(ddof=0)), 2) if len(per) > 1 else 0.0
+        res["n_sats_out"] = int(len(hi))
+        res["jump_median_out"] = round(float(hi["jump"].median()), 2) if len(hi) else None
+        res["jump_from_rx_bias"] = round(float(per["jump_from_rx_bias"].median()), 2)
+        res["jump_from_levelling"] = round(res["jump_median_el30"] - res["jump_from_rx_bias"], 2)
+    # smooth station curve: last value of day X vs first value of day X+1
+    sa, sb = prev["series"], nxt["series"]
+    if sa is not None and sb is not None:
+        va = sa.dropna(subset=["vtec_smooth"])
+        vb = sb.dropna(subset=["vtec_smooth"])
+        if len(va) and len(vb) and va["ut_hour"].iloc[-1] > 23.5 and vb["ut_hour"].iloc[0] < 0.5:
+            res["smooth_end_prev"] = round(float(va["vtec_smooth"].iloc[-1]), 2)
+            res["smooth_start_next"] = round(float(vb["vtec_smooth"].iloc[0]), 2)
+            res["smooth_jump"] = round(res["smooth_start_next"] - res["smooth_end_prev"], 2)
+    unc = [u for u in (prev.get("unc"), nxt.get("unc")) if u]
+    tol = max(1.0, float(np.hypot(*unc)) if len(unc) == 2 else (unc[0] if unc else 1.0))
+    res["tolerance_tecu"] = round(tol, 2)
+    j = res.get("jump_median_el30")
+    if j is None:
+        res["status"] = "no common satellites"
+    else:
+        res["status"] = "OK" if abs(j) <= tol else "CHECK"
+    return res, per

gpstec/convert.py

@@ -0,0 +1,77 @@
+"""Receiver .GPS (NovAtel binary) -> RINEX, using RTKLIB's convbin."""
+from pathlib import Path
+import shutil
+import subprocess
+
+import numpy as np
+
+
+def find_convbin(hint="convbin"):
+    local = Path.home() / ".local" / "bin" / "convbin"
+    for cand in (hint, "convbin", "convbin.exe", str(local)):
+        p = shutil.which(cand) or (cand if Path(cand).is_file() else None)
+        if p:
+            return p
+    raise FileNotFoundError(
+        "RTKLIB convbin was not found. Run `gpstec install-convbin`, or install RTKLIB yourself "
+        "and set `convbin = \"/path/to/convbin\"` under [processing] in your config file.")
+
+
+def gps_to_rinex(gps_file, out_dir, station, settings, freqs=None):
+    """Convert one receiver file to RINEX 2.11 obs + nav.
+
+    The station position from the config is written into the header
+    (APPROX POSITION XYZ), so the files are also safe to use in other programs.
+    Returns (obs_path, nav_path).
+    """
+    gps_file = Path(gps_file)
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    exe = find_convbin(settings.convbin)
+    x, y, z = station.ecef
+    stem = gps_file.stem
+    obs = out_dir / f"{stem}.obs"
+    nav = out_dir / f"{stem}.nav"
+    freqs = freqs or (3 if settings.pair == "L1L5" else 2)
+    cmd = [exe, "-r", settings.convbin_format, "-v", "2.11", "-f", str(freqs),
+           "-od", "-os", "-y", "R", "-y", "E", "-y", "J", "-y", "S", "-y", "C",
+           "-hm", station.name, "-hp", f"{x:.4f}/{y:.4f}/{z:.4f}",
+           "-o", str(obs), "-n", str(nav), str(gps_file)]
+    print("  " + " ".join(cmd))
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    if res.returncode != 0 or not obs.exists():
+        raise RuntimeError(f"convbin failed for {gps_file}:\n{res.stdout}\n{res.stderr}")
+    obs = rinex2_rename(obs, station.name)
+    if nav.exists():
+        new_nav = obs.with_name(obs.name[:-1] + "n")
+        if new_nav.exists():
+            new_nav.unlink()
+        nav = nav.rename(new_nav)
+    else:
+        nav = None
+    return obs, nav
+
+
+def rinex2_rename(path, site, kind="o"):
+    """Rename to the RINEX 2 short name ssssDDD0.YYo (what Gopi's software expects)."""
+    path = Path(path)
+    first = _first_obs_time(path)
+    if first is None:
+        return path
+    doy = (first.astype("datetime64[D]") - first.astype("datetime64[Y]")).astype(int) + 1
+    yy = first.astype("datetime64[Y]").astype(int) + 1970
+    new = path.with_name(f"{site[:4].lower():<4}{doy:03d}0.{yy % 100:02d}{kind}")
+    if new.exists():
+        new.unlink()
+    path.rename(new)
+    return new
+
+
+def _first_obs_time(path):
+    with open(path, errors="replace") as fh:
+        for ln in fh:
+            if "TIME OF FIRST OBS" in ln:
+                y, mo, d = ln[:6].strip(), ln[6:12].strip(), ln[12:18].strip()
+                return np.datetime64(f"{int(y):04d}-{int(mo):02d}-{int(d):02d}")
+            if "END OF HEADER" in ln:
+                return None

gpstec/data/station_template.toml

@@ -0,0 +1,54 @@
+# gpstec configuration file. Created by `gpstec init`; edit the [station] block for your receiver.
+# Every value is optional: anything left out keeps its default.
+
+[station]
+name = "skbu"
+lat = 23.3607          # degrees N   (the surveyed antenna position; never trust the RINEX header)
+lon = 86.3408          # degrees E
+height = 285.279       # metres (ellipsoidal)
+utc_offset_h = 5.5     # local time axis on plots (IST)
+
+[processing]
+shell_height_km = 350.0
+
+# Elevation limits (degrees)
+mask_elevation = 10.0      # data below this is ignored completely
+level_elevation = 20.0     # phase-to-code levelling uses points above this
+calib_elevation = 30.0     # receiver-bias estimation uses points above this
+calib_night_lt = [22.0, 6.0]   # ...and only this local-time window ([] = whole day)
+output_elevation = 50.0    # VTEC products (CSV, Std, plots) use satellites above this
+
+# Satellite biases:
+#   "auto"     use dcb_files if given, else download CODE monthly files into dcb_dir,
+#              else estimate them from the data (less accurate)
+#   "file"     require dcb_files
+#   "estimate" always estimate from the data
+sat_dcb = "auto"
+dcb_files = []             # e.g. ["dcb/P1P22212.DCB", "dcb/P1C12212.DCB"]
+dcb_dir = "dcb"
+
+# Receiver bias (night data only, each day on its own):
+#   "lsq"    least squares with north/east gradients (default; most stable on 25-26 Dec 2022)
+#   "minstd" minimum spread between satellites (Gopi-style; drifts with strong gradients)
+#   "gim"    match the CODE global ionosphere map;  or a fixed number in TECU
+receiver_bias = "lsq"
+lsq_elevation = 20.0
+receiver_bias_multiday = "per_day"    # each day calibrated on its own ("median" = one value per run)
+enforce_nonnegative = true          # never let the receiver bias make VTEC negative
+
+gim = "auto"               # CODE global ionosphere map as reference line + check ("off" to skip)
+gim_dir = "gim"
+
+bin_minutes = 1.0
+smooth_knot_min = 60.0     # smoothness of the station VTEC curve (smaller = more detail)
+clip_sigma = 2.0
+
+# Figures (publication quality: vector PDF + 300 dpi PNG by default)
+figure_formats = ["png", "pdf"]   # any of "png", "pdf", "svg", "eps", "tiff"
+figure_dpi = 300
+figure_width_in = 7.2      # 7.2 in = full page width; 3.5 in = one journal column
+figure_titles = true       # false = no title line (put the caption in the paper)
+
+# RTKLIB convbin, needed only for .GPS input (`gpstec install-convbin` builds it)
+convbin = "convbin"          # or a full path, e.g. "/home/you/.local/bin/convbin"
+convbin_format = "nov"     # NovAtel OEM6/OEM7 binary (GPStation-6)