Metadata-Version: 2.4
Name: hector-ts
Version: 3.1.1
Summary: A collection of programs to analyse geodetic time series
Home-page: https://gitlab.com/machielsimonbos/hector-ts
Author: Machiel Bos
Author-email: machielbos@protonmail.com
Project-URL: Bug Tracker, https://gitlab.com/machielsimonbos/hector-ts/issues
Keywords: geodesy,GNSS,GPS,time series,trend estimation,noise analysis,maximum likelihood,power-law noise,offset detection,Toeplitz
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: Free for non-commercial use
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: mpmath
Requires-Dist: cython
Requires-Dist: netCDF4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Hector v3.1

Hector estimates trends, periodic signals, and offsets in geodetic time series
with correlated noise. It uses Restricted Maximum Likelihood Estimation (RMLE)
and supports several noise models (GGM/flicker, power-law, AR(1), Matérn, white
noise and combinations thereof).

## Quick start

```bash
pip install hector-ts
hector-examples          # creates ./hector-examples/ with examples + manual PDF
```

`hector-examples` copies eight worked examples and the PDF user manual into a
directory of your choice.  Open `hector_manual_v3.1.pdf` first — it explains
the workflow, all control-file parameters, and walks through every example
step by step.  The examples are self-contained: each has its own data and
control files ready to run.

## Installation

### Windows

Pre-built wheels are available for Python 3.10–3.14.  FFTW3 is bundled
inside the wheel, so no separate installation is needed:

```bat
pip install hector-ts
```

### macOS (Apple Silicon — M1 and later)

Pre-built wheels are available for Python 3.10–3.14.  Install FFTW3 via
Homebrew first (it is not bundled in the macOS wheel):

```bash
brew install fftw
pip install hector-ts
```

### macOS (Intel)

Hector is compiled from source during `pip install`, so Xcode Command Line
Tools must be present (`xcode-select --install`):

```bash
brew install fftw
pip install hector-ts
```

If the build fails, conda provides a self-contained alternative:

```bash
conda install -c conda-forge fftw
pip install hector-ts
```

### Linux

Pre-built manylinux wheels are available for Python 3.10–3.14 on x86\_64 —
no FFTW3 headers needed for those platforms.  For other architectures (ARM64
etc.) Hector builds from source; install the FFTW3 development package first:

```bash
# Ubuntu / Debian
sudo apt install libfftw3-dev

# CentOS / RHEL / Fedora
sudo yum install fftw-devel        # or: sudo dnf install fftw-devel

pip install hector-ts
```

## Programs

| Name | Description |
|:--- |:--- |
| `estimatetrend` | Estimate trend, seasonal signals, and offsets using RMLE |
| `estimatespectrum` | Welch periodogram of the residuals |
| `removeoutliers` | Flag and remove outliers before trend estimation |
| `findoffsets` | Automated forward search for offset epochs |
| `find_all_offsets` | Multivariate (E+N+U) offset search on NCF files |
| `simulatenoise` | Generate synthetic coloured-noise time series |
| `estimate_all_trends` | Batch trend estimation on all files in `obs_files/` |
| `ncfgen` | Create a multi-channel NCF (NetCDF4) time-series file |
| `ncfdump` | Inspect or export an NCF file |
| `plot_ts` | Quick time-series plot from a mom file |
| `date2mjd` | Convert calendar date to Modified Julian Date |
| `mjd2date` | Inverse of `date2mjd` |
| `convert_rlrdata2mom` | Convert PSMSL RLR data to mom format |
| `predict_error` | Predict trend uncertainty as a function of series length |

## Reference

If you use Hector in your research, please cite:

> Bos, M.S. (2026). Fast noise analysis and offset detection for continuous GNSS time series. *Journal of Geodesy* (submitted).

## Performance

Hector v3.1 is a Python/Cython rewrite of [Hector C++ v2.2](https://teromovigo.com/hector/).
The core Toeplitz factorisation uses the Generalised Schur Algorithm (O(*n* log²*n*))
instead of Durbin-Levinson (O(*n*²)), and data gaps are handled exactly with an
FFT-based conjugate-gradient solver. The speedup over C++ v2.2 grows with series
length — up to ~27× at 40 years without gaps, and ~10× with 10% gaps:

| Series | Gaps | Hector v3.1 (s) | Hector C++ v2.2 (s) | Speedup |
|:---    |  ---:|             ---:|                 ---:|    ---: |
| 10 yr  |   0% |            1.11 |                 2.9 |    2.6× |
| 20 yr  |   0% |            1.60 |                 6.6 |    4.1× |
| 30 yr  |   0% |            2.32 |                21.8 |    9.4× |
| 40 yr  |   0% |            2.58 |                68.7 |   26.6× |
| 10 yr  |  10% |            2.36 |                 4.5 |    1.9× |
| 20 yr  |  10% |            4.36 |                16.5 |    3.8× |
| 30 yr  |  10% |            9.16 |                51.7 |    5.6× |
| 40 yr  |  10% |           14.44 |               150.1 |   10.4× |

*Benchmarked on Apple M4 Pro, GGM+White noise model, including offset estimation.*

## License

Free for academic, research, and educational use. Commercial use requires a
separate license from [TeroMovigo – Earth Innovation Lda](https://teromovigo.com).
See [LICENSE](LICENSE) for full terms.
