Creating cell tracks with the RunDirectory class

TintX main tracking utility.

TintX offers a simple :class:RunDirectory class that uses the xarray library to read datasets such as model output data or observational datasets.

The cell tracking as well as visualisation of cell tracks is realised through instances of this RunDirectory class.

class tintx.RunDirectory(dataset: Dataset | DataArray, var_name: str, *, time_coord: str = 'time', x_coord: str = 'lon', y_coord: str = 'lat', crs: str | CRS | Projection = 'epsg:4326', _files: list[str] | str = '')

Bases: Cell_tracks

Create an RunDirectory object from a given xarray dataset.

The RunDirectory object gathers all necessary information of data that is stored in a xarray dataset. Once loaded the most important metadata will be stored in the run directory for faster access the second time.

Parameters:

• dataset (xarray.DataArray, xarray.Dataset) – Input dataset/data array

• var_name (str) – Name of the variable that is tracked

• x_coord (str, default: lon) – Name of the X coordinate array/vector

• y_coord (str, default: lat) – Name of the Y coordinate array/vector

• time_coord (str, default: time) – Name of the time variable.

Example

import os
import xarray
from tintx import RunDirectory
files = os.path.join(os.environ["FILE_PATH"], "CMORPH*.nc")
dset = xarray.open_mfdataset(files, combine="by_coords")
run = RunDirectory(dset.isel(time=slice(10, 150)), "prcip")

animate(vmin: float = 0.01, vmax: float = 15, ax: GeoAxes | None = None, cmap: str | Colormap = 'Blues', alt: float | None = None, fps: float = 5, isolated_only: bool = False, tracers: bool = False, dt: float = 0, plot_style: dict[str, float | int | str] | None = None) → GeoAxes

Create a animation of tracked cells.

Parameters:

• vmin (float, default: 0.01) – Minimum values for the colormap.

• vmax (float, default: 15.0) – Maximum values for the colormap.

• isolated_only (bool, default: False) – If true, only annotates uids for isolated objects.

• cmap (str, default: Blues) – Colormap used for plotting the tracked fields.

• alt (float, default: None) – Altitude to be plotted in meters, for 3D data only.

• tracers (bool, default: False) – Plot traces of animated cells

• dt (float, default: 0) – Time shift in hours that is applied to the data, this can be useful if time data is in utc but should be displayed in another time zone.

• fps (int, default: 5) – Frames per second for output.

• ax (cartopy.mpl.geoaxes.GeoAxesSubplot, default: None) – Axes object that is used to create the animation. If None (default) a new axes object will be created.

• plot_style (dict) – Additional keyword arguments passed to the plotting routine.

Returns:

See FuncAnimation for more details.

Return type:

matplotlib.animation.FuncAnimation

Example

from tintx import RunDirectory
run = RunDirectory.from_files(
    os.path.join(os.environ["FILE_PATH"], "CPOL*.nc"),
    "radar_estimated_rain_rate", x_coord="x", y_coord="y"
)
run.get_tracks(min_size=4, field_thresh=2)
anim = run.animate(vmax=3, fps=2, plot_style={"lw":1})

