TfvParticle¶

class tfv.xarray.TfvParticle(xarray_obj)¶

Xarray accessor object for working with TUFLOW FV particle datasets.

Create regularized grid of particle data

Parameters:

time – Time selection. Can be index, timestamp, or slice
bbox – Bounding box (xmin, ymin, xmax, ymax)
datum (['sigma', 'height', 'depth', 'elevation'], optional) – vertical selection datum. Defaults to ‘elevation’. Choose from height, depth, elevation or sigma. Note that a depth variable must be present to use anything other than elevation
limits (tuple, optional) – vertical selection limits. Defaults to None.
dx – Grid spacing in each dimension
dy – Grid spacing in each dimension
dz – Grid spacing in each dimension
nx – Number of grid cells in each dimension
ny – Number of grid cells in each dimension
nz – Number of grid cells in each dimension
group_ids – Filter by group IDs
stats – Filter by status values
density – If True, add normalised density as additional variable. Defaults to False.
variables – Variables to grid (defaults to density only)
agg – Aggregation method (‘mean’, ‘sum’)

Returns:

Gridded dataset with dimensions (time, z, y, x)

Return type:

xr.Dataset

Extract filtered particle dataset

Parameters:

time – Time selection. Can be: - Integer index - String timestamp (e.g., ‘2010-01-01’) - Pandas Timestamp - Slice of any of the above
bounds – Horizontal bounds for filtering particles. Can be: - Tuple[float, float, float, float]: Bounding box (xmin, ymin, xmax, ymax) - shapely.geometry.Polygon: Polygon geometry - np.ndarray: Nx2 array of polygon vertices
datum (['sigma', 'height', 'depth', 'elevation'], optional) – vertical selection datum. Defaults to ‘elevation’. Choose from height, depth, elevation or sigma. Note that a depth variable must be present to use anything other than elevation
limits (tuple, optional) – vertical selection limits. Defaults to None.
age_bounds – Age bounds in hours (min_hours, max_hours). Use None in tuple for open-ended bounds Examples: - (0, 6): Particles up to 6 hours old - (6, None): Particles older than 6 hours - (6, 12): Particles between 6 and 12 hours old
group_ids – Single group ID or multiple group IDs to include
stats – Single status value or multiple status values to include
stride – Sample every nth particle. Must be >= 1. Defaults to 1.

Returns:

Filtered particle accessor (ds.tfv on the underlying dataset).

Return type:

TfvParticle

plot(time: str | Timestamp | int = -1, plot_type: Literal['scatter', 'hist'] = 'scatter', colorbar: bool = True, ax: matplotlib.pyplot.Axes | None = None, size_by: str | None = None, color_by: str | None = None, colorbar_kwargs: dict = {}, bounds: Tuple[float, float, float, float] | shapely.Polygon | ndarray | None = None, limits: Tuple[float, float] | None = None, datum: str = 'elevation', group_ids: int | List[int] | Tuple[int, ...] | None = None, stats: int | List[int] | Tuple[int, ...] | None = None, stride: int = 1, age_bounds: Tuple[float, float] | None = None, **kwargs) → ParticleScatter | ParticleHist¶

General particle plotting method.

This function provides flexible visualisation options for TUFLOW FV particle data. By default, it creates a scatter plot of particles coloured by group ID, but can also generate 2D histogram plots showing particle density or other statistics.

Parameters:

time (str, pd.Timestamp or int, optional) – Timestep to plot. Can be an index, timestamp, or string.
plot_type ({'scatter', 'hist'}, optional) – Type of plot to create. 'scatter' creates a scatter plot of individual particles. 'hist' creates a 2D histogram showing particle density or another statistic.
colorbar (bool, optional) – Whether to include a colorbar for the plot.
ax (matplotlib.pyplot.Axes, optional) – Matplotlib axis to draw on. If None, a new figure is created.
size_by (str, optional) – Variable to scale point sizes by for scatter plots.
color_by (str, optional) – Variable to colour points or histogram cells by. For scatter plots, defaults to 'groupID'.
colorbar_kwargs (dict, optional) – Additional arguments for colorbar customisation. Accepts label to override the default colorbar label.
bounds (tuple, shapely.geometry.Polygon or np.ndarray, optional) – Horizontal bounds for filtering particles. Tuple bounds are interpreted as (xmin, ymin, xmax, ymax).
limits (tuple, optional) – Vertical selection limits as (min, max).
datum ({'elevation', 'height', 'depth', 'sigma'}, optional) – Vertical selection datum. 'depth' requires a depth variable to be present.
group_ids (int or sequence of int, optional) – Filter by specific group IDs.
stats (int or sequence of int, optional) – Filter by status values.
stride (int, optional) – Sample every nth particle to reduce dataset size.
age_bounds (tuple, optional) – Age bounds in hours as (min_hours, max_hours).
**kwargs – Additional arguments passed to plotting functions. For plot_type='hist', supported arguments include bbox, dx, dy, nx, ny, and statistic. The statistic can be one of 'mean', 'count', 'density', 'median', 'min', 'max', 'std', or any NumPy-compatible aggregation function.

Returns:

The visualisation object created. Use the returned object to dynamically update the plot, e.g. vis.update(time_idx).

Return type:

ParticleScatter or ParticleHist

plot_interactive(time: str | Timestamp | int = -1, plot_type: Literal['scatter', 'hist'] = 'scatter', ax: matplotlib.pyplot.Axes | None = None, widget=None, bbox: Tuple[float, float, float, float] | None = None, dx: float | None = None, dy: float | None = None, nx: int = 100, ny: int = 100, statistic: str = 'mean', **kwargs) → None¶

Interactive particle plotting method for fast result viewing.

It is recommended that you choose a time to begin plot on otherwise there is no basis for sensible x and y limits. It defaults to the final timestep, which may be too large a domain (i.e., particles very dispersed).

This function requires matplotlib to be using an ipympl backend. Please first run %matplotlib widget before using this function.

Parameters:

time – Timestep to start plot. Can be: - Integer index - String timestamp (e.g., ‘2010-01-01’) - Pandas Timestamp Defaults to -1 (last timestep).
plot_type – Type of plot (‘scatter’ or ‘hist’). Defaults to ‘scatter’.
ax – Matplotlib axis to draw on. Default will create a new figure and axis.
widget – Pre-initialized widget box from prep_interactive_slider.
bbox – Bounding box for histogram (xmin, ymin, xmax, ymax). If None, determined from initial data extent.
dx – Grid spacing in x direction (histogram only). Takes precedence over nx if both are provided.
dy – Grid spacing in y direction (histogram only). Takes precedence over ny if both are provided.
nx – Number of grid cells in x (used if dx not provided). Defaults to 100.
ny – Number of grid cells in y (used if dy not provided). Defaults to 100.
statistic – Statistic to compute for color_by variable in histogram plots.
**kwargs – Additional keyword arguments passed to plot() including: - datum: Vertical selection datum (‘elevation’, ‘height’, ‘depth’, ‘sigma’) - limits: Vertical selection limits (tuple) - bounds: Horizontal bounds for filtering particles - group_ids: Filter by specific group IDs - stats: Filter by status values - stride: Sample every nth particle - age_bounds: Age bounds in hours - color_by, size_by, colorbar: Plot customization options

prep_interactive_slider()¶: Prepare an interactive ipympl widget box for controlling plot_interactive