path#
Usage#
usage: path [-h] [--version] [--output OUTPUT]
Compute path
options:
-h, --help show this help message and exit
--version print the version number and exit
--output OUTPUT Output positions
Overview#
The path
program computes the drift (trajectory) of a set of points over a
geostrophic velocity field time series. It reads an input table of positions
(longitude, latitude) and advects them from a start time to an end time.
Quick start#
path list.ini buoys.txt "2010-01-01" "2010-01-02" --output tracks.tsv
list.ini
: configuration of the velocity time seriesbuoys.txt
: initial positionsStart and end times in any ISO-like format (parsed with
dateutil
)Output is written to
tracks.tsv
(tab-separated). Without--output
, results are printed to stdout.
Inputs#
Configuration file#
Use a simple configuration file (one item per line) to describe the U/V time
series, similar to the one used by map_of_fle
:
U = /path/to/dt_upd_global_merged_madt_uv_20091230_20091230_20110329.nc
U = /path/to/dt_upd_global_merged_madt_uv_20100106_20100106_20110329.nc
... (one line per time slice)
V = /path/to/dt_upd_global_merged_madt_uv_20091230_20091230_20110329.nc
V = /path/to/dt_upd_global_merged_madt_uv_20100106_20100106_20110329.nc
... (one line per time slice)
U_NAME = Grid_0001
V_NAME = Grid_0002
FILL_VALUE = 0
U
/V
: paths to NetCDF files containing eastward/northward velocities for each time step (accepts absolute paths or${ENV}
variables).U_NAME
/V_NAME
: variable names inside the NetCDF files.FILL_VALUE
: value used for missing data (0
to avoid propagating missing values, ornan
to propagate them).
If you need sample data, see data.zip and the AVISO product page.
Buoys file format#
A plain text file with one point per line:
First column: longitude in degrees (range -180..180)
Second column: latitude in degrees (range -90..90)
Lines may contain comments starting with
#
Columns separated by whitespace (spaces or tabs)
Example:
# lon lat
0 0
1.433333 43.6
70 1
Command examples#
# Drift for 1 day, default 6 h time step
path list.ini buoys.txt "2010-01-01" "2010-01-02"
# Write output to a file
path list.ini buoys.txt "2010-01-01" "2010-01-02" --output tracks.tsv
Options#
--output FILE
: write results to a file (tab-separated). Defaults to stdout if omitted.--version
: print version and exit.
Positional arguments:
configuration
: path to the configuration file.input
: path to the buoys file.start_time
: start time of the drift.end_time
: end time of the drift.
Notes#
The internal integration time step is fixed to 6 hours.
The start/end times must lie within the velocity time series; otherwise a runtime error is raised.
Longitudes must be in [-180, 180] and latitudes in [-90, 90].
Output#
Tab-separated values with the following columns on each printed time step:
Index of the buoy (0-based)
Longitude [degree]
Latitude [degree]
Timestamp in ISO format
Example output snippet:
0 0.000000 0.000000 2010-01-01T01:00:00
1 1.433333 43.600000 2010-01-01T01:00:00
0 -0.038031 -0.013479 2010-01-01T07:00:00
Help#
Type path --help
or path.py --help
to see all options.
Troubleshooting#
PYTHONPATH#
If you see this error message:
ImportError: No module named lagrangian
Set the PYTHONPATH
environment variable to include the directory that
contains the compiled lagrangian
module (lagrangian.so
).
UDUNITS2_XML_PATH#
If you see this error message:
RuntimeError: The variable UDUNITS2_XML_PATH is unset, and the installed, default unit, database couldn't be opened: No such file or directory
Set the UDUNITS2 database path, for example:
export UDUNITS2_XML_PATH=/path/to/share/udunits/udunits2.xml
See also#
map_of_fle: compute FSLE/FTLE maps from the same velocity time series.