Using the command line interface

Tintx also comes with a simple command line interface (cli) to apply tracking and visualise tracking data. After installing tintx you will have tintx available to your command line. Like with most command line tools you can inspect the help menu using the --help flag:

tintx --help

Usage: tintx [OPTIONS] COMMAND [ARGS]...

  Command line interface (cli) of the tintX tracking algorithm.

  The cli offers two sub commands. One for applying the tracking algorithm,
  one for visualisation of already tracked data.

Options:
  -V, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  plot   Plot/Animate existing tracking data.
  track  Apply the tintX tracking algorithm.

As the help menu suggests the tintx command comes with two sub commands (track and plot).

Applying the tracking algorithm

The track sub command can be used to apply tracking:

tintx track --help

Usage: tintx track [OPTIONS] VARIABLE [INPUT_FILES]...

  Apply the tintX tracking algorithm.

  The sub command takes at least two arguments and attempts of read data saved
  in netcdf/grib format and apply the tracking to a data variable within the
  dataset.

  Arguments:

  variable:     Variable name of the data that is tracked

  input_files:     Filename(s) or Directory where the data is stored.

Options:
  -s, --start TEXT        ISO-8601 string representation of the first tracking
                          time step.
  -e, --end TEXT          ISO-8601 string representation of the last tracking
                          time step.
  --x-coord TEXT          Name of the X (eastward) coordinate
  --y-coord TEXT          Name of the Y (northward) coordinate
  --time-coord TEXT       Name of the time coordinate
  -o, --output PATH       Output file where the tracking results pandas
                          DataFrame is saved to. If `None` given (default) the
                          output filename will be set from the input meta data
                          and the variable name.
  --field-thresh FLOAT    Threshold used for object detection. Detected
                          objects are connected pixels above this threshold.
  --iso-thresh FLOAT      Used in isolated cell classification. Isolated cells
                          must not be  connected to any other cell by
                          contiguous pixels above this threshold.
  --min-size FLOAT        Minimum size threshold in pixels for an object to be
                          detected.
  --search-margin FLOAT   Radius of the search box around the predicted object
                          center.
  --flow-margin FLOAT     Margin size around objects to perform phase
                          correlation.
  --max-disparity FLOAT   Maximum allowable disparity value.
  --max-flow-mag FLOAT    Maximum allowable global shift magnitude.
  --max-shift-disp FLOAT  Maximum magnitude of difference in meters per second
                          for two shifts to be considered in agreement.
  --gs-alt FLOAT          Altitude in meters at which to perform phase
                          correlation for globalshift calculation. 3D data
                          only
  --iso-smooth FLOAT      Gaussian smoothing parameter in peak detection
                          preprocessing.
  -h, --help              Show this message and exit.

We can for example apply the tracking to the radar estimates. The radar estimates are saved in netCDF files with the longitude variable saved as longitude and the latitude variable saved as latitude. The variable name is radar_estimated_rain_rates. Let’s apply the tracking and save the tracks to a hdf5 file.

tintx track radar_estimated_rain_rate $DATA_FILES/CPOL_radar.nc \
  --field-thresh 0.1 --min-size 4 --x-coord longitude --y-coord latitude \
  -s 2006-11-16T03:00 -e 2006-11-16T11:00 -o /tmp/output.h5

Tracking: 49it [00:01, 25.53it/s]
Found and tracked 125 objects.

Plotting the data

The plot sub command can be used to plot data that has as already been tracked:

tintx plot --help

Usage: tintx plot [OPTIONS] INPUT_FILE

  Plot/Animate existing tracking data.

  Arguments:

  input_files:     Filename of the HDF5 file containing the tracking data.

Options:
  -o, --output FILE        Path to a visualisation of the tracking. If `None`
                           is given, no visualisation will be created. The
                           type of visualisation will be determined from the
                           file type. E.i for `.png` or `.jpg` files
                           trajectory plots will be created for `.mp4`, `.gif`
                           animations will be created.
  --animate                Create animation
  --dt FLOAT               Offset in hours from UTC. Animation only
  --fps FLOAT              Play back speed of an animation. Animation only
  --cmap TEXT              Colormap used for animations.
  --vmin FLOAT             minimum values to be plotted
  --vmax FLOAT             Maximum values to display. Animation only
  --mintrace FLOAT         Minimum length of a trace to be plotted: Trajectory
                           plot only
  -ms, --markersize FLOAT  Help marker size of the trijectory plot
  -lw, --linewidth FLOAT   Line width to be plotted.
  -h, --help               Show this message and exit.

Let’s create a plot of the tracks that have been identified.

tintx plot /tmp/output.h5 -o tracks_new.png  -lw 1 -ms 35

This will result in the following image: