Estimators of Ship Tracks

Kalman Filters

This Python library implements an Unscented Kalman Filter with geodetic dynamics, as described in references 1 and 2. Furthermore, it includes the implementation of the Unscented Rauch-Tung-Striebel Smoother (URTSS) algorithm, elaborated in reference 3. The implemented outlier robustification method is detailed in reference 4.

Gausian Processes

This library leverages the functionalities of Gaussian Process models available in scikit-learn, documented in reference 5. Users can use all features of Gaussian Process models seamlessly through this toolkit.

Conda environment

To utilise this package, it should be installed within a dedicated Conda environment. You can create a Conda environment with Python 3.10 using the following command:

conda create -n shiptrack-estimators python=3.10 -c conda-forge

To activate the conda environment use:

conda activate shiptrack-estimators

Whenever you need to deactivate the Conda environment, execute:

conda deactivate

Pyenv environment

Alternatively, instead of using Conda, you can utilise a dedicated pyenv environment to install this package. Assuming you already have pyenv installed (if not, see the pyenv installation instructions here), the first step is to install Python 3.10:

pyenv install 3.10.13

You can then create a virtual environment using the following command:

pyenv virtualenv 3.10.13 shiptrack-estimators

To activate the pyenv environment use:

pyenv activate shiptrack-estimators

Whenever you need the pyenv environment, execute:

pyenv deactivate

Install the package

To install this library, follow these steps:

Cloning the repository

Begin by cloning this repository using the following command:

git clone git@github.com:NOC-OI/ship-track-estimators.git

Pip installation

Once the repository is cloned, navigate to the root directory of the package and execute the following command:

pip install -e .

If you prefer to install the package directly from the repository without cloning it, use the following command:

pip install git+https://github.com/NOC-OI/ship-track-estimators.git@main#egg=track_estimators

Examples

Python Scripts

Numerous examples of Python scripts explaining how to use this package can be found in the examples directory.

Command line interface (CLI)

The CLI provided by this package allows you to execute the Unscented Kalman Filter; however, it offers less flexibility compared to using the Python scripts. To run the track estimator in the terminal, type, e.g., the following command:

track_estimator -i input.json -o "output" -t  data/historical_ships/historical_ship_data.csv -s 01203823 -ic "primary.id" -lat "lat" -lon "lon" -rts

Flags description

• -i or --input: Filepath to the input JSON file containing the Unscented Kalman Filter configurations (by default input.json)
• -o or --output: Output file prefix (by default output)
• -t or --track-file: Filepath to the ship track data (mandatory)
• -s or --ship-id: ID of the ship (mandatory)
• -lat or --latitude-id: Name of the latitude column (mandatory)
• -lon or --longitude-id: Name of the longitude column (mandatory)
• -ic or --id-col: Name of the ship ID column (mandatory)
• -rts or --rts-smoother: Apply the Rauch-Tung-Striebel (RTS) smoother
• -rev or --reverse: Reverse the track

Example of input.json

{
  "dim": 4,
  "H": [1, 1, 0, 0],
  "R": [0.0025, 0.0025, 0, 0],
  "Q": [1e-4, 1e-4, 1e-6, 1e-6],
  "P": [1.0, 1.0, 1.0, 1.0],
  "dt": 1,
  "nsteps": 500,
}

Here, dim represents the dimensions of matrices, H is the measurement matrix, R is the measurement noise covariance matrix, Q the process noise covariance, and P is the estimate error covariance matrix. Furthermore, dt is the time step (which can be either a constant time step or a list of numbers), and nsteps indicates the number of estimation steps to be performed. When dt is -1, 0 or null, the nsteps parameter indicates the number of sub-steps that should be performed within each main time step, as determined by the measurements. For example:

{
  "dim": 4,
  "H": [1, 1, 0, 0],
  "R": [0.001, 0.001, 0, 0],
  "Q": [1e-2, 1e-2, 1e-4, 1e-4],
  "P": [1.0, 1.0, 1.0, 1.0],
  "dt": -1,
  "nsteps": 2
}

This configuration will result in performing 2 sub-steps within each main step, with the length of each main step determined by the measurement data. It produces the following results:

The speed over ground (SOG) and course over ground (COG) can also be smoothed prior to calculating their respective rates using the smooth parameter, which determines the number of data points to be used for the moving average.

{
  "dim": 4,
  "H": [1, 1, 0, 0],
  "R": [0.01, 0.01, 0, 0],
  "Q": [1e-4, 1e-4, 1e-6, 1e-6],
  "P": [1.0, 1.0, 1.0, 1.0],
  "dt": -1,
  "nsteps": 2,
  "smooth": 2
}

References

1. Unscented Kalman filter for long-distance vessel tracking in geodetic coordinates
2. Unscented Filtering and Nonlinear Estimation
3. Unscented Rauch-Tung-Striebel Smoother
4. Robust Kalman filtering based on Mahalanobis distance as outlier judging criterion
5. scikit-learn: Gaussian Processes