TfvDomain

class tfv.xarray.TfvDomain(xarray_obj)

Xarray accessor object for working with TUFLOW FV domain (spatial) netcdf files.

Extends the functionality of native xarray to add methods that assist with typical analyses.

To use this, call .tfv on an xarray dataset based on a TUFLOW FV domain file.

get_curtain(polyline: ndarray, variables: Union[str, list], time: Optional[Union[str, int, Timestamp, slice]] = None)

Extract a 2D curtain timeseries, returned as an Xarray dataset.

Note

This is a work-in-progress method, and is not directly used in any other methods currently. If you wish to just view curtain plots, please use the plot_curtain method.

Parameters

  • polyline (np.ndarray) – a Nx2 array containing the X and Y coordinates to extract the curtain over.

  • variables ([str, list]) – single or list of variables to extract

  • time ([str, pd.Timestamp, int, slice], optional) – time indexer for extraction. Defaults to the entire dataset.

Returns

Xarray dataset object

Return type

xr.Dataset

get_profile(point: Union[tuple, dict], time: Optional[slice] = None, variables: Optional[list[str]] = None)

Extract profile timeseries at a single location

Simple method to extract a profile timeseries at a single location. This returns a native Xarray dataset, and does not have the methods available using the TfvTimeseries Xarray accessor.

Parameters

  • point ([tuple, dict]) – Single location to extract profile as a tuple (X,Y) or dictionary dict(loc_01=(X,Y)).

  • time ([str, pd.Timestamp, int, slice], optional) – time indexer for extraction. Defaults to the entire dataset.

  • variables (list[str], optional) – List of variables. Defaults to all variables.

Returns

a native Xarray dataset containing the profile timeseries.

Return type

xr.Dataset

get_sheet(variables: Union[str, list], time: Optional[Union[str, int, Timestamp, slice]] = None, datum: Literal['sigma', 'height', 'depth', 'elevation'] = 'sigma', limits: tuple = (0, 1), agg: Literal['min', 'mean', 'max'] = 'mean')

Extract a 2D sheet timeseries

General purpose method for extracting 2D sheet data from a TfvDomain object. This will handle dimension reduction of 3D variables (by default will average over the depth column, i.e., depth-averaged), as well as handling single or multiple timesteps or slices.

Parameters

  • variables ([str, list]) – variables to extract. (“V” or “VDir” may be requested if “V_x” and “V_y” are present)

  • time ([str, pd.Timestamp, int, slice], optional) – time indexer for extraction. Defaults to the entire dataset.

  • datum (['sigma', 'height', 'depth', 'elevation'], optional) – depth-averaging datum. Defaults to ‘sigma’. Choose from height, depth, elevation or sigma.

  • limits (tuple, optional) – depth-averaging limits. Defaults to (0,1).

  • agg (['min', 'mean', 'max'], optional) – depth-averaging aggregation function. Defaults to ‘mean’. Choose from min, mean, or max.

Returns

new TfvDomain object with the requested timeseries variables

Return type

TfvDomain

get_statistics(stats: list[str], variables: Union[list, str], time: Optional[slice] = None, datum: str = 'sigma', limits: tuple = (0, 1), agg: str = 'mean', fillna=None, skipna=True)

Extract statistics on 2D variables.

General purpose method for extracting statistics using typical statistic functions (e.g., ‘mean’, ‘max’…).

Percentiles can be obtained using the string format ‘pX’ (e.g., for 10th and 90th: stats = [‘p10’, ‘p90’]).

This function will first call get_sheet to obtain the data for calculating statistics on. All arguments for get_sheet can be passed through to this method.

Parameters

  • stats (list[str]) – list of statistics, e.g., [‘min’, ‘mean’, ‘p50’, ‘p95’]

  • variables ([list, str]) – variables to do statistics on

  • time ([list, slice], optional) – time indexer (e.g., slice(50) for the first 50 timesteps, or slice(‘2012-01-01’, ‘2012-02-01’))

  • datum (['sigma', 'height', 'depth', 'elevation'], optional) – depth-averaging datum. Defaults to ‘sigma’. Choose from height, depth, elevation or sigma.

  • limits (tuple, optional) – depth-averaging limits. Defaults to (0,1).

  • agg (['min', 'mean', 'max'], optional) – depth-averaging aggregation function. Defaults to ‘mean’. Choose from min, mean, or max.

  • fillna (float, optional) – Fill nan values (e.g., dried out cells) with this value before doing statistics. Defaults to None.

  • skipna (bool, optional) – Skip nan values. Defaults to True.

Returns

new TfvDomain object with the requested timeseries variables

Return type

TfvDomain

get_timeseries(variables: Union[str, list], points: Union[tuple, dict], time: Optional[Union[str, int, Timestamp, slice]] = None, datum: Literal['sigma', 'height', 'depth', 'elevation'] = 'sigma', limits: tuple = (0, 1), agg: Literal['min', 'mean', 'max'] = 'mean')

Get timeseries at point location(s) in the model

