View source for TUFLOW Viewer - Isodate (Date-Time) Format

==Tool Description==
This page describes how to use date-time format when using QGIS 3.16 or later. Prior versions of QGIS are not recommended for Isodate (Date-Time) format.<br>
Be aware that all layers have individual reference times and may become misaligned if one is updated and the others are not (e.g. the map outputs are updated, but not the time series outputs). 

Date-time can be toggled on by toggling '''Show as dates''' below the plot toolbar.<br>
[[File: TUFLOW_Viewer_Show_As_Dates_01a.png]]<br>

This will toggle the time format in the time box from relative time (hh:mm:ss) to absolute time (dd/mm/yyyy hh:mm:ss). The plot will not always update and may require '''refresh plot''' [[File: refreshplotblack.png | 15px]] to be clicked before updating the x-axis of the time series plot. After toggling on '''Show as dates''', refer to the following sections for specific information and examples relating to Map Output Results, Time Series Results, Particle Tracking Results and Imported Data (not model results).

===Zero Date===
The '''Zero Date''' option in '''Settings >> Options >> Plotting''' controls the relative time. Consequently, this value has no effect on the date-time displayed in the time box or plot window if '''Show as dates''' is toggled on. If '''Show as dates''' is toggled off and the '''Zero Time''' and the '''Reference Time''' are not aligned, then you may find that the relative time in the time box is offset by some value (the results should still work as expected).<br>
[[File: TUFLOW_Viewer_Settings_Plotting_Dialog_01a.png]]<br>

==Map Outputs==
For QGIS v3.16+, the reference time for map outputs is controlled in the layer's '''Properties'''. For TUFLOW Classic and HPC simulation results, this will most likely default to '''1999-12-31 14:00:00'''. TUFLOW FV outputs can contain a reference time specified in the '''.fvc''' file and may be correctly set on load.<br> 
[[File: TUFLOW_Viewer_Properties_Dialog_Temporal_Settings_01a.png]]<br>
<br>

Be aware that all layers have individual reference times and may start mis-aligning if one is updated and the others are not (e.g. the map outputs are updated, but not the time series outputs). Please see relevant links at the bottom of the page on how to work with date-time format with other outputs.<br>

'''Switching on Date-Time and Changing the Reference Time'''<br>
{{Video|name=TUFLOW_Viewer_Map Outputs_Isodate Format_4a.mp4|width=1350}}


'''Fixing the Relative Time'''<br>
{{Video|name=TUFLOW_Viewer_Map Outputs_Isodate Format_5a.mp4|width=1350}}<br>

==Time Series Outputs==
Once '''Time Series Outputs''' have been loaded, it is not currently possible to change the reference time. To set the reference time, this must be done prior to loading the results into TUFLOW Viewer. This can be done either by:<br>
* Setting '''Zero Date''' in '''Settings >> Options >> Plotting''' prior to loading the results as this will be used in-lieu of any inherent reference time contained in the results
* Users can add the following reference time line to the '''.tpc''' file to set the reference time for the results:<br>
:: <tt><font color="blue">Reference Time </font><font color="red">==</font> YYYY-MM-DD hh:mm:ss</tt><br> 
Note: the date format doesn't have to use this exact form. Other conventions (e.g. U.S. convention) can be used.<br>

'''Turning on Date-Time Format'''<br>
{{Video|name=TUFLOW_Viewer_TS_Outputs_Isodate_Format_01a.mp4|width=1350}}<br>

'''Changing Reference Time'''<br>
{{Video|name=TUFLOW_Viewer_TS_Outputs_Isodate_Format_02a.mp4|width=1350}}<br>

== Particle Tracking Output==
Once '''Particle Tracking Outputs''' have been loaded, it is not currently possible to change the reference time. Particle results may inherently have a reference time and if this is the case, it is not possible to change unless the user updates this directly in the netCDF file (e.g. either by using Matlab or Python - example presented below using Python). If the particle results do not have a reference time, then it is possible to change the reference time by changing '''Zero Date''' in '''Settings >> Options >> Plotting''' prior to loading the results. The '''Zero Date''' will be adopted in-lieu of any reference time contained in the results.<br>

[[File: DateTime_Particles_Example.gif]]<br>
<br>

'''Example Python Code to Add or Modify the Reference Time'''<br>
This can be done in QGIS using the Python Console. To access the Python Console, go to '''Plugins''' in the top dropdown menu options and select '''Python Console'''.<br>

[[File: TUFLOW_Viewer_QGIS_Python_Console_Dropdown_01a.png]]<br>

<pre>
from netCDF4 import Dataset


ptm = r"C:\TUFLOW\results\particle_output_ptm.nc"  #  Path to particle output netCDF file

# Open netCDF file and change the 'long_name' of the Time variable
nc = Dataset(ptm, "r+")
nc['Time'].long_name = "output time from 01/01/2000 00:00:00"  # dd/mm/yyyy hh:mm:ss - If removing reference time, use 'output time' and omit the date string
nc.close()
</pre>

== Imported Data (Not Model Results) ==
If the user data is imported with dates, then these will be adopted for use when date-time format is used. If dates are not imported with the data then the reference time will be dynamic and be adopted from '''Settings >> Options >> Plotting >> Zero Date'''. 
'''''Note:''''' Unlike imported model results, relative time is locked on import. So even if the import includes dates, the relative time will not dynamically update if the '''Zero Date''' is changed.<br>
{{Video|name=TUFLOW_Viewer_User_Data_Isodate_Format_01a.mp4|width=1350}}<br>
<br>

{{Tips Navigation
|uplink=[[TUFLOW_Viewer#Data_Selection.2C_Display_and_Styling| Back to TUFLOW Viewer Main Page]]
}}