View source for QGIS ARR to TUFLOW

The ARR to TUFLOW utility has been developed to help users set up a TUFLOW model that uses Australian Rainfall and Runoff (ARR) input parameters and the Australian Bureau of Meteorology (BOM) rainfall by automating the collection and processing of the data. The inputs and outputs of the tool are explained in detail below. '''''Note:''''' this tool helps with data processing, however is not a substitute to reading ARR. Similarly this wiki page discusses the use of the tool and the options, however context should be derived from ARR directly. Please see the [http://arr.ga.gov.au/arr-guideline| ARR Website] for more information.<br><br>
__TOC__
<br>
=Getting Started=
===Installation===
The ARR to TUFLOW tool is a free tool that comes as part of the TUFLOW plugin in QGIS. For instructions on how to install the plugin, read the following wiki page:<br><br>
[[TUFLOW_QGIS_Plugin#Installation_of_Plugin | How to install the TUFLOW plugin]]<br><br>
There are also instructions on installing plugins in the QGIS documentation - if you choose to follow the QGIS documentation, the plugin is called "TUFLOW" in the repository:<br><br>
[https://docs.qgis.org/3.16/en/docs/training_manual/qgis_plugins/fetching_plugins.html Link to QGIS Documentation - Installing and Managing Plugins]<br>

===QGIS Version===
The ARR to TUFLOW tool is, for the most part**, a Python tool that runs independently of QGIS. Therefore the installed QGIS version should not be a significant factor, however occasionally QGIS will update the Python version in the installation. This does present a small risk that the tool will break with QGIS version, although it's considered unlikely (the risk of the tool being broken by updates to the ARR datahub would be higher). If the tool does break, please see [[#The_Tool_Isn.27t_Working | The Tool Isn't Working]] for information (the solution is most likely to update the plugin rather than reinstall an older version of QGIS).<br><br>

<nowiki>**</nowiki>The tool does use QGIS for pre-processing tasks, such as area and centroid calculation as well as reprojection or cartesian to long-lat conversion.
===Opening The ARR to TUFLOW Tool===
Once the TUFLOW plugin is installed, the ARR to TUFLOW tool can be opened by clicking the following icon in the plugin toolbar:<br>
[[File: ARR_to_TUFLOW_toolbar.PNG]]<br><br>

=Quickstart=
<ol>
<li> Load a catchment GIS file (e.g. shp file) into QGIS - this can either be a polygon or point layer
<li> Open the '''ARR to TUFLOW''' tool
<li> Select the GIS catchment layer in '''Input Catchment File''' dropdown box<br>
[[File: ARR_dialog_input_catchment_file.PNG | 500px]]<br>
<li> Select the attribute field to use as the catchment name in the '''Unique Catchment Identifier Field''' dropdown<br>
[[File: ARR_dialog_unique_catchment_identifier.PNG | 500px]]<br>
<li> Select storm event combinations from the list of magnitudes and durations<br>
[[File: ARR_dialog_storm_events.PNG | 350px]]<br>
<li> Choose an output location<br>
[[File: ARR_dialog_output_location.PNG | 500px]]<br>
<li> Click '''OK''' and wait for the tool to finish<br>
[[File: ARR_tool_complete_dialog.PNG | 250px]]
</ol><br><br>

=Output=
===Log File===
A log file ('''<catchment_name>_log.txt''') will be written to the output folder. The log file will contain all WARNING and ERROR messages as well as logged inputs and processing steps. It's recommended to check the log file after running the tool for any warning or error messages. Most warning messages will be collated and written together near the bottom of the log file to make it easier to review them.

===Data Output===
The following outputs are located in the folder '''<output_folder>\data'''
<ol>
<li> '''Raw BOM and ARR Datahub outputs'''
* ARR_Web_data_<catchment_name>.txt
* BOM_raw_web_<catchment_name>.html
* Areal_<TP_Zone>_Increments.csv (Areal temporal patterns)
<li> '''Rainfall depths'''
* BOM_Rainfall_Depths_<catchment_name>.csv - processed rainfall depths (after ARF factors)
<li> '''ARF Factors'''
* <catchment_name>_ARF_Factors.csv - calculated ARF factors
<li> '''Storm Burst Rainfall Losses'''
* <catchment_name>_Burst_Initial_Loss.csv - calculated Storm Burst Initial Rainfall Losses (Complete Storm Initial Loss - Preburst Rainfall Depth)
</ol>

===TUFLOW Output===
The following outputs are generated by the utility in TUFLOW format. Please see the example below on how to use the output files for a model.
<ol>
<li> '''TUFLOW Rainfall Inflows'''
* The rainfall inflows are output in the following location '''<output_folder>\rf_inflows'''. This output folder is where all the direct rainfall inflows that would be used in the TUFLOW model are output. An inflow file is generated for each event magnitude - duration combination. All available temporal patterns are included in a single file (including climate change options).
<li> '''bc_dbase.csv'''
* TUFLOW boundary condition database. Setup to point to the '''RF''' folder with wildcards applied.
<li> '''event_file.tef'''
* TUFLOW Event File. Setup with wildcards applied. To keep the file names from becoming overly long and complicated, Climate Change scenarios are labelled as '''CC1''', '''CC2'''.. etc. These correspond to the combinations of climate change scenarios requested by the user e.g. 2090_8.5 (climate change year: 2090, RCP: 8.5)
<li> '''soil_infiltration.trd''' or '''rainfall_losses.trd''' - the name of the file will be dependent on the selected loss method, but they are essentially the same file
* This file is a TUFLOW Read File (.trd) that contains variable initialisation for initial and continuing loss values
<li> '''soils.tsoilf''' or '''materials.csv''' - which file is output will be dependent on the selected loss method
* soils.tsoilf - rainfall loss file for the infiltration loss method
* materials.csv - rainfall loss file for the rainfall excess method
</ol><br>

===Example: Using the outputs in a TUFLOW model===
* [[QGIS_ARR_to_TUFLOW_Example | Example use of the ARR to TUFLOW tool]]
<br>

=Additional Options=
===Climate Change===
Climate change options can be added by checking on a combination of climate change years and Representative Concentration Pathways (RCP) in the dialog. Selecting at least one climate change scenario will output:
* An extra boundary database file: '''bc_dbase_CC.csv'''
* Climate change inflows will be appended to the end of each event's inflow file
* One additional event option will also be added to the event file for each combination of selected climate change scenarios labelled as CC01, CC02, CC03,... etc.. It is intended that the climate change scenarios would be treated as a separate event (e1 = magnitude, e2 = duration, e3 = temporal pattern, e4 = climate change scenario) however the output files can easily be manipulated by the user to configure the model differently.<br><br>
[[File: ARR_dialog_climate_change.PNG | 500px]]<br><br>
[[File: ARR_example_climate_change_rf_inflow.PNG | 650px]] <br><br>
[[File: ARR_example_climate_change_tef.PNG | 300px]]
<br><br>
===Temporal Patterns===
Temporal pattern options can be found by expanding the '''Temporal Patterns''' section in the dialog.
* '''Manually Specify Point Temporal Patterns (csv)''' - lets the user specify the point temporal patterns which is expected to be in the ARR datahub format
* '''Manually Specify Areal Temporal Patterns (csv)''' - lets the user specify the arealtemporal patterns which is expected to be in the ARR datahub format
* '''Optional Additional Temporal Patterns''' - lets the user specify additional temporal pattern zones which will be included in the inflow files. This is only if the user wishes to included ''additional'' temporal patterns. The temporal patterns from the catchment location (taken at the catchment centroid) will always be included. The additional temporal patterns will be included in the inflow files and added to the event file.<br><br>
[[File: ARR_Dialog_temporal_patterns.PNG | 300px]]<br><br>
[[File: ARR_example_additional_temporal_patterns_rf_inflow.PNG | 650px]]<Br><br>
[[File: ARR_example_additional_temporal_patterns_tef.PNG | 250px]]
<br><br>

===Rainfall Losses===
=====Probability Neutral Losses=====
Probability neutral losses can be toggled on / off in the dialog (default is on). If 'on' this option will use probability neutral losses for the design burst initial loss rather than using the storm initial loss and pre-purst depths. If probability neutral losses are not available in the catchment area, then the method will automatically revert to using the storm initial loss). Currently this option cannot be used in conjunction with the '''complete storm''' option.<br><br>
[[File: ARR_dialog_probability_neutral_losses.PNG]]
<br><br>
=====NSW Continuing Loss=====
Continuing loss values for NSW will be automatically multiplied by 0.4. This will be reported in the log file as:
* "Catchment is in NSW, multiplying Datahub continuing loss by 0.4"
<br><br>
=====Pre-burst Percentile=====
The pre-burst percentile used to calculate design burst initial loss, or for pre-burst rainfall depth for the complete storm option, can be changed using the dropdown box in the dialog.<br><br>
[[File: ARR_dialog_preburst.PNG]]
<br><br>
=====User Defined Losses=====
Users can use their own rainfall loss values. The initial loss value will be treated as a complete storm value and not just for the design burst. For most regions, the design burst loss will be calculated my removing the pre-burst depth from the input loss value. If probability neutral losses are available, the burst initial loss will be calculated using the following equation:<br>
: <tt>IL burst = User IL x IL ARR Prob Neutral / IL ARR Complete Storm</tt><Br><br>
[[File: ARR_dialog_user_losses.PNG]]
<br><br>
=====Event Independent Continuing Loss=====
<br><br>
=====Impervious Losses=====
<br><br>
=====TUFLOW Loss Method=====
<br><br>
=====Initial Losses For Durations Less Than 1 Hour=====
<br><br>

===Areal Reduction Factors===
<br><br>
===Additional Output Options===
<br><br>
===Offline Mode===
<br><br>

=The Tool Isn't Working=
Coming Soon
<br><br>
==Can't access websites==
For whatever reasons, sometimes the BOM or ARR Datahub websites are down or unable to be accessed by the tool. The below are a set of instructions that can be used as a workaround should this occur:
*[[ARR_DATAHUB_CANNOT_BE_ACCESSED | ARR datahub website cannot be accessed by the tool]]