PyTuflow

Class: ResData

Class for TUFLOW time series results.

Initialised as an empty object, or with results with a *.tpc in TUFLOW 2016 release and later or *.info in TUFLOW 2013 release.

import pytuflow as tu


res = tu.ResData()  # initialising as an empty object
# or
res = tu.ResData('M01_5m_001.tpc')  # initialising with results

Methods

Method	Description	Returns
channelConnectionCount ( str Node ID )	Returns the number of channels connected to a given node	int Count
channelConnections ( str Node ID )	Returns a list of the channels connected to a given node	list Channel IDs
channelCount ()	Returns the total number of channels in results	int Count
channelResultTypes ()	Returns a list of all the available result types for channels	list of Result Types
channels ()	Returns a list of all the channels IDs in the results	list Channel IDs
channelsDownstream ( str Node ID )	Returns a list of all the channels downstream of a given node	list Channel IDs
channelsUpstream ( str Node ID )	Returns a list of all the channels upstream of a given node	list Channel IDs
format ()	Returns the result format i.e. '2013' or '2016'	str Format
getAdverseGradients ()	Returns locations of any adverse water level or energy level (if result type available) gradients in long profile. Note getLongProfileData method must be called prior to calling this method	tuple Adverse Water Level Gradient Locations ( list x data, list y data )
		tuple Adverse Energy Level Gradient Locations ( list x data, list y data )
getLongProfileData ( float Timestep, str Result Type, str Channel ID, [optional] str 2nd Channel ID )	Returns long profile data from a given channel to another channel. If no second channel is specified will continue until no further channels downstream	bool Error
		str Message
		tuple Profile Data ( list x values, list y values )
getLongProfileTimeOfMax ()	Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method	list x values
		list y values
getPipes ()	Returns any pipe or culvert data in the current profile. Note getLongProfileData method must be called prior to calling this method	list pipes [ list pipe vertexes [ tuple vertex ( x point, y point ) ] ]
getTimeSeriesData ( str Element, str Result Type, [optional] str domain )	Returns time series data for the given element (1D node, 1D channel, 2D PO, RL) for a the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')	bool Error
		str Message
		tuple time series data ( list x data, list y data )
load ( str filepath )	Loads result file. File formats are *.tpc for TUFLOW release 2016 and later, or *.info for TUFLOW release 2013	bool Error
		str Message
longProfileResultTypes ()	Returns list of available long profile result types	list Result Types
maximum ( str Element, str Result Type, [optional] str Domain )	Returns the maximum result value for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')	bool Error
		str Message
		float Maximum Value
maximumTimestepChange ( str Element, str Result Type, [optional] str Domain )	Returns the maximum change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')	bool Error
		str Message
		float Maximum Value
name ()	Returns the name of the result	str Name
nodeCount ()	Returns the total number of nodes in the results	int Count
nodeDownstream ( str Channel ID )	Returns the name of the downstream node of a given channel	str Node ID
nodeResultTypes ( str Channel ID )	Returns a list of all the available result types for nodes	list Result Types
nodes ()	Returns a list of all the node IDs in the results	list Node IDs
nodeUpstream ( str Channel ID )	Returns the name of the upstream node of a given channel	str Node ID
poNames ()	Returns a list of all the available Plot Output names	list PO ID
poResultTypes ()	Returns a list of all the available Plot Output result types	list Result Types
rlCount ()	Returns the total number of Reporting Locations (of all geometry type) in the results	int Count
rlLineCount ()	Returns the total number of line Reporting Locations in the results	int Count
rlNames ()	Returns a list of all the Reporting Location names	list RL ID
rlPointCount ()	Returns the total number of point Reporting Locations in the results	int Count
rlRegionCount ()	Returns the total number of region Reporting Locations in the results	int Count
rlResultTypes ()	Returns a list of all the available Reporting Location result types	list Result Types
source ()	Returns the full file path to the source result file (*.tpc or *.info)	str Path
timeOfMaximum ( str Element, str Result Type, [optional] str Domain )	Returns the time of maximum for the given element (1D node, 1D channel, 2D PO, RL) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')	bool Error
		str Message
		float Time (hrs)
timeOfMaximumTimestepChange ( str Element, str Result Type, [optional] str Domain )	Returns the time of maximum for change in result value in one timestep for the given element (RL elements supported only) for the given result type. If there are duplicate names between 1D, PO, or RL elements it will give priority return to 1D elements first, PO elements second, and lastly RL elements unless 'domain' variable is explicitly specified (domain options: '1D', '2D', 'RL')	bool Error
		str Message
		float Time (hrs)