Tracking:   0%|          | 0/143 [00:00<?, ?it/s]
Tracking:   3%|3         | 5/143 [00:00<00:03, 44.71it/s]
Tracking:   7%|6         | 10/143 [00:00<00:04, 31.58it/s]
Tracking:  10%|#         | 15/143 [00:00<00:03, 36.47it/s]
Tracking:  13%|#3        | 19/143 [00:00<00:03, 31.37it/s]
Tracking:  16%|#6        | 23/143 [00:00<00:04, 26.64it/s]
Tracking:  18%|#8        | 26/143 [00:00<00:05, 21.17it/s]
Tracking:  20%|##        | 29/143 [00:01<00:06, 18.58it/s]
Tracking:  22%|##2       | 32/143 [00:01<00:06, 16.42it/s]
Tracking:  24%|##3       | 34/143 [00:01<00:06, 16.15it/s]
Tracking:  25%|##5       | 36/143 [00:01<00:06, 16.66it/s]
Tracking:  27%|##7       | 39/143 [00:01<00:05, 17.84it/s]
Tracking:  29%|##9       | 42/143 [00:01<00:05, 18.79it/s]
Tracking:  31%|###       | 44/143 [00:02<00:05, 18.57it/s]
Tracking:  32%|###2      | 46/143 [00:02<00:05, 17.86it/s]
Tracking:  34%|###4      | 49/143 [00:02<00:04, 19.60it/s]
Tracking:  37%|###7      | 53/143 [00:02<00:04, 21.50it/s]
Tracking:  39%|###9      | 56/143 [00:02<00:03, 22.69it/s]
Tracking:  43%|####2     | 61/143 [00:02<00:02, 28.68it/s]
Tracking:  48%|####7     | 68/143 [00:02<00:01, 37.92it/s]
Tracking:  52%|#####1    | 74/143 [00:02<00:01, 42.32it/s]
Tracking:  55%|#####5    | 79/143 [00:03<00:01, 44.24it/s]
Tracking:  70%|######9   | 100/143 [00:03<00:00, 89.07it/s]
Tracking:  80%|########  | 115/143 [00:03<00:00, 105.96it/s]
Tracking:  89%|########8 | 127/143 [00:03<00:00, 43.00it/s] 
Tracking:  95%|#########5| 136/143 [00:04<00:00, 23.94it/s]
Tracking: 100%|##########| 143/143 [00:05<00:00, 18.24it/s]
Tracking: 144it [00:05, 24.96it/s]                         

classmethod from_dataframe(track_file: str | Path, dataset: Dataset | None = None) → RunDirectory

Create an instance of the RunDirectory class from tintx tracks.

Parameters:

• track_file (str, pathlib.Path) – Path to the hdf5 file containing the tint tracks

• dataset (xr.Dataset, default: None) – xarray Dataset holding the data of the tracked field. if None (default) the dataset will be re opened from the files. Note: this only works if the previous instance of the tracking class was instanciated with the from_files method.

• note:: (..)

