hector-ts 3.0__tar.gz

hector_ts-3.0/LICENSE

@@ -0,0 +1,78 @@
+HECTOR SOFTWARE LICENSE AGREEMENT
+--------------------------------
+
+Version 1.0
+
+Copyright (c) 2026
+TeroMovigo – Earth Innovation Lda ("Licensor")
+
+1. DEFINITIONS
+
+"Software" means the Hector software package, including source code,
+documentation, and any associated materials provided by the Licensor.
+
+"Non-Commercial Use" means use solely for research, academic, educational,
+or other purposes that are not primarily intended for or directed toward
+commercial advantage or monetary compensation.
+
+"Commercial Use" means any use that does not qualify as Non-Commercial Use,
+including use by for-profit entities, use in connection with revenue-generating
+activities, or use in proprietary products or services.
+
+2. GRANT OF LICENSE
+
+Subject to the terms of this Agreement, the Licensor hereby grants a
+non-exclusive, non-transferable, royalty-free license to use, reproduce,
+modify, and distribute the Software for Non-Commercial Use.
+
+3. COMMERCIAL USE
+
+Commercial Use of the Software is not permitted under this license.
+Any Commercial Use requires a separate written agreement with the Licensor.
+
+Commercial entities or individuals intending to use the Software for
+Commercial Use must contact:
+
+    TeroMovigo – Earth Innovation Lda
+    info@teromovigo.com / https://teromovigo.com 
+
+4. RESTRICTIONS
+
+Except as expressly permitted under this Agreement, you may not:
+
+(a) use the Software for Commercial Use;
+(b) sublicense, sell, lease, or otherwise distribute the Software
+    for Commercial Use;
+(c) remove or alter any copyright or attribution notices.
+
+5. ATTRIBUTION
+
+Any redistribution of the Software, in whole or in part, must retain
+this license text and provide appropriate attribution to the Licensor.
+
+6. OWNERSHIP
+
+The Software is licensed, not sold. All intellectual property rights,
+including copyright, remain with the Licensor.
+
+7. NO WARRANTY
+
+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 NON-INFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
+ARISING FROM OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+9. TERMINATION
+
+This license terminates automatically if you breach any of its terms.
+Upon termination, you must cease all use of the Software.
+
+10. GOVERNING LAW
+
+This Agreement shall be governed by and construed in accordance with
+the laws of [Portugal], without regard to conflict-of-law principles.

