FvExtractor

class tfv.extractor.FvExtractor(file: Path | str | xarray.Dataset, lazy_load: bool = True, is_spherical: bool = True, warmup: str | Timedelta = '0D')

Class that extracts data from a TUFLOW FV netCDF4 result file.

Parameters:

• file (string) – Model result file path.

• is_spherical (bool) – True if model geometry defined in spherical coordinate reference system.

nc2

Number of 2D mesh cells

Type:

int

nv2

Number of 2D mesh vertices

Type:

int

is_tri

Logical index of triangular elements

Type:

1D np.ndarray

is_quad

Logical index of quadrilateral elements

Type:

1D np.ndarray

edge_node

Tuple defining start node, end node and cell for each mesh half edge

Type:

tuple

weights

A (n, 4) array defining weighting of each cell gives to each mesh vertex

Type:

2D np.ndarray

tri_cell_node

A (n, 3) array defining each mesh cell/element by three node indices

Type:

2D np.ndarray

tri_cell_index

A (n,) array mapping triangular mesh elements to base mesh elements

Type:

1D np.ndarray

nc

Dataset object

Type:

netCDF4.Dataset

nz

A (nc2,) array defining number of vertical cells in each 2D model mesh cell

Type:

np.ndarray

idx2

A (nc3,) array defining the 2D model mesh cell index for each 3D cell

Type:

np.ndarray

idx3

A (nc2,) array defining the surface 3D model mesh cell index for each 2D model mesh cell

Type:

np.ndarray

idx4

A (nc3+nc2,) array defining the 2D model mesh cell index for each 3D vertical layer face

Type:

np.ndarray

wli

A (nc2,) array defining the surface vertical layer face index for each 2D model mesh cell

Type:

np.ndarray

bli

A (nc2,) array defining the bed vertical layer face index for each 2D model mesh cell

Type:

np.ndarray

get_curtain_cell(**kwargs)

Query to extract data in a 2D slice format (‘curtain’) at the cell centroids for a given time step. It does this along the polyline specified.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• polyline (2D np.ndarray) – Polyline as [x, y] used to slice 3D data.

• x_data (tuple) – Model edge intersection(x) data returned by self.get_intersections.

• index (tuple) – Curtain index data returned by self.get_curtain_cell_index.

Returns:

data – A 2D slice ‘curtain’ of the relevant variable at time step ii.

Return type:

np.ndarray

get_curtain_cell_geo(ii: int, polyline: ndarray, x_data: tuple | None = None, index: tuple | None = None, return_unit_vector=False, crs=None)

Query to extract geometry data for a 2D vertical slice (‘curtain’) along a given polyline.

Parameters:

• ii (integer) – Time index at which to extract the data.

• polyline (2D np.ndarray) – Polyline as [x, y] used to slice 3D data.

• x_data (tuple) – Model edge intersection(x) data returned by self.get_intersections.

• index (tuple) – Curtain index data returned by self.get_curtain_cell_index.

• crs (int) – EPSG Code for accurate transformations from spherical coordinates. Not necessary if model is non-spherical

Returns:

geo – A tuple containing the geometry of the 2D vertical slice as (node_x, node_y, cell_node).

Return type:

tuple

get_curtain_cell_index(polyline: ndarray, x_data: tuple | None = None)

Query to extract 3D cell indices of 2D vertical slice (‘curtain’) for a given polyline.

Parameters:

• polyline (2D np.ndarray) – Polyline as [x, y] used to slice 3D data.

• x_data (tuple) – Model edge intersection(x) data returned by self.get_intersections.

Returns:

index – Index data defined by line index & cell index (line_index, cell_index). The line index provides the 1D polyline segment indices for each cell in the 2D vertical slice. The cell index provides the 3D model cell indices for each cell in the 2D vertical slice.

Return type:

tuple

get_curtain_edge()

Query to extract data in a 2D slice format (‘curtain’) at the cell centroids for a given time step. It does this along the polyline specified.

This function is currently not supported.

get_curtain_grid(variable: str, ii: int, polyline: ndarray, xg, yg, x_data=None, index=None, grid_index=None)

Query to extract data in a 2D slice format (‘curtain’) at fixed grid points for a given time step. It does this along the polyline specified.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• polyline (2D np.ndarray) – Polyline as [x, y] used to slice 3D data.

• grid_x (1D np.ndarray) – Horizontal grid point values

• grid_y (1D np.ndarray) – Vertical grid point values

• x_data (tuple) – Model edge intersection(x) data returned by self.get_intersections.

• index (tuple) – Curtain index data returned by self.get_curtain_cell_index.

• grid_index (2D np.ndarray) – Curtain cell index for each grid point

Returns:

data – A gridded 2D slice ‘curtain’ of the relevant variable at time step ii.

Return type:

2D np.ndarray

get_integral_data(ii: int, datum: str, limits: tuple, lfz=None)

Query to extract data for vertical integration at given time step. Principle data is the integral limit (z2 - z1) for each 2D model cell/node and dz for each 3D model cell/node.

Parameters:

• ii (integer) – Time index at which to extract the vertical layer faces.

