Python Library TUFLOW Results: Difference between revisions
Content deleted Content added
No edit summary |
No edit summary |
||
| (23 intermediate revisions by 4 users not shown) | |||
Line 1:
[[File:TUPython.png | 435px]]
=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
Line 9:
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command.<br>
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib.<br>
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on the QGIS plugin repository, on the TUFLOW support GitHub repository or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.
<ol>
<li>QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/]<br>
: If you select '''Download Latest''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin QGIS plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin]<br>
: If you select '''Clone or Download''' and then select '''Download Zip''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>QGIS<br>
: If you have QGIS2 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\.qgis2\python\plugins\tuflow<br>
: If you have QGIS3 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\tuflow<br></li>
</ol>
The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.
Note it shouldn’t matter if you’re using python 2 or python 3.
=Dependencies=
The TUFLOW results library calls a number of python
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
Line 22 ⟶ 37:
==Import==
This library is imported with the typical python syntax.<br>
<pre>import
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res =
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
Line 43 ⟶ 58:
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
Line 103 ⟶ 118:
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=
! style="background-color:#005581; font-weight:bold; color:white;" width=
! style="background-color:#005581; font-weight:bold; color:white;" width=
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
Line 142 ⟶ 157:
|}
<br>
=Examples=
These examples
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import
input_res = r'C:\TUFLOW\Models\Tutorials\QGIS\Complete_Model\TUFLOW\results\M04\2d\plot\M04_5m_001.tpc'
# initialise the results class
res = TUFLOW_results.ResData()
# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
Line 156 ⟶ 178:
sys.exit()
print('loaded')
#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure
#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()
# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>
<br>
[[File:Python Results 2016 Q Example 01.png|600px]]
<br>
This will create a figure that looks like the above.
<br>
==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure
# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']
#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTSData(node_id,'1D','H','P')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print(message)
sys.exit()
# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
<br>
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above.<br>
<br>
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties
#Get flow data
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()
#Get velocity data
found, results, message = res.getTSData(chan_id,'1D','V','L')
if found:
print('found requested data')
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print(message)
sys.exit()
# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
<br>
[[File:Python Results 2016 QV Example 01.png|600px]]
<br>
This will create a figure that looks like the above.<br>
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None
#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print(message)
sys.exit()
else:
print('LP connectivity determined.')
print('Get LP static data')
error, message = res.LP_getStaticData()
if error:
print(message)
sys.exit()
else:
print('LP static data retrieved')
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure
#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')
# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')
# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
<br>
[[File:Python Results 2016 LP Example 01.png|600px]]
<br>
This will create a figure that looks like the above.<br>
=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results)
{{Tips Navigation
|uplink=[[TuPlot| Back to TuPlot]]
}}
| |||