Parameters

  • variables ([str, list]) – variables to extract.

  • points ([tuple, dict]) – locations to extract (e.g., a tuple (x,y) or a dict {‘name’: (x,y), …})

  • time ([str, pd.Timestamp, int, slice], optional) – time indexer for extraction. Defaults to the entire dataset.

  • datum (['sigma', 'height', 'depth', 'elevation'], optional) – depth-averaging datum. Defaults to ‘sigma’. Choose from height, depth, elevation or sigma.

  • limits (tuple, optional) – depth-averaging limits. Defaults to (0,1).

  • agg (['min', 'mean', 'max'], optional) – depth-averaging aggregation function. Defaults to ‘mean’. Choose from min, mean, or max.

Returns

A timeseries dataset in xarray format

Return type

xr.Dataset

plot(variable: Optional[str] = None, time: Union[str, Timestamp, int] = 0, colorbar=True, shading='patch', ax: Optional[Axes] = None, **kwargs)

General 2D sheet plot method

By default, this function will plot the first variable and timestep.

This function is a general wrapper around the tfv.visual “Sheet” methods. Kwargs will be supplied through to the underlying matplotlib function.

Depth-averaging logic can be handled by passing through the optional keywords datum, limits, agg as required.

Several magic “variables” are available via this method including:

  • Plot bed elevation using variable ‘Zb’

  • Plot current speed or direction using either ‘V’ or ‘VDir’ respectively

Parameters

  • variable (str, optional) – variable to plot. Defaults to alphabetical first.

  • time ([str, pd.Timestamp, int], optional) – Timestep to plot, provided as str (e.g., ‘2010-01-01’), int, Timestamp object, etc. Defaults to 0.

  • colorbar (bool, optional) – Show colorbar (best to turn off if making subplots). Defaults to True.

  • shading (str, optional) –

    Figure shading type, which changes the underlying matplotlib function. Options include:

    ”patch” that calls tfv.visual.SheetPatch and Matplotlib’s PolyCollection “interp” that calls tfv.visual.SheetPatch and Matplotlib’s TriMesh “contour” that calls tfv.visual.SheetContour and Matplotlib’s TriContourSet

    Defaults to “patch”.

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • kwargs (dict, optional) – Keyword arguments. These are passed to the underlying matplotlib method if not a tfv specific method (e.g., depth averaging kwargs). Common examples include: cmap, clim, levels, norm, datum, limits, agg

Returns

tfv.visual.Sheet<X> Object, depending on the shading option.

Return type

Sheet

plot_curtain(polyline: ndarray, variable: Optional[str] = None, time: Union[str, Timestamp, int] = 0, ax: Optional[Axes] = None, colorbar=True, **kwargs)

General 2D curtain plot method

By default, this function will plot the first variable and timestep. A polyline is always required.

This function is a general wrapper around the tfv.visual.CurtainPatch method. kwargs will be supplied through to the underlying matplotlib function.

A polyline (Nx2 numpy.ndarray) needs to be supplied containing the X and Y coordinates in columns 0 and 1 respectively.

Parameters

  • polyline (np.ndarray) – a Nx2 array containing the X and Y coordinates to extract the curtain over.

  • variable (str, optional) – variable to plot. Defaults to ‘V’ if available, otherwise the first variable alphabetically.

  • time ([str, pd.Timestamp, int], optional) – Timestep to plot, provided as str (e.g., ‘2010-01-01’), int, Timestamp object, etc. Defaults to 0.

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • colorbar (bool, optional) – Show colorbar (best to turn off if making subplots). Defaults to True.

Returns

tfv.visual.CurtainPatch object

Return type

CurtainPatch

plot_curtain_interactive(polyline: ndarray, variable: str, ax: Optional[Axes] = None, vectors: bool = False, vector_kwargs={}, widget=None, **kwargs)

2D interactive matplotlib method for fast curtain viewing.

This function wraps the .plot_curtain and .plot_curtain_vector methods, with kwargs passed directly through to these methods. (see TfvDomain.plot_curtain e.g., ds.tfv.plot and TfvDomain.plot_curtain_vector e.g., ds.tfv.plot_curtain_vector).

A polyline (Nx2 numpy.ndarray) needs to be supplied containing the X and Y coordinates in columns 0 and 1 respectively.

This function requires matplotlib to be using an ipympl backend, typically in a Jupyter lab/notebook environment. Please first run %matplotlib widget before using this function.

Parameters

  • polyline (np.ndarray) – a Nx2 array containing the X and Y coordinates to extract the curtain over.

  • variable (str) – Variable to plot

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • vectors ([bool, list, tuple], optional) – Flag to draw vectors. If True, the vectors will represent projected velocity (V_x, V_y projected to the curtain plane). Vertical velocity, W, will be included automatically if available in the model.

  • vector_kwargs (dict, optional) – a dictionary of kwargs that is passed directly through to the TfvDomain.plot_curtain_vector object.

  • widget (tuple, optional) – A pre-initalised ipympl widget box, generated using TfvDomain.prep_interactive_slider. This can be used to control multiple subplots using the single widget controller. Defaults to None.

  • kwargs (dict, optional) – Keyword arguments passed directly to TfvDomain.plot_curtain