• created (If the dataset can't be opened an empty data set will be)

• instead.

Example

Tracking:   0%|          | 0/143 [00:00<?, ?it/s]
Tracking:   3%|2         | 4/143 [00:00<00:03, 36.55it/s]
Tracking:   6%|5         | 8/143 [00:00<00:04, 32.96it/s]
Tracking:   8%|8         | 12/143 [00:00<00:04, 30.01it/s]
Tracking:  11%|#1        | 16/143 [00:00<00:04, 30.59it/s]
Tracking:  14%|#3        | 20/143 [00:00<00:04, 26.00it/s]
Tracking:  16%|#6        | 23/143 [00:00<00:05, 22.37it/s]
Tracking:  18%|#8        | 26/143 [00:01<00:06, 18.46it/s]
Tracking:  20%|##        | 29/143 [00:01<00:06, 17.79it/s]
Tracking:  22%|##1       | 31/143 [00:01<00:06, 17.81it/s]
Tracking:  23%|##3       | 33/143 [00:01<00:06, 16.97it/s]
Tracking:  24%|##4       | 35/143 [00:01<00:07, 15.24it/s]
Tracking:  26%|##5       | 37/143 [00:01<00:07, 13.61it/s]
Tracking:  27%|##7       | 39/143 [00:02<00:08, 12.88it/s]
Tracking:  29%|##8       | 41/143 [00:02<00:07, 13.95it/s]
Tracking:  31%|###       | 44/143 [00:02<00:05, 17.01it/s]
Tracking:  32%|###2      | 46/143 [00:02<00:05, 17.27it/s]
Tracking:  34%|###3      | 48/143 [00:02<00:05, 17.57it/s]
Tracking:  36%|###6      | 52/143 [00:02<00:04, 21.75it/s]
Tracking:  38%|###8      | 55/143 [00:02<00:04, 21.95it/s]
Tracking:  41%|####      | 58/143 [00:02<00:03, 23.38it/s]
Tracking:  43%|####2     | 61/143 [00:03<00:03, 23.42it/s]
Tracking:  46%|####6     | 66/143 [00:03<00:02, 29.24it/s]
Tracking:  50%|#####     | 72/143 [00:03<00:01, 36.23it/s]
Tracking:  53%|#####3    | 76/143 [00:03<00:01, 35.39it/s]
Tracking:  56%|#####5    | 80/143 [00:03<00:01, 31.97it/s]
Tracking:  59%|#####9    | 85/143 [00:03<00:01, 36.03it/s]
Tracking:  67%|######7   | 96/143 [00:03<00:00, 53.54it/s]
Tracking:  72%|#######2  | 103/143 [00:03<00:00, 57.48it/s]
Tracking:  76%|#######6  | 109/143 [00:03<00:00, 57.23it/s]
Tracking:  80%|########  | 115/143 [00:04<00:00, 41.27it/s]
Tracking:  84%|########3 | 120/143 [00:04<00:01, 21.50it/s]
Tracking:  87%|########6 | 124/143 [00:05<00:01, 14.67it/s]
Tracking:  89%|########8 | 127/143 [00:05<00:01, 12.39it/s]
Tracking:  91%|######### | 130/143 [00:06<00:01, 11.52it/s]
Tracking:  92%|#########2| 132/143 [00:06<00:01, 10.81it/s]
Tracking:  94%|#########3| 134/143 [00:06<00:00, 10.42it/s]
Tracking:  95%|#########5| 136/143 [00:06<00:00, 10.06it/s]
Tracking:  97%|#########6| 138/143 [00:07<00:00,  9.16it/s]
Tracking:  98%|#########7| 140/143 [00:07<00:00,  8.64it/s]
Tracking:  99%|#########8| 141/143 [00:07<00:00,  8.62it/s]
Tracking:  99%|#########9| 142/143 [00:07<00:00,  8.10it/s]
Tracking: 100%|##########| 143/143 [00:07<00:00,  7.78it/s]
Tracking: 144it [00:07,  7.22it/s]                         
Tracking: 144it [00:08, 17.84it/s]
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:82: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.coords.to_hdf(buffer, "dims")
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:83: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.to_dataframe(self._x_coord).to_hdf(buffer, "x_coord")
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:84: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.to_dataframe(self._y_coord).to_hdf(buffer, "y_coord")

from tintx import RunDirectory
run = RunDirectory.from_dataframe("/tmp/output.hdf5")

See also

save_tracks

classmethod from_files(input_files: Path | str | list[str] | list[Path] | Iterator[Path], var_name: str, *, x_coord: str = 'lon', y_coord: str = 'lat', time_coord: str = 'time', start: str | datetime | Timestamp | None = None, end: str | datetime | Timestamp | None = None, crs: str | CRS | Projection = 'epsg:4326', **kwargs: Any) → RunDirectory

Create a RunDirectory object from input file(s)/directory.

The RunDirectory object gathers all necessary information of the data that is stored in the run directory. Once loaded the most important metadata will be stored in the run directory for faster access the second time.

Parameters:

• inp_files (os.PathLike, list[os.PathLike]) – Input filenames or directory that is opened.

• var_name (str) – Name of the variable that is tracked

• start (str, pandas.Timestamp, datetime.datetime (default: None)) – first time step that is considered, if None given the first time step in the data is considered.

• end (str, pandas.Timestamp, datetime.datetime (default: None)) – last time step that is considered, if None given the last time step in the data is considered.

• x_coord (str (default: lat)) – The name of the longitude vector/array, can be 1D or 2D

• x_coord – The name of the latitude vector/array, can be 1D or 2D

• time_coord (str, default: time) – The name of the time variable

• crs (str, pyproj.Proj, cartopy.crs.Projection (default: "epsg:4326")) – pyproj/cartopy projection object or string defining the Coordinate Reference System (CRS). If “aeqd”, CRS will be computed as AzimuthalEquidistant Projection from the geodetic radar site coordinates “longitude” and “latitude”.

• kwargs – Additional keyword arguments that are passed to open the dataset with xarray

Example

import os
from tintx import RunDirectory
run = RunDirectory.from_files(
    os.path.join(os.environ["FILE_PATH"], "CMORPH*.nc"),
    "cmorph"
)

get_parameters(tracks: DataFrame | None = None) → dict[str, float]

Get the parameters of given cell tracks.

Parameters:

tracks (pd.DataFrame, default: None) – The tracks DataFrame that is the result of the tuning parameters in question.

Returns:

dict

Return type:

dictionary holding the tuning parameters for the given tracks.

Raises:

ValueError – if no parameters matching the input tracks DataFrame: could be found.

Example

from tintx import RunDirectory
run = RunDirectory.from_dataframe("/tmp/output.hdf5")
parameters = run.get_parameters()

get_tracks(centre: tuple[float, float] | None = None, leave_bar: bool = True, flush: bool = True, **tracking_parameters: float) → int

Apply the tint tracking algorithm.

This is the primary method of the RunDirectory class. This method applies the tracking algorithm to the data and saves the tracked cells to a pandas DataFrame for analysis.

Parameters:

• centre (tuple, default: None) – The centre of the radar station

• leave_bar (bool, default: True) – Leave the progress bar after tracking is finished

• flush (bool, default: True) – Flush old tracking data. If false, the tracks will be added to the existing ::method::tracks DataFrame.

• **tracking_parameters (float) – Overwrite the tint tracking parameters with these values for this specific tracking. The defaults will be restored afterwards. See tintx.config for details

See also

tintx.config

Returns:

int

Return type:

Number of unique cells identified by the tracking

Example

import os
import xarray
from tintx import RunDirectory
files = os.path.join(os.environ["FILE_PATH"], "CPOL*.nc")
dset = xarray.open_mfdataset(files, combine="by_coords")
run = RunDirectory(dset,
                   "radar_estimated_rain_rate",
                   x_coord="longitude",
                   y_coord="latitude")
num_cells = run.get_tracks(field_thresh=0.01)

Tracking:   0%|          | 0/143 [00:00<?, ?it/s]
Tracking:   3%|2         | 4/143 [00:00<00:03, 36.82it/s]
Tracking:   6%|5         | 8/143 [00:00<00:04, 33.11it/s]
Tracking:   8%|8         | 12/143 [00:00<00:04, 28.10it/s]
Tracking:  10%|#         | 15/143 [00:00<00:04, 28.10it/s]
Tracking:  13%|#2        | 18/143 [00:00<00:04, 25.79it/s]
Tracking:  15%|#4        | 21/143 [00:00<00:05, 21.71it/s]
Tracking:  17%|#6        | 24/143 [00:01<00:06, 18.36it/s]
Tracking:  18%|#8        | 26/143 [00:01<00:07, 15.46it/s]
Tracking:  20%|#9        | 28/143 [00:01<00:07, 15.13it/s]
Tracking:  21%|##        | 30/143 [00:01<00:07, 15.40it/s]
Tracking:  22%|##2       | 32/143 [00:01<00:07, 15.80it/s]
Tracking:  24%|##3       | 34/143 [00:01<00:07, 13.72it/s]
Tracking:  25%|##5       | 36/143 [00:02<00:08, 12.13it/s]
Tracking:  27%|##6       | 38/143 [00:02<00:09, 11.10it/s]
Tracking:  28%|##7       | 40/143 [00:02<00:09, 11.09it/s]
Tracking:  29%|##9       | 42/143 [00:02<00:07, 12.73it/s]
Tracking:  31%|###1      | 45/143 [00:02<00:06, 14.45it/s]
Tracking:  33%|###2      | 47/143 [00:02<00:06, 15.43it/s]
Tracking:  34%|###4      | 49/143 [00:02<00:05, 16.40it/s]
Tracking:  37%|###7      | 53/143 [00:03<00:04, 20.38it/s]
Tracking:  39%|###9      | 56/143 [00:03<00:04, 19.41it/s]
Tracking:  41%|####1     | 59/143 [00:03<00:03, 21.59it/s]
Tracking:  43%|####3     | 62/143 [00:03<00:03, 23.61it/s]
Tracking:  47%|####6     | 67/143 [00:03<00:02, 29.60it/s]
Tracking:  51%|#####1    | 73/143 [00:03<00:02, 33.91it/s]
Tracking:  54%|#####3    | 77/143 [00:03<00:01, 34.39it/s]
Tracking:  57%|#####6    | 81/143 [00:03<00:02, 30.21it/s]
Tracking:  60%|######    | 86/143 [00:04<00:01, 34.56it/s]
Tracking:  71%|#######   | 101/143 [00:04<00:00, 61.96it/s]
Tracking:  76%|#######5  | 108/143 [00:04<00:00, 63.81it/s]
Tracking:  80%|########  | 115/143 [00:04<00:00, 43.11it/s]
Tracking:  85%|########4 | 121/143 [00:05<00:01, 19.61it/s]
Tracking:  88%|########8 | 126/143 [00:06<00:01, 13.96it/s]
Tracking:  91%|######### | 130/143 [00:06<00:01, 12.55it/s]
Tracking:  93%|#########3| 133/143 [00:06<00:00, 11.57it/s]
Tracking:  94%|#########4| 135/143 [00:07<00:00, 11.29it/s]
Tracking:  96%|#########5| 137/143 [00:07<00:00, 10.98it/s]
Tracking:  97%|#########7| 139/143 [00:07<00:00, 10.07it/s]
Tracking:  99%|#########8| 141/143 [00:07<00:00,  9.49it/s]
Tracking: 100%|##########| 143/143 [00:08<00:00,  8.97it/s]
Tracking: 144it [00:08, 17.32it/s]                         

property grids: Iterator[GridType]

Iterator holding longitude/latitude/time and data.

plot_trajectories(label: bool = False, ax: GeoAxes | None = None, uids: list[str] | None = None, mintrace: int = 2, size: int = 50, thresh: float = -1.0, color: str | None = None, plot_style: dict[str, float | int | str] | None = None) → GeoAxes

Plot traces of trajectories for each cell track.

This code is a fork of plot_traj method in the plot module from the trackpy project see http://soft-matter.github.io/trackpy for more details

Parameters:

• label (boolean, default: False) – Set to True to write cell uids next to trajectories.

• cmap (colormap, Default matplotlib.colormap.winter) – Colormap used to color different tracks

• ax (cartopy.mpl.geoaxes.GeoAxesSubplot, default: None) – Axes object that is used to create the animation. If None (default) a new axes object will be created.

• uids (list[str], default: None) – a preset of stroms to be drawn, instead of all (default)

• color (str, default: None) – A pre-defined color, if None (default) each track will be assigned a different color.

• thresh (float, default: -1) – Plot only trajectories with average intensity above this value.

• mintrace (int, default 2) – Minimum length of a trace to be plotted

• plot_style (dict) – Additional keyword arguments passed through to the Axes.plot(...)

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

Example

from tintx import RunDirectory
run = RunDirectory.from_dataframe("/tmp/output.hdf5")
ax = run.plot_trajectories(thresh=2, plot_style={"ms":25, "lw":1})

reset_tracks(tracks: DataFrame | None = None) → None

Override the tack data with a given DataFrame.

Parameters:

tracks (pd.DataFrame, default: None) – Tracking information used to override the current tarcks. If None (default) an empty DataFrame will be used.

Example

import os
import xarray
from tintx import RunDirectory
files = os.path.join(os.environ["FILE_PATH"], "CPOL*.nc")
dset = xarray.open_mfdataset(files, combine="by_coords")
run = RunDirectory(dset,
                   "radar_estimated_rain_rate",
                   x_coord="longitude",
                   y_coord="latitude")
num_cells = run.get_tracks(field_thresh=0.01)
print(len(run.tracks))
run.reset_tracks()
print(len(run.tracks))

763
0

Tracking:   0%|          | 0/143 [00:00<?, ?it/s]
Tracking:   3%|2         | 4/143 [00:00<00:03, 39.11it/s]
Tracking:   6%|5         | 8/143 [00:00<00:04, 33.65it/s]
Tracking:   8%|8         | 12/143 [00:00<00:04, 28.34it/s]
Tracking:  10%|#         | 15/143 [00:00<00:04, 28.35it/s]
Tracking:  13%|#2        | 18/143 [00:00<00:04, 25.99it/s]
Tracking:  15%|#4        | 21/143 [00:00<00:05, 21.81it/s]
Tracking:  17%|#6        | 24/143 [00:01<00:06, 18.38it/s]
Tracking:  18%|#8        | 26/143 [00:01<00:07, 15.64it/s]
Tracking:  20%|#9        | 28/143 [00:01<00:07, 15.30it/s]
Tracking:  21%|##        | 30/143 [00:01<00:07, 15.56it/s]
Tracking:  22%|##2       | 32/143 [00:01<00:06, 15.98it/s]
Tracking:  24%|##3       | 34/143 [00:01<00:07, 13.82it/s]
Tracking:  25%|##5       | 36/143 [00:02<00:08, 12.18it/s]
Tracking:  27%|##6       | 38/143 [00:02<00:09, 11.10it/s]
Tracking:  28%|##7       | 40/143 [00:02<00:09, 11.08it/s]
Tracking:  30%|###       | 43/143 [00:02<00:07, 13.61it/s]
Tracking:  31%|###1      | 45/143 [00:02<00:06, 14.30it/s]
Tracking:  33%|###2      | 47/143 [00:02<00:06, 15.34it/s]
Tracking:  34%|###4      | 49/143 [00:02<00:05, 16.29it/s]
Tracking:  37%|###7      | 53/143 [00:03<00:04, 20.31it/s]
Tracking:  39%|###9      | 56/143 [00:03<00:04, 19.42it/s]
Tracking:  41%|####1     | 59/143 [00:03<00:03, 21.68it/s]
Tracking:  44%|####4     | 63/143 [00:03<00:03, 25.90it/s]
Tracking:  47%|####6     | 67/143 [00:03<00:02, 29.14it/s]
Tracking:  51%|#####1    | 73/143 [00:03<00:02, 33.96it/s]
Tracking:  54%|#####3    | 77/143 [00:03<00:02, 28.86it/s]
Tracking:  57%|#####6    | 81/143 [00:04<00:02, 27.00it/s]
Tracking:  60%|######    | 86/143 [00:04<00:01, 31.78it/s]
Tracking:  71%|#######   | 101/143 [00:04<00:00, 58.24it/s]
Tracking:  76%|#######5  | 108/143 [00:04<00:00, 60.87it/s]
Tracking:  80%|########  | 115/143 [00:04<00:00, 42.18it/s]
Tracking:  85%|########4 | 121/143 [00:05<00:01, 19.44it/s]
Tracking:  87%|########7 | 125/143 [00:05<00:01, 14.47it/s]
Tracking:  90%|########9 | 128/143 [00:06<00:01, 12.79it/s]
Tracking:  92%|#########1| 131/143 [00:06<00:01, 11.93it/s]
Tracking:  93%|#########3| 133/143 [00:06<00:00, 11.16it/s]
Tracking:  94%|#########4| 135/143 [00:07<00:00, 10.89it/s]
Tracking:  96%|#########5| 137/143 [00:07<00:00, 10.63it/s]
Tracking:  97%|#########7| 139/143 [00:07<00:00,  9.75it/s]
Tracking:  99%|#########8| 141/143 [00:07<00:00,  9.22it/s]
Tracking: 100%|##########| 143/143 [00:08<00:00,  8.75it/s]
Tracking: 144it [00:08,  8.54it/s]                         
Tracking: 144it [00:08, 17.20it/s]

save_tracks(output: str | Path) → None

Save tracked data to hdf5 table.

Parameters:

output (Path, str) – Filename where the output will be saved to.

Example

import os
import xarray
from tintx import RunDirectory
files = os.path.join(os.environ["FILE_PATH"], "CPOL*.nc")
dset = xarray.open_mfdataset(files, combine="by_coords")
run = RunDirectory(dset,
                   "radar_estimated_rain_rate",
                   x_coord="longitude",
                   y_coord="latitude")
num_cells = run.get_tracks(field_thresh=0.01)
run.save_tracks("/tmp/output.hdf5")

Tracking:   0%|          | 0/143 [00:00<?, ?it/s]
Tracking:   3%|2         | 4/143 [00:00<00:03, 39.23it/s]
Tracking:   6%|5         | 8/143 [00:00<00:03, 33.82it/s]
Tracking:   8%|8         | 12/143 [00:00<00:04, 28.47it/s]
Tracking:  10%|#         | 15/143 [00:00<00:04, 28.24it/s]
Tracking:  13%|#2        | 18/143 [00:00<00:04, 25.86it/s]
Tracking:  15%|#4        | 21/143 [00:00<00:05, 21.73it/s]
Tracking:  17%|#6        | 24/143 [00:01<00:06, 18.43it/s]
Tracking:  18%|#8        | 26/143 [00:01<00:07, 15.58it/s]
Tracking:  20%|#9        | 28/143 [00:01<00:07, 15.27it/s]
Tracking:  21%|##        | 30/143 [00:01<00:07, 15.53it/s]
Tracking:  22%|##2       | 32/143 [00:01<00:06, 15.96it/s]
Tracking:  24%|##3       | 34/143 [00:01<00:07, 13.78it/s]
Tracking:  25%|##5       | 36/143 [00:02<00:08, 12.13it/s]
Tracking:  27%|##6       | 38/143 [00:02<00:09, 11.08it/s]
Tracking:  28%|##7       | 40/143 [00:02<00:09, 11.07it/s]
Tracking:  30%|###       | 43/143 [00:02<00:07, 13.57it/s]
Tracking:  31%|###1      | 45/143 [00:02<00:06, 14.24it/s]
Tracking:  33%|###2      | 47/143 [00:02<00:06, 15.28it/s]
Tracking:  34%|###4      | 49/143 [00:02<00:05, 16.31it/s]
Tracking:  37%|###7      | 53/143 [00:03<00:04, 20.34it/s]
Tracking:  39%|###9      | 56/143 [00:03<00:04, 19.51it/s]
Tracking:  41%|####1     | 59/143 [00:03<00:03, 21.79it/s]
Tracking:  44%|####4     | 63/143 [00:03<00:03, 25.99it/s]
Tracking:  47%|####6     | 67/143 [00:03<00:02, 29.20it/s]
Tracking:  51%|#####1    | 73/143 [00:03<00:02, 34.12it/s]
Tracking:  54%|#####3    | 77/143 [00:03<00:01, 34.54it/s]
Tracking:  57%|#####6    | 81/143 [00:03<00:02, 30.25it/s]
Tracking:  60%|######    | 86/143 [00:04<00:01, 34.65it/s]
Tracking:  71%|#######   | 101/143 [00:04<00:00, 62.07it/s]
Tracking:  76%|#######5  | 108/143 [00:04<00:00, 63.92it/s]
Tracking:  80%|########  | 115/143 [00:04<00:00, 42.97it/s]
Tracking:  85%|########4 | 121/143 [00:05<00:01, 19.64it/s]
Tracking:  88%|########8 | 126/143 [00:06<00:01, 13.96it/s]
Tracking:  91%|######### | 130/143 [00:06<00:01, 12.53it/s]
Tracking:  93%|#########3| 133/143 [00:06<00:00, 11.52it/s]
Tracking:  94%|#########4| 135/143 [00:07<00:00, 11.26it/s]
Tracking:  96%|#########5| 137/143 [00:07<00:00, 10.98it/s]
Tracking:  97%|#########7| 139/143 [00:07<00:00, 10.10it/s]
Tracking:  99%|#########8| 141/143 [00:07<00:00,  9.52it/s]
Tracking: 100%|##########| 143/143 [00:07<00:00,  8.97it/s]
Tracking: 144it [00:08, 17.19it/s]                         
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:82: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.coords.to_hdf(buffer, "dims")
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:83: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.to_dataframe(self._x_coord).to_hdf(buffer, "x_coord")
/home/docs/checkouts/readthedocs.org/user_builds/tintx/checkouts/stable/src/tintx/helpers.py:84: FutureWarning: Starting with pandas version 3.0 all arguments of to_hdf except for the argument 'path_or_buf' will be keyword-only.
  self.to_dataframe(self._y_coord).to_hdf(buffer, "y_coord")

See also

from_dataframe

property tracks: DataFrame

Pandas DataFrame representation of the tracked cells.

Configuring the tracking Algorithm

Tracking tuning parameters

The following parameter can be set to tune the cell tracking algorithm

• field_thresh: units of ‘field’ attribute, default: 32

  The threshold used for object detection. Detected objects are connected pixels above this threshold.

• iso_thresh: units of ‘field’ attribute, default: 4

  Used in isolated cell classification. Isolated cells must not be connected to any other cell by contiguous pixels above this threshold.

• iso_smooth: pixels, default: 4

  Gaussian smoothing parameter in peak detection preprocessing. See single_max in tint.objects.

• min_size: square kilometers, default: 8

  The minimum size threshold in pixels for an object to be detected.

• search_margin: meters, default: 250

  The radius of the search box around the predicted object center.

• flow_margin: meters, default: 750

  The margin size around the object extent on which to perform phase correlation.

• max_disparity: float, default: 999

  Maximum allowable disparity value. Larger disparity values are sent to a large number.

• max_flow_mag: meters per second, default: 50

  Maximum allowable global shift magnitude. See get_global_shift in tint.phase_correlation.

• max_shift_disp: meters per second, default: 15

  Maximum magnitude of difference in meters per second for two shifts to be considered in agreement. See correct_shift in tint.matching.

• gs_alt: meters, default: 1500

  Altitude in meters at which to perform phase correlation for global shift calculation. See correct_shift in tint.matching.

Setting and getting the tuning parameters

The parameters can the set using the tintx.config.set class. Getting the values of the currently set parameters can be done by the tintx.config.get() method.

tintx.config.get(key: str, default: float | None = None) → float | None

Get elements from global tinitX config

Examples

from tintx import config
print(config.get('min_size'))

8.0

from tintx import config
print(config.get('bar', default=123.))

123.0

See also

tintx.config.set

class tintx.config.set(**kwargs: float)

Bases: object

Set tint configuration values within a context manager

Parameters:

**kwargs (float) – key-value pairs of the config values to set.

Example

Set field_thresh parameter in a context. After the with block the parameter will be set back to its original value.

from tintx import config
with config.set(field_thresh=5):
    print(config.get("field_thresh"))
print(config.get("field_thresh"))

5.0
32.0

To make the configuration changes persistent you can use set without the with block:

import tintx
tintx.config.set(field_thresh=5)

See also

tintx.config.get

get(key: str, default: float | None = None) → float | None

Convenience method to retrieve elements from the tinitx configuration

Examples

from tintx import config
with config.set(field_thresh=5) as cfg:
    print(cfg.get("field_thresh"))

5.0