channelConnectionCount

channelConnectionCount ( Node ID )
Returns the number of channels connected to a given node

Parameters

Node ID: str

Name or ID of node e.g. 'Chan_A.1'

Returns

Count: int

Number of connected channels

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    node = 'Chan_A.1'
    conn_count = res.channelConnectionCount(node)
    # print to console    
    print('{0} channels connected to {1}'.format(conn_count, node))
else:
    # did not load correctly, print error message to console
    print(message)

channelConnections

channelConnections ( Node ID )
Returns a list of the channels connected to a given node

Parameters

Node ID: str

Name or ID of node e.g. 'Chan_A.1'

Returns

Out: list

List of connected channels e.g. ['Chan_A', 'Chan_B']

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    node = 'Chan_A.1'
    conn_chans = res.channelConnections(node)
    # print to console    
    print('Channels connected to {0}:'.format(node))
    for chan in conn_chans:
        print(chan)
else:
    # did not load correctly, print error message to console
    print(message)

channelCount

channelCount ()
Returns the total number of channels in results

Parameters

-

Returns

Count: int

Number of channels

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    chan_count = res.channelCount()
    # print to console    
    print('{0} channels in results'.format(chan_count))
else:
    # did not load correctly, print error message to console
    print(message)

channelResultTypes

channelResultTypes ()
Returns a list of all the available result types for channels

Parameters

-

Returns

Out: list

List of result types e.g. ['Q', 'V']

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    chan_rt = res.channelResultTypes()
    # print to console    
    print('Available channel result types:')
    for rt in chan_rt:
        print(rt)
else:
    # did not load correctly, print error message to console
    print(message)

channels

channels ()
Returns a list of all the channels IDs in the results

Parameters

-

Returns

Out: list

List of channels e.g. ['Chan_A', 'Chan_B', 'Chan_C']

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    chans = res.channels()
    # print to console    
    print('Channels:')
    for chan in chans:
        print(chan)
else:
    # did not load correctly, print error message to console
    print(message)

channelsDownstream

channelsDownstream ( Node ID )
Returns a list of all the channels downstream of a given node

Parameters

Node ID: str

Name or ID of node e.g. 'Chan_A.1'

Returns

Out: list

List of channels e.g. ['Chan_B']

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    node = 'Chan_A.1'
    dns_chans = res.channelsDownstream(node)
    # print to console    
    print('Channels downstream of {0}:'.format(node))
    for chan in dns_chans:
        print(chan)
else:
    # did not load correctly, print error message to console
    print(message)

channelsUpstream

channelsUpstream ( Node ID )
Returns a list of all the channels upstream of a given node

Parameters

Node ID: str

Name or ID of node e.g. 'Chan_A.1'

Returns

Out: list

List of channels e.g. ['Chan_A']

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    node = 'Chan_A.1'
    ups_chans = res.channelsUpstream(node)
    # print to console    
    print('Channels upstream of {0}:'.format(node))
    for chan in ups_chans:
        print(chan)
else:
    # did not load correctly, print error message to console
    print(message)

format

format ()
Returns the result format i.e. '2013' or '2016'

Parameters

-

Returns

Format: str

Format of results e.g. '2016'

Example

import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before calling function
if not err:
    format = res.format()
    # print to console    
    print('Results format: {0}'.format(format)
else:
    # did not load correctly, print error message to console
    print(message)

getAdverseGradients

getAdverseGradients ()
Returns locations of any adverse water level or energy level (if result type available) gradients in long profile. Note getLongProfileData method must be called prior to calling this method

Parameters

-

Returns

Adverse water level gradients: tuple

( list x data, list y data ) e.g. ([0, 5], [10, 12])

Adverse energy level gradients: tuple

( list x data, list y data ) e.g. ([0, 5], [11, 14])

Example

import matplotlib.pyplot as plt  # plotting library
import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before continuing
if not err:
    # initialise plot
    fig, ax = plt.subplots()

    # get long profiles and add to plot
    chan = 'Chan_A'
    timestep = 1.0
    result_types = ['Bed Level', 'H']  # get both water level and bed level
    for rt in result_types:
        err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan)
    
        # check for error before plotting
        if not err_lp:
            x, y = data
            ax.plot(x, y, label=rt)
        else:
            # error occurred getting long profile data, print error message to console
            print(mess_lp)

    # check for adverse gradients
    adv = res.getAdverseGradients()
    for i, data in enumerate(adv):
        x, y = data

        # get appropriate label
        # getAdverseGradients() returns 2 datasets:
        # first dataset adverse water level
        # second dataset adverse energy level
        if i == 0:  # first dataset
            label = 'Adverse Water Levels'
        else:  # second dataset
            label = 'Adverse Energy Levels' 

        # add to plot as points
        ax.plot(x, y, label=label, marker='o', linestyle='None')
    
    # add legend to plot
    lines, labs = ax.get_legend_handles_labels()
    ax.legend(lines, labs)
      
    # show plot   
    fig.show()
