gpstec 1.0.0__tar.gz

gpstec-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dipanjan Banerjee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpstec-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: gpstec
+Version: 1.0.0
+Summary: Calibrated GPS total electron content (TEC) from NovAtel GPStation-6 and other dual-frequency receivers, with elevation cut-off and publication-quality plots
+Author: Dipanjan Banerjee
+Maintainer: Dipanjan Banerjee
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dipanjanbanerjee/gpstec
+Project-URL: Source, https://github.com/dipanjanbanerjee/gpstec
+Project-URL: Issues, https://github.com/dipanjanbanerjee/gpstec/issues
+Keywords: GPS,GNSS,TEC,VTEC,ionosphere,GPStation-6,NovAtel,RINEX,DCB,space weather,equatorial ionization anomaly
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: unlzw3>=0.2
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# gpstec
+
+**Calibrated GPS total electron content (TEC) from NovAtel GPStation-6 and other dual-frequency receivers.**
+
+[![tests](https://github.com/dipanjanbanerjee/gpstec/actions/workflows/tests.yml/badge.svg)](https://github.com/dipanjanbanerjee/gpstec/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/gpstec.svg)](https://pypi.org/project/gpstec/)
+
+Website: https://dipanjanbanerjee.github.io/gpstec/
+
+gpstec turns a raw GPStation-6 `.GPS` file (or any RINEX 2/3 observation file) into calibrated slant and vertical TEC, with a user-chosen elevation cut-off. It writes daily data files and publication-quality figures in one command:
+
+```
+gpstec run -c station.toml -o results  2242_0_00_skbu.GPS
+```
+
+![Daily vertical TEC at SKBU, 25 December 2022](docs/images/daily_vtec.png)
+
+## Why
+
+Many GPStation-6 users go through the chain `.GPS` → RTKLIB → RINEX → a closed calibration program → `.Cmn` files. That chain has three problems:
+
+- **Wrong station position.** RTKCONV 2.4.2 writes latitude, longitude and height into the `APPROX POSITION XYZ` header field, which expects Earth-centred coordinates. A program that trusts the header then places the station near the centre of the Earth, so every elevation, pierce point and VTEC is wrong. gpstec always takes the position from your configuration file.
+- **No elevation cut-off.** Low-elevation rays need a mapping function that fails near the equatorial anomaly. gpstec lets you choose the cut-off (50° by default) and keeps all lower data out of the products.
+- **No way to check the calibration.** gpstec reports independent checks for every day: the CODE global ionosphere map, a midnight continuity test, and a calibration uncertainty band.
+
+## Install
+
+Python 3.9 or newer:
+
+```
+pip install gpstec
+gpstec install-convbin        # only needed for .GPS input: builds RTKLIB convbin (needs git, gcc, make)
+gpstec init                   # writes station.toml: put your antenna position in it
+```
+
+On Ubuntu/Debian, `sudo apt install git build-essential` provides the build tools for `install-convbin`. On Windows, use the `convbin.exe` that comes with RTKLIB and set its path in `station.toml`.
+
+## Use
+
+```
+gpstec run -c station.toml -o results  /data/2242_*.GPS        # a week of receiver files
+gpstec run -c station.toml -o results  skbu3590.22o            # RINEX (.22n next to it)
+gpstec run -c station.toml -o results  skbu3590.22o --elev 40  # another elevation cut-off
+gpstec --version
+```
+
+Satellite bias files (CODE `.DCB`) and global ionosphere maps (CODE IONEX) are downloaded automatically into `dcb/` and `gim/`. If your network blocks the download, put the files there yourself. gpstec picks them up by date and prints the exact file names it needs.
+
+## Method
+
+1. **.GPS → RINEX** with RTKLIB `convbin -r nov`. The correct station position is written into the header.
+2. **Geometry.** Satellite positions come from the broadcast ephemeris (or SP3 precise orbits with `--sp3`). Azimuth, elevation and pierce points are computed on a thin shell at 350 km.
+3. **Slant TEC.**
+   - Code: `P4 = P2 − C1`.
+   - Carrier phase: `L4 = L1·λ1 − L2·λ2`.
+   - Each continuous satellite pass is levelled to the code with an elevation-weighted mean above 20° (Ciraolo et al., 2007).
+   - Passes that continue across midnight are levelled as one pass.
+4. **Biases:** `STEC = STEC_measured + B_sat + B_rx`.
+   - `B_sat` comes from CODE monthly DCBs (P1−P2, plus P1−C1 for C1 receivers) or from Bias-SINEX files.
+   - `B_rx` is estimated for each day from that day's night-time data alone. It is a least-squares fit of `STEC = VTEC(t, pierce point)/M(el) − B_rx`, in which VTEC may vary north–south and east–west. That matters near the anomaly crest, where minimum-scatter methods drift.
+   - The receiver bias is never allowed to make VTEC negative.
+5. **VTEC.** `VTEC = STEC · √(1 − (Re·cos E / (Re + h))²)`, using only satellites above the elevation cut-off.
+6. **Station VTEC curve.** All satellites above the cut-off are fitted together as `V0(t) + Gn(t)·Δlat + Ge(t)·Δlon` with smooth splines. The curve therefore does not jump when a satellite rises or sets, and the horizontal gradients are saved as well.
+
+## Checks you get for every day
+
+- **CODE global ionosphere map** at the station, drawn on the plot. Its night-time difference from the station is saved, typically within 2–3 TECU.
+- **Calibration uncertainty band:** the spread of independent receiver-bias estimates.
+- **Midnight continuity.** Day X's file ends at 00:00:00 and the next file starts at 00:00:01, so the same satellites are seen at the same moment. gpstec compares them and splits any jump into the part caused by the receiver-bias change and the part left over from processing.
+
+![Midnight continuity check](docs/images/midnight_continuity.png)
+
+## Outputs
+
+Per day, in `results/YYYY-MM-DD/`:
+
+| File | Content |
+|---|---|
+| `STAT_DATE_vtec_1min.csv` | UT, mean VTEC of satellites, std, satellite count, station VTEC, N/E gradients, GIM VTEC, uncertainty |
+| `STAT_DATE.Std` | Gopi-style `.Std` (UT, station VTEC, std, latitude) |
+| `STAT_DATE.Cmn` | Gopi-style `.Cmn` with correct geometry (all elevations ≥ 10°) |
+| `STAT_DATE_vtec.pdf/.png` | daily figure |
+| `STAT_DATE_pierce_points.pdf/.png` | pierce-point map coloured by VTEC |
+| `STAT_DATE_calibration.json` | every bias, method, check and warning |
+
+For multi-day runs, `results/` also gets:
+- all days in one CSV;
+- an overlay figure, a day × UT map and the midnight continuity figure;
+- `calibration_summary.csv` and `midnight_continuity.csv`.
+
+## Figures
+
+The figures are made for papers:
+- vector PDF with embedded, editable fonts, plus 300 dpi PNG;
+- legends outside the data area;
+- a colour-blind-safe palette.
+
+The test suite checks automatically that no two pieces of text touch. In `station.toml` you can change:
+- the formats (`png`, `pdf`, `svg`, `eps`, `tiff`);
+- the width (`figure_width_in = 3.5` for one journal column);
+- whether titles are drawn (`figure_titles = false` when the caption goes in the paper).
+
+![Pierce points](docs/images/pierce_points.png)
+
+## Citing
+
+If you use gpstec in published work, please cite it (see [CITATION.cff](CITATION.cff); GitHub shows a "Cite this repository" button):
+
+> Banerjee, D. (2026). gpstec: calibrated GPS total electron content from GPStation-6 receivers (version 1.0.0). https://github.com/dipanjanbanerjee/gpstec
+
+## References
+
+- Ciraolo, L., Azpilicueta, F., Brunini, C., Meza, A., & Radicella, S. M. (2007). Calibration errors on experimental slant total electron content (TEC) determined with GPS. *Journal of Geodesy*, 81, 111–120.
+- Ma, G., & Maruyama, T. (2003). Derivation of TEC and estimation of instrumental biases from GEONET in Japan. *Annales Geophysicae*, 21, 2083–2093.
+- Schaer, S. (1999). *Mapping and predicting the Earth's ionosphere using the Global Positioning System*. PhD thesis, University of Bern.
+- Seemala, G. K., & Valladares, C. E. (2011). Statistics of total electron content depletions observed over the South American continent for the year 2008. *Radio Science*, 46, RS5019.
+
+## Author and license
+
+Copyright © 2026 Dipanjan Banerjee. Released under the license in [LICENSE](LICENSE).
+
+Bug reports and questions: [GitHub issues](https://github.com/dipanjanbanerjee/gpstec/issues).

gpstec-1.0.0/README.md

@@ -0,0 +1,122 @@
+# gpstec
+
+**Calibrated GPS total electron content (TEC) from NovAtel GPStation-6 and other dual-frequency receivers.**
+
+[![tests](https://github.com/dipanjanbanerjee/gpstec/actions/workflows/tests.yml/badge.svg)](https://github.com/dipanjanbanerjee/gpstec/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/gpstec.svg)](https://pypi.org/project/gpstec/)
+
+Website: https://dipanjanbanerjee.github.io/gpstec/
+
+gpstec turns a raw GPStation-6 `.GPS` file (or any RINEX 2/3 observation file) into calibrated slant and vertical TEC, with a user-chosen elevation cut-off. It writes daily data files and publication-quality figures in one command:
+
+```
+gpstec run -c station.toml -o results  2242_0_00_skbu.GPS
+```
+
+![Daily vertical TEC at SKBU, 25 December 2022](docs/images/daily_vtec.png)
+
+## Why
+
+Many GPStation-6 users go through the chain `.GPS` → RTKLIB → RINEX → a closed calibration program → `.Cmn` files. That chain has three problems:
+
+- **Wrong station position.** RTKCONV 2.4.2 writes latitude, longitude and height into the `APPROX POSITION XYZ` header field, which expects Earth-centred coordinates. A program that trusts the header then places the station near the centre of the Earth, so every elevation, pierce point and VTEC is wrong. gpstec always takes the position from your configuration file.
+- **No elevation cut-off.** Low-elevation rays need a mapping function that fails near the equatorial anomaly. gpstec lets you choose the cut-off (50° by default) and keeps all lower data out of the products.
+- **No way to check the calibration.** gpstec reports independent checks for every day: the CODE global ionosphere map, a midnight continuity test, and a calibration uncertainty band.
+
+## Install
+
+Python 3.9 or newer:
+
+```
+pip install gpstec
+gpstec install-convbin        # only needed for .GPS input: builds RTKLIB convbin (needs git, gcc, make)
+gpstec init                   # writes station.toml: put your antenna position in it
+```
+
+On Ubuntu/Debian, `sudo apt install git build-essential` provides the build tools for `install-convbin`. On Windows, use the `convbin.exe` that comes with RTKLIB and set its path in `station.toml`.
+
+## Use
+
+```
+gpstec run -c station.toml -o results  /data/2242_*.GPS        # a week of receiver files
+gpstec run -c station.toml -o results  skbu3590.22o            # RINEX (.22n next to it)
+gpstec run -c station.toml -o results  skbu3590.22o --elev 40  # another elevation cut-off
+gpstec --version
+```
+
+Satellite bias files (CODE `.DCB`) and global ionosphere maps (CODE IONEX) are downloaded automatically into `dcb/` and `gim/`. If your network blocks the download, put the files there yourself. gpstec picks them up by date and prints the exact file names it needs.
+
+## Method
+
+1. **.GPS → RINEX** with RTKLIB `convbin -r nov`. The correct station position is written into the header.
+2. **Geometry.** Satellite positions come from the broadcast ephemeris (or SP3 precise orbits with `--sp3`). Azimuth, elevation and pierce points are computed on a thin shell at 350 km.
+3. **Slant TEC.**
+   - Code: `P4 = P2 − C1`.
+   - Carrier phase: `L4 = L1·λ1 − L2·λ2`.
+   - Each continuous satellite pass is levelled to the code with an elevation-weighted mean above 20° (Ciraolo et al., 2007).
+   - Passes that continue across midnight are levelled as one pass.
+4. **Biases:** `STEC = STEC_measured + B_sat + B_rx`.
+   - `B_sat` comes from CODE monthly DCBs (P1−P2, plus P1−C1 for C1 receivers) or from Bias-SINEX files.
+   - `B_rx` is estimated for each day from that day's night-time data alone. It is a least-squares fit of `STEC = VTEC(t, pierce point)/M(el) − B_rx`, in which VTEC may vary north–south and east–west. That matters near the anomaly crest, where minimum-scatter methods drift.
+   - The receiver bias is never allowed to make VTEC negative.
+5. **VTEC.** `VTEC = STEC · √(1 − (Re·cos E / (Re + h))²)`, using only satellites above the elevation cut-off.
+6. **Station VTEC curve.** All satellites above the cut-off are fitted together as `V0(t) + Gn(t)·Δlat + Ge(t)·Δlon` with smooth splines. The curve therefore does not jump when a satellite rises or sets, and the horizontal gradients are saved as well.
+
+## Checks you get for every day
+
+- **CODE global ionosphere map** at the station, drawn on the plot. Its night-time difference from the station is saved, typically within 2–3 TECU.
+- **Calibration uncertainty band:** the spread of independent receiver-bias estimates.
+- **Midnight continuity.** Day X's file ends at 00:00:00 and the next file starts at 00:00:01, so the same satellites are seen at the same moment. gpstec compares them and splits any jump into the part caused by the receiver-bias change and the part left over from processing.
+
+![Midnight continuity check](docs/images/midnight_continuity.png)
+
+## Outputs
+
+Per day, in `results/YYYY-MM-DD/`:
+
+| File | Content |
+|---|---|
+| `STAT_DATE_vtec_1min.csv` | UT, mean VTEC of satellites, std, satellite count, station VTEC, N/E gradients, GIM VTEC, uncertainty |
+| `STAT_DATE.Std` | Gopi-style `.Std` (UT, station VTEC, std, latitude) |
+| `STAT_DATE.Cmn` | Gopi-style `.Cmn` with correct geometry (all elevations ≥ 10°) |
+| `STAT_DATE_vtec.pdf/.png` | daily figure |
+| `STAT_DATE_pierce_points.pdf/.png` | pierce-point map coloured by VTEC |
+| `STAT_DATE_calibration.json` | every bias, method, check and warning |
+
+For multi-day runs, `results/` also gets:
+- all days in one CSV;
+- an overlay figure, a day × UT map and the midnight continuity figure;
+- `calibration_summary.csv` and `midnight_continuity.csv`.
+
+## Figures
+
+The figures are made for papers:
+- vector PDF with embedded, editable fonts, plus 300 dpi PNG;
+- legends outside the data area;
+- a colour-blind-safe palette.
+
+The test suite checks automatically that no two pieces of text touch. In `station.toml` you can change:
+- the formats (`png`, `pdf`, `svg`, `eps`, `tiff`);
+- the width (`figure_width_in = 3.5` for one journal column);
+- whether titles are drawn (`figure_titles = false` when the caption goes in the paper).
+
+![Pierce points](docs/images/pierce_points.png)
+
+## Citing
+
+If you use gpstec in published work, please cite it (see [CITATION.cff](CITATION.cff); GitHub shows a "Cite this repository" button):
+
+> Banerjee, D. (2026). gpstec: calibrated GPS total electron content from GPStation-6 receivers (version 1.0.0). https://github.com/dipanjanbanerjee/gpstec
+
+## References
+
+- Ciraolo, L., Azpilicueta, F., Brunini, C., Meza, A., & Radicella, S. M. (2007). Calibration errors on experimental slant total electron content (TEC) determined with GPS. *Journal of Geodesy*, 81, 111–120.
+- Ma, G., & Maruyama, T. (2003). Derivation of TEC and estimation of instrumental biases from GEONET in Japan. *Annales Geophysicae*, 21, 2083–2093.
+- Schaer, S. (1999). *Mapping and predicting the Earth's ionosphere using the Global Positioning System*. PhD thesis, University of Bern.
+- Seemala, G. K., & Valladares, C. E. (2011). Statistics of total electron content depletions observed over the South American continent for the year 2008. *Radio Science*, 46, RS5019.
+
+## Author and license
+
+Copyright © 2026 Dipanjan Banerjee. Released under the license in [LICENSE](LICENSE).
+
+Bug reports and questions: [GitHub issues](https://github.com/dipanjanbanerjee/gpstec/issues).

gpstec-1.0.0/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-1.0.0/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-1.0.0/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