FvExtractor

class tfv.extractor.FvExtractor(file: Union[Path, str, xarray.Dataset], lazy_load: bool = True, is_spherical: bool = True, warmup: Union[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: Optional[tuple] = None, index: Optional[tuple] = None, return_unit_vector=False)

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.

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: Optional[tuple] = 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)

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: Optional[tuple] = None, grid_index: Optional[ndarray] = 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: Union[Path, str], data: ndarray, resolution: float, precision: int = 2, bbox: Optional[list] = None, grid_index: Optional[ndarray] = 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: Union[Path, str], locations: dict, variables: Optional[list] = 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