else:
    # did not load correctly, print error message to console
    print(message)

getLongProfileData

getLongProfileData ( Timestep, Result Type, Channel ID, [optional] 2nd Channel ID )
Returns long profile data from a given channel to another channel. If no second channel is specified will continue until no further channels downstream

Parameters

Timestep: float or str

Output timestep to plot. Can be a value e.g. 1.5 or string e.g. 'max'

Result Type: str

Result type e.g. 'H'

Channel ID: str

Starting channel for long profile e.g. 'Chan_A'

2nd Channel ID: str

Optional downstream channel ID to stop the long profile at e.g. 'Chan_D'

Returns

Error: bool

Returns False on success, True when an error occurred

Message: str

Accompanying error message if an error occurred

Data: tuple

list x data points, list y data points e.g. ([0, 1, 2], [10, 20, 30])

Example

import matplotlib.pyplot as plt  # plotting library
import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before continuing
if not err:
    # initialise plot
    fig, ax = plt.subplots()

    # get long profiles and add to plot
    chan = 'Chan_A'
    timestep = 1.0
    result_types = ['Bed Level', 'H']  # get both water level and bed level
    for rt in result_types:
        err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan)
    
        # check for error before plotting
        if not err_lp:
            x, y = data
            ax.plot(x, y, label=rt)
        else:
            # error occurred getting long profile data, print error message to console
            print(mess_lp)

    # add legend to plot
    lines, labs = ax.get_legend_handles_labels()
    ax.legend(lines, labs)
      
    # show plot   
    fig.show()
else:
    # did not load correctly, print error message to console
    print(message)

getLongProfileTimeOfMax

getLongProfileTimeOfMax () Returns the time of maximum water level along the current profile. Note getLongProfileData method must be called prior to calling this method

Parameters

-

Returns

x data: list

x points for plotting time of max along long profile e.g. [0, 1, 2, 3, 4, 5]

y data: list

y points for plotting time of max along long profile e.g. [10, 11, 12, 13, 14, 15]

Example

import matplotlib.pyplot as plt  # plotting library
import pytuflow as tu

# Initialise result class
res = tu.ResData()

# load .tpc result file
path = r'C:\TUFLOW\results\M04_5m_001.tpc'
err, message = res.load(path)

# check results were loaded successfully before continuing
if not err:
    # initialise plot
    fig, ax = plt.subplots()

    # get long profiles and add to plot
    chan = 'Chan_A'
    timestep = 'max'  # maximum result along profile
    result_types = ['Bed Level', 'H']  # get both water level and bed level
    for rt in result_types:
        err_lp, mess_lp, data = res.getLongProfileData(timestep, rt, chan)
    
        # check for error before plotting
        if not err_lp:
            x, y = data
            ax.plot(x, y, label=rt)
        else:
            # error occurred getting long profile data, print error message to console
            print(mess_lp)

    # also plot time of max water level on secondary axis
    tom_x, tom_y = res.getLongProfileTimeOfMaximum()
    ax2 = ax.twinx()  # initialise secondary axis

    # add to plot to secondary axis
    ax2.plot(tom_x, tom_y, label='Time of Maximum', linestyle='--')
    
    # combine axis legends and add to plot
    lines, labs = ax.get_legend_handles_labels()
    lines2, labs2 = ax2.get_legend_handles_labels()
    comb_lines = lines + lines2
    comb_labs = labs + labs2
    ax.legend(comb_lines, comb_labs)
      
    # show plot   
    fig.show()
else:
    # did not load correctly, print error message to console
    print(message)