• datum (str) – {‘sigma’, ‘depth’, ‘height’, ‘elevation’} Vertical depth-averaging datum i.e sigma, depth, height, elevation, top, bottom.

• limits (tuple) – Vertical depth-averaging limits (z1, z2) relative to vertical datum.

Returns:

z_data – The elevation limits (z2 - z1) for each 2D cell/node & dz for each 3D cell/node

Return type:

tuple, (z2_z1, dz)

get_mask_vector(ii: int)

Query to extract an array that defines invalid model data.

Parameters:

ii (integer) – Time index at which to extract the stat array.

Returns:

mask – Logical index, True if model cells/nodes are invalid (i.e dry cells).

Return type:

np.ndarray

get_profile_cell(**kwargs)

Query to extract data as 1D vertical profile of cells at the given time step. It does this at the point specified.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• point (tuple) – Point (x, y) of profile location.

• index (integer) – Index of cell which contains the point.

Returns:

data – A 1D section of the vertical values of the relevant variable.

Return type:

np.ndarray

get_raw_data(variable: str, ii: int)

Query to extract raw data at a time step (if time-varying).

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – The time vector index at which to extract the data.

Returns:

data – The raw data as 1D or 2D numpy array

Return type:

np.ndarray

get_sheet_cell(**kwargs)

Query to extract data in a 2D map format (‘sheet’) at model cell centroids for a given time step. If model data is 3D then it is depth-averaged according to the depth-averaging vertical datum and vertical limits.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• datum ({'sigma', 'depth', 'height', 'elevation'}) – Vertical depth-averaging datum i.e sigma, depth, height, elevation, top, bottom.

• limits (tuple) – Vertical depth-averaging limits (z1, z2) relative to vertical datum.

• z_data (tuple, optional) – Vertical integration data returned by `self.get_integral_data`

Returns:

data – A 2D spatial ‘sheet’ of the relevant variable at time step ii.

Return type:

np.ndarray

get_sheet_grid(variable: str, ii: int, xg: ndarray, yg: ndarray, datum='sigma', limits=(0, 1), agg='mean', z_data: tuple | None = None, grid_index: ndarray | None = None)

Query to extract data in a 2D map format (‘sheet’) at fixed grid points for a given time step. If model data is 3D then it is depth-averaged according to the depth-averaging vertical datum and vertical limits.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• grid_x (1D np.ndarray) – Horizontal grid point values

• grid_y (1D np.ndarray) – Vertical grid point values

• datum ({'sigma', 'depth', 'height', 'elevation'}) – Vertical depth-averaging datum i.e sigma, depth, height, elevation, top, bottom.

• limits (tuple) – Vertical depth-averaging limits (z1, z2) relative to vertical datum.

• z_data (tuple, optional) – Vertical integration data returned by self.get_integral_data

• grid_index (2D np.ndarray) – Mesh cell index for each grid point returned by self.get_grid_index

Returns:

data – A gridded 2D spatial ‘sheet’ of the relevant variable at time step ii.

Return type:

2D np.ndarray

get_sheet_node(**kwargs)

Query to extract data in a 2D map format (‘sheet’) at model cell vertices for a given time step. If model data is 3D then it is depth-averaged according to the depth-averaging vertical datum and vertical limits.

Parameters:

• variable (string) – Name of time varying data set to be extracted.

• ii (integer) – Time index at which to extract the data.

• datum ({'sigma', 'depth', 'height', 'elevation'}) – Vertical depth-averaging datum i.e sigma, depth, height, elevation, top, bottom.

• limits (tuple) – Vertical depth-averaging limits (z1, z2) relative to vertical datum.

• z_data (tuple, optional) – Vertical integration data returned by self.get_integral_data

Returns:

data – A 2D spatial ‘sheet’ of the relevant variable at time step ii.

Return type:

np.ndarray

get_z_layer_faces(ii: int)

Query to extract an array that defines the vertical layer faces of a 3D model.

Parameters:

ii (integer) – Time index at which to extract the vertical layer faces.

Returns:

lfz – Vertical layer faces. If model is 2D returns None.

Return type:

np.darray

write_data_to_ascii(out_file: Path | str, data: ndarray, resolution: float, precision: int = 2, bbox: list | None = None, grid_index: ndarray | None = None)

Query data at cell centroids to gridded raster ASCII file.

Parameters:

• out_file (string) – File path of .asc file to write data to.

• data (1D np.ndarray) – Cell centred TUFLOW FV data as numpy array.

• resolution (float) – Grid resolution at which to output data.

• precision (int) – Output precision as number of decimal places.

• bbox (list, optional) – The bounding box to trim the data with as [left, bottom, right, top].

• grid_index (2D np.ndarray, optional) – Mesh cell index for each grid point returned by self.get_grid_index

write_time_series_file(out_file: Path | str, locations: dict, variables: list | None = None)

Query that writes 2D & 3D point time series data from a TUFLOW FV netCDF4 results file.

Parameters:

• out_file (string) – File path to write time series file.

• locations (dictionary) – Extraction points as dict(SITE_1=(x, y), SITE_2=(x, y)).

• variables (list) – List of variables to extract. Default is all variables