Tutorial 1. TUFLOW FV Post-Processing Using Xarray¶

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

This notebook is used in combination with the TUFLOW FV Python Toolbox (tfv) package. To follow along on your own computer, please download the demonstration notebooks from the TUFLOW Downloads Page. Look for the TUFLOW FV Python Toolbox download. Installation instructions are provided on our TUFLOW FV Python Toolbox Wiki Page.

import xarray as xr  # We utilise xarray to do all the heavy lifting 
import tfv.xarray
from pathlib import Path # We'll also make use of the `pathlib` module to assist with managing file-paths, although this is entirely optional! 

Some Common Use Examples¶

Spatial Plots¶

By default the first variable will be plotted on the first timestep.

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

fv.plot()

<tfv.visual.SheetPatch at 0x295e5cd6dd0>

../../_images/436e1bfbb322b094b093fb32cfb6acbe7a64c0bac4f4c796d095fdda5625105b.png

For further control there are a wide range of arguments to style plots to your liking. For velocity outputs, i.e. if you have V_x and V_y in your dataset, you can request V or VDir directly and the fv.plot functionality will take care of the processing.

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 0x295e64bde90>

../../_images/7184683e85adcdcabcaa74130f635ab494e17f9779f2a1b42e1e73a98eaf2ea0.png

In addition to the simple plots above, all the plotting methods can be embedded in normal matplotlib figures so you have control over how you display your results.

Here is an example that provides some building blocks you might use. It plots velocity, salinity and temperature in the surface 1m on a figure with subplots at 2am on the 5th of February, 2011.

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/e874aba63c60a2f50aec9c79bdf40657f94fd126382fe7de81ecef342e9402af.png

Interactive Plotting¶

The tfv tools work great in interactive Python, such as with JupyterLab.

Often we just 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 review our results.

In general, the arguments to the plot_interactive method are the same as the plot method. We can also add on vectors, and set up 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

plt.close('all')
%matplotlib inline

Extracting and Plotting Timeseries¶

To extract a timeseries from the model domain result we can provide either a simple tuple with (X,Y), or a dictionary with 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, calls to the fv object will 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 bars 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.809976613	P1	159.100	-31.390	-1.067781	0.049078	0.053110	19.960014
2011-02-01 01:00:17.809976613	P2	159.115	-31.395	-4.886311	0.108249	0.037206	19.989328
2011-02-01 02:00:00.263493507	P1	159.100	-31.390	-1.067781	-0.091997	0.003442	19.927108

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

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

../../_images/0625257abfe40e300726e629a46d47d37c33dc17f1c811e7b468ece62fe506a7.png

Exporting New Results¶

You can use xarray to export results back to NetCDF. This is a great feature and allows you to save custom output variables into a TUFLOW FV unstructured mesh format for display in other software such as the TUFLOW Viewer Plugin for QGIS.

Common examples might be to process 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.

As an example, we can trim 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.

Tutorial 1. TUFLOW FV Post-Processing Using Xarray¶

Loading Data¶

Some Common Use Examples¶

Spatial Plots¶

Interactive Plotting¶

Extracting and Plotting Timeseries¶

Sheet Timeseries¶

Built-In Statistics¶

Exporting New Results¶