hector_ts-3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include src/hector/*.pyx
+include src/hector/*.pxd
+include LICENSE
+include README.md

hector_ts-3.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: hector-ts
+Version: 3.0
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+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: pyfftw
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+### Hector
+
+### Table of Contents
+
+1. [Introduction](#introduction)
+2. [Code Description](#code)
+    1. [Installation](#installation)
+    2. [Directory Structure](#directories)
+3. [Bugs/Future Work](#bugs)
+
+
+### 1. Introduction <a name="introduction"></a>
+
+<p>Hector is a software package that can be used to estimate a trend in time series with temporal correlated noise. Trend estimation is a common task in geophysical research where one is interested in phenomena such as the increase in temperature, sea level or GNSS derived station position over time. The trend can be linear or a higher degree polynomial and in addition one can estimate periodic signals, offsets and post-seismic deformation. Together they represent the model that is fitted to the observations.</p>
+
+<p>It is well known that in most geophysical time series the noise is correlated in time ([Agnew, 1992](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/91GL02832); [Beran, 1992](https://www.amazon.com/Statistics-Long-Memory-Processes-Monographs-Probability/dp/0412049015)) and this has a significant influence on the accuracy by which the model parameters can be estimated. Therefore, the use of a computer program such as Hector is advisable. Hector assumes that the user knows what type of temporal correlated noise exists in the observations and estimates both the model parameters and the parameters of the chosen noise model using the Restricted Maximum Likelihood Estimation (RMLE) method. Since for most observations the choice of noise model can be found from literature or by looking at the power spectral density, this is sufficient in most cases.</p>
+
+<p>Instead of using Hector, one can also use the [CATS](https://www.ngs.noaa.gov/gps-toolbox/cats.htm) software of Williams (2008). Another alternative is the program [est_noise](https://github.com/langbein-usgs/est_noise) of Langbein (2010). Recent versions include some tricks from Bos et al. (2013) to deal with missing data but with a different way to construct the covariance matrix (Langbein, 2017). Hector is a complete rewrite of [Hector](https://teromovigo.com/hector/) which is written in C++. The reason for changing the programming language was the need to make maintenance of the code easier. The Hector (P for Python) has around 8 times less lines of code than Hector (C++). In addition, Hector could not run on Windows and installation on a Mac computer was difficult. Hector is a truly cross-platform application. I have tried to keep the way Hector works similar to that of the C++ version to smooth the transition</p>
+
+The reason Hector is fast is because it makes use of the symmetry in the covariance matrix (i.e., a Toeplitz matrix) to apply fast methods to compute its inverse. Non-stationary noise is approximated by a noise model that becomes stationary at the very, very low frequencies and in this way also a Toeplitz covariance matrix is generated. This is a nutshell the core reason why Hector is fast. Another part is due to clever usage of the Fast Fourier Transform (FFT).
+
+<p> In the book by [Montillet and Bos (2020)](https://link.springer.com/book/10.1007/978-3-030-21718-1#about) more examples on the analysis of geodetic time series with temporal correlated noise can be found.</p>
+
+<p> The next secion explains how to install Hector on your computer, the best way to organise your files and the recommended work flow to analyse the time series. For more detailed information, see the Wiki pages on this site.</p>
+
+### 2. Code Description <a name="code"></a>
+
+List of programs provided by the Hector software package. Details can be found in the Wiki-pages.
+
+| Name              | Description                                              |
+|:---               |:---                                                      |
+| estimatetrend | Main program to estimate a linear trend.                 |
+| estimatespectrum  | Program to estimate the power spectral density from the data or residuals using the Welch periodogram method.  |
+| modelspectrum     | Given a noise model and values of the noise parameters,  this program computed the associated power spectral density for given frequency range.                       |
+| removeoutliers | Program to remove outliers from the data.                |
+| findoffsets       | Program to find the epoch of a possible offset in the time series.                                             |
+| simulatenoise     | Program to files with synthetic coloured noise.          |
+| date2mjd | Small program to convert calendar date into Modified  Julian Date.                                      |
+| mjd2date | The inverse of date2mjd.      |
+| msfgen | MSF: MJD - SOD - Format. Small program to combine a json file with metadata and a text file with data in columns into a single binary file.      |
+| msfdump | Inverse of msfgen. Small program that reads a msf-file and creates  a json file with metadata and a text file with data in columns.      |
+
+
+#### 2.i Installation <a name="installation"></a>
+
+Following Python customs, it is best to create a virtual environment by typing on the command line:
+```
+python3 -m venv env
+source env/bin/activate
+```
+
+This creates the virtual environment (called and stored in `env`) which is then activated. Next, on the command line type:
+```
+(env) pip install hectorp
+```
+
+That should be it. You can now go to the directory where you have your project and run the hectorp executables. Once you are done, you can exit your virtual environment with:
+```
+deactivate
+```
+
+
+#### 2.ii Directory Structure <a name="directories"></a>
+
+The following directory structure is recommended to automate the analysis of your time series with Hector:
+```
+ori_files
+obs_files
+pre_files
+fin_files
+```
+
+The `ori_files` directory is needed if your time series does follow the Hector formats. Hector comes with scripts to convert formats 
+(e.g., enu, pos, sol) into the mom-format which are then stored in the
+`obs_files` directory.
+
+The `obs_files` directory contains the time series files in mom/msf-format. 
+Normally one wants to remove outliers and the cleaned time series are stored in 
+`pre_files`. These are then analysed with 'estimatetrend' to create a copy of 
+the observations with the fitted model in the `fin_files` directory. If you 
+look at [example/ex1](./examples/ex1) then this will become clearer.
+
+The advantage of adapting this directory structure is that you can just type `estimate_all_trends` which will look for all files in the `obs_files` directory, remove the outliers, estimate the trends and finally estimates the power spectral density of the residuals.
+
+
+
+### 3. Bugs/Future Work <a name="bugs"></a>
+
+Of course, one selling point of Hector is its speed. Having a source code that is easy to maintain is all very well for me, but the user does not care about that. Fortunately, the numpy and scipy libraries are optimised which results in good comparison with the C++ version, see table below.
+
+| N        | C++ (s) | Python (s) |
+|:---      |     ---:|        ---:|
+| 1000     |       5 |        2.4 |
+| 3000     |       6 |        6.7 |
+| 5000     |       7 |       13.6 |
+| 8000     |      12 |       56.5 |
+| 5000 10% |      16 |       63.8 |
+| 8000 10% |      33 |       81.0 |
+| 5000 20% |      26 |       70.0 |
+| 8000 20% |      60 |      140.0 |
+
+
+

hector_ts-3.0/README.md

@@ -0,0 +1,103 @@
+### Hector
+
+### Table of Contents
+
+1. [Introduction](#introduction)
+2. [Code Description](#code)
+    1. [Installation](#installation)
+    2. [Directory Structure](#directories)
+3. [Bugs/Future Work](#bugs)
+
+
+### 1. Introduction <a name="introduction"></a>
+
+<p>Hector is a software package that can be used to estimate a trend in time series with temporal correlated noise. Trend estimation is a common task in geophysical research where one is interested in phenomena such as the increase in temperature, sea level or GNSS derived station position over time. The trend can be linear or a higher degree polynomial and in addition one can estimate periodic signals, offsets and post-seismic deformation. Together they represent the model that is fitted to the observations.</p>
+
+<p>It is well known that in most geophysical time series the noise is correlated in time ([Agnew, 1992](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/91GL02832); [Beran, 1992](https://www.amazon.com/Statistics-Long-Memory-Processes-Monographs-Probability/dp/0412049015)) and this has a significant influence on the accuracy by which the model parameters can be estimated. Therefore, the use of a computer program such as Hector is advisable. Hector assumes that the user knows what type of temporal correlated noise exists in the observations and estimates both the model parameters and the parameters of the chosen noise model using the Restricted Maximum Likelihood Estimation (RMLE) method. Since for most observations the choice of noise model can be found from literature or by looking at the power spectral density, this is sufficient in most cases.</p>
+
+<p>Instead of using Hector, one can also use the [CATS](https://www.ngs.noaa.gov/gps-toolbox/cats.htm) software of Williams (2008). Another alternative is the program [est_noise](https://github.com/langbein-usgs/est_noise) of Langbein (2010). Recent versions include some tricks from Bos et al. (2013) to deal with missing data but with a different way to construct the covariance matrix (Langbein, 2017). Hector is a complete rewrite of [Hector](https://teromovigo.com/hector/) which is written in C++. The reason for changing the programming language was the need to make maintenance of the code easier. The Hector (P for Python) has around 8 times less lines of code than Hector (C++). In addition, Hector could not run on Windows and installation on a Mac computer was difficult. Hector is a truly cross-platform application. I have tried to keep the way Hector works similar to that of the C++ version to smooth the transition</p>
+
+The reason Hector is fast is because it makes use of the symmetry in the covariance matrix (i.e., a Toeplitz matrix) to apply fast methods to compute its inverse. Non-stationary noise is approximated by a noise model that becomes stationary at the very, very low frequencies and in this way also a Toeplitz covariance matrix is generated. This is a nutshell the core reason why Hector is fast. Another part is due to clever usage of the Fast Fourier Transform (FFT).
+
+<p> In the book by [Montillet and Bos (2020)](https://link.springer.com/book/10.1007/978-3-030-21718-1#about) more examples on the analysis of geodetic time series with temporal correlated noise can be found.</p>
+
+<p> The next secion explains how to install Hector on your computer, the best way to organise your files and the recommended work flow to analyse the time series. For more detailed information, see the Wiki pages on this site.</p>
+
+### 2. Code Description <a name="code"></a>
+
+List of programs provided by the Hector software package. Details can be found in the Wiki-pages.
+
+| Name              | Description                                              |
+|:---               |:---                                                      |
+| estimatetrend | Main program to estimate a linear trend.                 |
+| estimatespectrum  | Program to estimate the power spectral density from the data or residuals using the Welch periodogram method.  |
+| modelspectrum     | Given a noise model and values of the noise parameters,  this program computed the associated power spectral density for given frequency range.                       |
+| removeoutliers | Program to remove outliers from the data.                |
+| findoffsets       | Program to find the epoch of a possible offset in the time series.                                             |
+| simulatenoise     | Program to files with synthetic coloured noise.          |
+| date2mjd | Small program to convert calendar date into Modified  Julian Date.                                      |
+| mjd2date | The inverse of date2mjd.      |
+| msfgen | MSF: MJD - SOD - Format. Small program to combine a json file with metadata and a text file with data in columns into a single binary file.      |
+| msfdump | Inverse of msfgen. Small program that reads a msf-file and creates  a json file with metadata and a text file with data in columns.      |
+
+
+#### 2.i Installation <a name="installation"></a>
+
+Following Python customs, it is best to create a virtual environment by typing on the command line:
+```
+python3 -m venv env
+source env/bin/activate
+```
+
+This creates the virtual environment (called and stored in `env`) which is then activated. Next, on the command line type:
+```
+(env) pip install hectorp
+```
+
+That should be it. You can now go to the directory where you have your project and run the hectorp executables. Once you are done, you can exit your virtual environment with:
+```
+deactivate
+```
+
+
+#### 2.ii Directory Structure <a name="directories"></a>
+
+The following directory structure is recommended to automate the analysis of your time series with Hector:
+```
+ori_files
+obs_files
+pre_files
+fin_files
+```
+
+The `ori_files` directory is needed if your time series does follow the Hector formats. Hector comes with scripts to convert formats 
+(e.g., enu, pos, sol) into the mom-format which are then stored in the
+`obs_files` directory.
+
+The `obs_files` directory contains the time series files in mom/msf-format. 
+Normally one wants to remove outliers and the cleaned time series are stored in 
+`pre_files`. These are then analysed with 'estimatetrend' to create a copy of 
+the observations with the fitted model in the `fin_files` directory. If you 
+look at [example/ex1](./examples/ex1) then this will become clearer.
+
+The advantage of adapting this directory structure is that you can just type `estimate_all_trends` which will look for all files in the `obs_files` directory, remove the outliers, estimate the trends and finally estimates the power spectral density of the residuals.
+
+
+
+### 3. Bugs/Future Work <a name="bugs"></a>
+
+Of course, one selling point of Hector is its speed. Having a source code that is easy to maintain is all very well for me, but the user does not care about that. Fortunately, the numpy and scipy libraries are optimised which results in good comparison with the C++ version, see table below.
+
+| N        | C++ (s) | Python (s) |
+|:---      |     ---:|        ---:|
+| 1000     |       5 |        2.4 |
+| 3000     |       6 |        6.7 |
+| 5000     |       7 |       13.6 |
+| 8000     |      12 |       56.5 |
+| 5000 10% |      16 |       63.8 |
+| 8000 10% |      33 |       81.0 |
+| 5000 20% |      26 |       70.0 |
+| 8000 20% |      60 |      140.0 |
+
+
+

hector_ts-3.0/pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "cython",
+    "numpy",
+    "pyfftw",
+]
+build-backend = "setuptools.build_meta"
+

hector_ts-3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hector_ts-3.0/setup.py

@@ -0,0 +1,147 @@
+import os
+import sys
+import subprocess
+import setuptools
+from setuptools import Extension
+from Cython.Build import cythonize
+import numpy as np
+import pyfftw
+
+
+def _fftw_include_dirs():
+    """Return a list of include directories that contain fftw3.h, portably."""
+    # 1. Honour an explicit override (useful on Windows or exotic installs).
+    fftw_dir = os.environ.get('FFTW_DIR')
+    if fftw_dir:
+        return [fftw_dir]
+
+    # 2. Ask pkg-config (works on Linux and macOS with Homebrew/MacPorts).
+    try:
+        out = subprocess.check_output(
+            ['pkg-config', '--cflags-only-I', 'fftw3'],
+            stderr=subprocess.DEVNULL, text=True,
+        )
+        dirs = [tok[2:] for tok in out.split() if tok.startswith('-I')]
+        if dirs:
+            return dirs
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    # 3. Search common platform-specific locations.
+    candidates = [
+        '/usr/include',
+        '/usr/local/include',
+    ]
+    if sys.platform == 'darwin':
+        candidates += [
+            '/opt/homebrew/include',   # Apple Silicon Homebrew
+            '/usr/local/include',      # Intel Homebrew / MacPorts
+        ]
+    elif sys.platform == 'win32':
+        candidates += [
+            r'C:\vcpkg\installed\x64-windows\include',
+            r'C:\fftw3',
+            r'C:\Program Files\fftw3\include',
+            r'C:\Program Files (x86)\fftw3\include',
+        ]
+
+    found = [d for d in candidates if os.path.isfile(os.path.join(d, 'fftw3.h'))]
+    if found:
+        return found
+
+    raise RuntimeError(
+        "fftw3.h not found. Install FFTW3 (e.g. 'brew install fftw', "
+        "'apt install libfftw3-dev', or 'conda install -c conda-forge fftw') "
+        "or set the FFTW_DIR environment variable to its include directory."
+    )
+
+
+def _fftw_ext_kwargs():
+    """Return Extension kwargs for Cython modules that link against FFTW3."""
+    inc = [np.get_include(), os.path.dirname(pyfftw.__file__)] + _fftw_include_dirs()
+    kwargs = {'include_dirs': inc}
+    if sys.platform == 'win32':
+        # Derive lib dir from the include dir (FFTW_DIR points to …/include,
+        # sibling …/lib holds fftw3.lib; vcpkg layout assumed as fallback).
+        inc_dirs = _fftw_include_dirs()
+        if inc_dirs:
+            lib_dir = os.path.join(os.path.dirname(inc_dirs[0]), 'lib')
+        else:
+            lib_dir = r'C:\vcpkg\installed\x64-windows\lib'
+        kwargs['library_dirs'] = [lib_dir]
+        # vcpkg names the import lib fftw3.lib (links to fftw3-3.dll at runtime)
+        kwargs['libraries'] = ['fftw3']
+    return kwargs
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    name="hector-ts",
+    version="3.0",
+    author="Machiel Bos",
+    author_email="machielbos@protonmail.com",
+    description="A collection of programs to analyse geodetic time series",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://gitlab.com/machielsimonbos/hector-ts",
+    project_urls={
+        "Bug Tracker": "https://gitlab.com/machielsimonbos/hector-ts/issues",
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+    package_dir={"": "src"},
+    packages=setuptools.find_packages(where="src"),
+    package_data={"hector": ["*.pyx", "*.pxd"]},
+    python_requires=">=3.6",
+    install_requires=[
+        'pandas',
+        'numpy',
+        'matplotlib',
+        'scipy',
+        'mpmath',
+        'cython',
+        'pyfftw',
+    ],
+    ext_modules=cythonize(
+        [
+            "src/hector/_epoch_scan_gaps.pyx",
+            "src/hector/_gap_correction.pyx",
+            "src/hector/_ggm.pyx",
+            "src/hector/_levinson.pyx",
+            Extension(
+                "hector._schur_gsa",
+                sources=["src/hector/_schur_gsa.pyx"],
+                **_fftw_ext_kwargs(),
+            ),
+            Extension(
+                "hector._schur_multiply",
+                sources=["src/hector/_schur_multiply.pyx"],
+                **_fftw_ext_kwargs(),
+            ),
+        ],
+        language_level="3",
+    ),
+    include_dirs=[np.get_include()],
+    entry_points ={
+        'console_scripts': [
+            'estimatespectrum = hector.estimatespectrum:main',
+            'modelspectrum = hector.modelspectrum:main',
+            'estimatetrend = hector.estimatetrend:main',
+            'estimate_all_trends = hector.estimate_all_trends:main',
+            'removeoutliers = hector.removeoutliers:main',
+            'findoffsets = hector.findoffsets:main',
+            'find_all_offsets = hector.find_all_offsets:main',
+            'simulatenoise = hector.simulatenoise:main',
+            'mjd2date = hector.mjd2date:main',
+            'date2mjd = hector.date2mjd:main',
+            'convert_rlrdata2mom = hector.convert_rlrdata2mom:main',
+            'predict_error = hector.predict_error:main',
+            'test_Schur = hector.test_Schur:main',
+            'msfgen= hector.msfgen:main',
+            'msfdump= hector.msfdump:main',
+        ],
+    }
+)