Example 1. Basic usage with the TfvDomain Xarray accessor¶

This notebook provides a high-level view on the typical usage of the TfvDomain xarray accessor tool.

To try this out for yourself, you can get a copy of the TUFLOW FV tutorial model result file from here:

import xarray as xr  # We utilise xarray to do all the heavy lifting 
import tfv.xarray

Some Common Use Examples¶

Spatial Plots¶

By default, the tool will plot the first variable it finds, with the first timestep it finds.

For many model results, this will be surface elevation at the first timestep.

fv.plot()

<tfv.visual.SheetPatch at 0x176448a60>

../../_images/f342fd8ebf2838d621bd505a05d8203404d1a4ec12584e27ad6a32e02184c77f.png

You can add lots of arguments to style plots to your liking. There is also some magic behind the scenes - if you have V_x and V_y in your dataset, you can request V or VDir directly.

fv.plot('V', '2011-02-04 02:00', cmap='turbo', clim=(0, 0.25), datum='depth')

# Other things to try:
# Depth-averaging, e.g., datum=["sigma", "height", "depth"], combined with limits
# Shading = ["interp", "patch", "contour"]

# Time can be provided as a str, a Timestamp object, or a simple integer.

<tfv.visual.SheetPatch at 0x16b32f6a0>

../../_images/07e5f7169070cc4a2314826489852c325cdf54909b93d4e42ae0991713c8ab15.png

All the plotting methods can be embedded in normal matplotlib figures, so you can create complex plots.

Here is a very simple example and which provides some building blocks you might use.

import matplotlib.pyplot as plt

# With datum='depth', this is the surface 1m. 
# experiment with datum='height' to see how the results change. 
datum = 'depth'
limits = (0,1)

fig, axes = plt.subplots(ncols=3, figsize=(12, 6), constrained_layout=True)

ts = '2011-02-05 02:00'

ax = axes[0]
p1 = fv.plot('V', ts, ax=ax,  shading='interp', cmap='turbo', clim=(0, 0.25), datum=datum, limits=limits, colorbar=False)  # By setting datum to depth, this is now the "surface 1m")
v1 = fv.plot_vector('V', ts, ax=ax, color='k')   # We can plot a vector overlay using the `plot_vector` method here
ax.set_title('Velocity')
plt.colorbar(p1.patch, ax=ax, orientation='horizontal', label='Speed (m/s)')

ax = axes[1]
p2 = fv.plot('SAL', ts, ax=ax,  shading='interp', cmap='ocean', clim=(0, 36), datum=datum, limits=limits, colorbar=False)
ax.set_title('Salinity')
plt.colorbar(p2.patch, ax=ax, orientation='horizontal', label='Salinity (PSU)')

ax = axes[2]
p3 = fv.plot('TEMP', ts, ax=ax, shading='interp', cmap='plasma', clim=(5, 25), datum=datum, limits=limits, colorbar=False)
ax.set_title('Temperature')
plt.colorbar(p3.patch, ax=ax, orientation='horizontal', label='Temp (°C)')

plt.show()

../../_images/8a045bf6df138de04b848bc49d496497541f9b9a4b42389726073965f486fff3.png

Interactive Plotting¶

The tfv tools work great in interactive python, such as with Jupyterlab.

Often we jsut want to interactively look at our model results to ensure that everything is working well, or to understand the results. We can use the plot_interactive method to enable animated plotting so we can dig deeper into the results.

In general, the arguments to the plot_interactive method are the same as the plot method. We can also add on vectors, and setup multiple plots. This is covered in another tutorial.

We first need to turn on interactive plotting by enabling matplotlib in widget model - run this once %matplotlib widget. You may need to install ipympl if this fails.

%matplotlib widget

Output hidden because it doesn’t render nicely in on tutorial page

fv.plot_interactive('V', cmap='turbo', clim=(0,0.5), datum='depth', vectors=True)
plt.show()

To turn off interactive plotting (which can often make your sessions run faster, a good idea when you don’t need it), use %matplotlib inline

%matplotlib inline

Extracting and plotting timeseries¶

To grab a timeseries from the model domain result, we can provide either a simple tuple with (X,Y), or a dictionary with some named locations.

For example, we may wish to extract two timeseries at “P1” and “P2”, which we then want to plot and convert to a pandas dataframe. By default, we’ll always be returned with Xarray objects, but these are easily converted by calling the .to_dataframe() method

locs = {
    'P1': (159.1, -31.39), 
    'P2': (159.115, -31.395), 
}

ts = fv.get_timeseries(['H', 'V', 'TEMP'], locs)
ts_df = ts.to_dataframe()

# Output hidden because progress bar's don't render nicely here! 

ts_df.head()

		x	y	z	H	V	TEMP
Time	Location
2011-02-01 00:00:00.000000000	P1	159.100	-31.390	-1.067781	-0.001545	0.000000	20.000000
2011-02-01 00:00:00.000000000	P2	159.115	-31.395	-4.886311	-0.000878	0.000000	20.000001
2011-02-01 01:00:17.809977600	P1	159.100	-31.390	-1.067781	0.049078	0.053110	19.960014
2011-02-01 01:00:17.809977600	P2	159.115	-31.395	-4.886311	0.108249	0.037206	19.989328
2011-02-01 02:00:00.263494800	P1	159.100	-31.390	-1.067781	-0.091997	0.003442	19.927108

ts['V'][:, 1].plot()

[<matplotlib.lines.Line2D at 0x176473940>]

../../_images/25341b2a2d706417545328f44b5020fdaae7037083e0009c7806a98d4ddda18e.png

Exporting new results¶

You can use Xarray to export results back to netcdf.

Common examples might be to load up a very large TUFLOW FV result here in Python, do some post-processing (e.g., some statistics?), or slice it to a smaller time period, and then use the to_netcdf method to export it back. Results exported in this manner will be formatted as any normal TUFLOW FV result, and can be loaded into QGIS, for example.

As an example, we can chop our result into something much smaller, like this:

fv_small = fv.isel(Time=slice(10, 20))  # Here we've used an `Xarray` native function - isel. This selected the 10th through to 19th timestep. 
fv_small.to_netcdf('my_smaller_netcdf.nc')
# fv_small

This concludes the basic usage tutorial

Example 1. Basic usage with the TfvDomain Xarray accessor¶

Loading data¶

Some Common Use Examples¶

Spatial Plots¶

Interactive Plotting¶

Extracting and plotting timeseries¶

Sheet Timeseries¶

Built-in statistics¶

Exporting new results¶