pytuflow.XMDF.time_series

pytuflow.XMDF.time_series#

XMDF.time_series(locations, data_types, time_fmt='relative', averaging_method=None)#

Extracts time-series data for the given locations and data types.

The locations can be a single point in the form of a tuple (x, y) or in the Well Known Text (WKT) format. It can also be a list of points, or a dictionary of points where the key will be used in the column name in the resulting DataFrame.

The locations argument can also be a single GIS file path e.g. Shapefile or GPKG (but any format supported by GDAL is also supported). GPKG’s should follow the TUFLOW convention if specifying the layer name within the database database.gpkg >> layer. If the GIS layer has a field called name, label, or ID then this will be used as the column name in the resulting DataFrame.

The returned DataFrame will use a single time index and the column names will be in the form of: label/data_type e.g. pnt1/water level.

Parameters:

  • locations (Point | list[Point] | dict[str, Point] | PathLike) – The location to extract the time series data for.

  • data_types (str | list[str]) – The data types to extract the time series data for.

  • time_fmt (str, optional) – The format for the time values. Options are ‘relative’ or ‘absolute’.

  • averaging_method (str, optional) –

    The depth-averaging method to use. Only applicable for 3D results. If None is provided for a 3D result, the current rendering method will be used.

    The averaging methods are:

    • singlelevel

    • multilevel

    • depth

    • height

    • elevation

    • sigma

    The averaging method parameters can be adjusted by building them into the method string in a URI style format. The format is as follows:

    <method>?dir=<dir>&<value1>&<value2>

    Where

    • <method> is the averaging method name

    • <dir> is the direction, top or bottom (i.e. from top or from bottom) - only used by certain averaging methods

    • <value1>, <value2>… are the values to be used in the averaging method (the number required to be passed depends on the averaging method)

    e.g. 'singlelevel?dir=top&1' uses the single level averaging method and takes the first vertical layer from the top. Or 'sigma&0.1&0.9' uses the sigma averaging method and averages values located between the 10th and 90th water column depth.

Returns:

The time series data.

Return type:

pd.DataFrame

Examples

Get the water level time-series data for a given point defined as (x, y):

>>> mesh = ... # Assume mesh is a loaded Mesh result
>>> mesh.time_series((293250, 6178030), 'water level')
    time  pnt1/water level
0.000000               NaN
0.083333               NaN
0.166667               NaN
0.250000               NaN
0.333333               NaN
0.416667               NaN
0.500000               NaN
0.583333               NaN
0.666667         41.561204
0.750000         41.838923
...                    ...
2.666667         41.278006
2.750000         41.239387
2.833334         41.201996
2.916667         41.166462
3.000000         41.128152

Get velocity time-series using all the points within a shapefile:

>>> mesh.time_series('path/to/shapefile.shp', 'vel')
    time  pnt1/velocity
0.000000            NaN
0.083333            NaN
0.166667            NaN
0.250000            NaN
0.333333            NaN
0.416667            NaN
0.500000            NaN
0.583333            NaN
0.666667       0.975577
0.750000       0.914921
...                 ...
2.666667       0.320217
2.750000       0.270925
2.833334       0.233793
2.916667       0.206761
3.000000       0.183721
Contents