plot_curtain_vector(polyline: ndarray, time: Union[str, Timestamp, int] = 0, variables: Optional[Union[list, tuple]] = None, ax: Optional[Axes] = None, tangential=True, **kwargs)

General 2D curtain vector plot method

This method is designed to draw velocity vectors over a curtain. If W (vertical velocity) is available in the TUFLOW FV dataset, these vectors will be scaled to show vertical motion as well. To avoid vertical velocity scaling of the vectors, specify tangential=False as well.

Note

This method accepts a variables kwarg so that custom variables can be supplied, which will be scaled with vertical velocity W if present. To avoid this behaviour, also specify tangential=False.

This function is a general wrapper around the tfv.visual.CurtainVector method. kwargs will be supplied through to the underlying matplotlib function.

A polyline (Nx2 numpy.ndarray) needs to be supplied containing the X and Y coordinates in columns 0 and 1 respectively.

Parameters

  • polyline (np.ndarray) – a Nx2 array containing the X and Y coordinates to extract the curtain over.

  • time ([str, pd.Timestamp, int], optional) – Timestep to plot, provided as str (e.g., ‘2010-01-01’), int, Timestamp object, etc. Defaults to 0.

  • variables ([list, tuple], optional) – Variables to create vector (X-comp, Y-comp). Defaults to None.

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • tangential (bool, optional) – Flag to scale vectors vertically using W, if present. Defaults to True.

Returns

tfv.visual.CurtainVector object.

Return type

CurtainVector

plot_interactive(variable: str, ax: Optional[Axes] = None, vectors: Union[bool, list, tuple] = False, vector_kwargs={}, widget=None, **kwargs)

2D interactive matplotlib plotting method for fast result viewing.

This function wraps the .plot and .plot_vector methods, with kwargs passed directly through to these methods. (see TfvDomain.plot e.g., ds.tfv.plot and TfvDomain.plot_vector e.g., ds.tfv.plot_vector).

This function requires matplotlib to be using an ipympl backend, typically in a Jupyter lab/notebook environment. Please first run %matplotlib widget before using this function.

Parameters

  • variable (str) – Variable to plot

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • vectors ([bool, list, tuple], optional) – Flag to draw vectors. If a boolean (True) is supplied, the vectors will be velocity (V_x, V_y). A list/tuple of variable names can be supplied as required (E.g., W10_x, W10_y). Defaults to False.

  • vector_kwargs (dict, optional) – a dictionary of kwargs that is passed directly through to the TfvDomain.plot_vector object.

  • widget (tuple, optional) – A pre-initalised ipympl widget box, generated using TfvDomain.prep_interactive_slider. This can be used to control multiple subplots using the single widget controller. Defaults to None.

  • kwargs (dict, optional) – Keyword arguments passed directly to TfvDomain.plot

plot_vector(variables: Optional[Union[list, tuple]] = None, time: Union[str, Timestamp, int] = 0, plot_type: Literal['quiver'] = 'quiver', ax: Optional[Axes] = None, **kwargs)

General 2D vector plot method

Generic method to call tfv.visual’s SheetVector. This can be used to overlay vector plots on other figures. By default, this method will plot vectors using V_x and V_y to give velocity vectors, however a list/tuple of an x/y component can be provided.

kwargs passed to this function are supplied to the underlying matplotlib function (e.g., Quiver or Streamplot). The default vector scaling for velocity is usually ok; however in some cases you may need to scale the vectors (e.g., scale=100).

Vectors can also be set to a uniform length using normalised=True.

Depth-averaging logic can be handled by passing through the optional keywords datum, limits, agg as required.

Parameters

  • variables ([list, tuple], optional) – Variables to create vector (X-comp, Y-comp). Defaults to None.

  • time ([str, pd.Timestamp, int], optional) – Timestep to plot, provided as str (e.g., ‘2010-01-01’), int, Timestamp object, etc. Defaults to 0.

  • plot_type (Literal['quiver'], optional) – _description_. Defaults to “quiver”.

  • ax (plt.Axes, optional) – Matplotlib axis to draw on. Default will create a new figure and axis.

  • kwargs (dict, optional) – Keyword arguments. These are passed to the underlying matplotlib method if not a tfv specific method (e.g., depth averaging kwargs). Common examples include: scale, normalised, datum, limits, agg.

Returns

tfv.visual.SheetVector object.

Return type

SheetVector

prep_interactive_slider()

Prepare an interactive ipympl widget box for controlling TfvDomain.plot_interactive

This method pre-initialises a widget box that can be used to control the interactive jupyter plotting method, and is called by default from the plot_interactive method.

To control multiple interactive plots using the one widget box, first call this method, e.g. widget=ds.tfv.prep_interactive_slider(), and then pass this widget through to the plot_interactive method.