TotPrePart

3. User Guide

At the top, a contextual menu provides access to the various modules of the tool. The modules can be accessed progressively, in the following order: 1) Home (Information module); 2) Input Data (Data entry module); and 3) Analysis (Calculation module). Once the calculations of a module are completed, the user can advance to the next module and can also return to the respective module at any time during the session. Menu tabs are available for both the data entry (i.e., Info, Load Data, Graphical View, Table View and Export Input Data for the Input Data module) and calculation (i.e., Info, Analysis, Graphical View, Table View and Export) modules. Additional buttons (i.e., UCD and Reset Data) appear in the contextual menu once the Input Data is loaded to the tool.

TotPrePart uses a daily timestep for both input and output data and includes a series of averaging options for displaying and exporting data (i.e., monthly, seasonal, yearly). TotPrePart also calculates and allows for displaying of input and output data using as a "typical year daily" timeseries (i.e., daily multi-year averages for each day of the year available in the input and output files) when the analysis is carried out for a period longer than one year. The daily values for the typical year can also be averaged by the tool over monthly, seasonal, and yearly periods. Daily typical and monthly averaging intervals are recommended for inspecting and analyzing "average" conditions when the datasets cover longer periods of time (several years).

In the following sections the options available under the various modules of the tool, together with details about the output data, calibration procedure and data inspection, visualization and export are presented in separate subsections.

3.1. Quick start

In order to run TotPrePart the user has to complete the following steps:

1. Load Data: provide required data or use the provided test data [Input Data module];

2. Perform snowfall and rainfall amount calculations: enter required coefficients and select Run Analysis [ANALYSIS module - Analysis tab]. The calibration of the tool is conducted by adjusting the coefficients available on this page (i.e., precipitation [mm] to snowfall [mm] conversion factors; snowfall conversion factors [mm to cm]); and the lower and upper bounds for the temperature intervals associated with each conversion factor. The Analysis is performed in conjunction with the information displayed in the Calibration overlay window launched by using the Run Analysis button;

3. Investigate Results and Export Data: review TotPrePart output from each module [Table View and/or Graphical View] and export results [Export Data button available under each data entry and calculation modules or the CSV button available under the Stats and Calibration Stats of the Graphical View or under the Table, Stats and Calibration Stats of the Table View].

The steps required for using this tool are described in more detail below.

3.2. Home Module

This module contains information related to the development, methodology and use of TotPrePart. Under each of the input and calculation modules an Info tab is available, where general information relevant to the respective module is provided.

3.3. Input Data Module

The first step in conducting an analysis is to upload the input data file to be used by TotPrePart. The users can run TotPrePart either by using the test dataset or by uploading a new dataset.

For testing TotPrePart and better understanding how the various components of the tool operate, the user can upload the test data set provided by clicking on "Try the tool using the test dataset" button. The test dataset contains three years of weather and user calibration data (UCD). Test dataset UCD data consists of snowfall (mm; UCD1; corresponding to TotPrePart SNF (mm) output parameter; UCD1 estimated as the difference between total precipitation and rainfall measured at the Environment and Climate Change Canada (ECCC) weather station located at the Charlottetown Airport, Prince Edward Island, Canada), snowfall (cm; UCD2; corresponding to TotPrePart SNF (cm) output parameter; UCD2 measured at the ECCC weather station located at the Charlottetown Airport, Prince Edward Island, Canada), and rainfall (mm; UCD3; UCD3 measured at the ECCC weather station located at the Charlottetown Airport, Prince Edward Island, Canada).

For using TotPrePart, the users need to upload daily timeseries. The tool accepts source data sets in Comma Separated File (csv) format. The users can use the "Download Sample File" button located on the Upload User Data Page (Load Data) or the "Export Input Data - Daily" menu to obtain a correctly formatted input file that can be used as a model for populating the input data file with user data. The "Export Input Data - Daily" menu becomes available after the test or a user dataset is loaded. The user input file can be uploaded to TotPrePart by using the "Upload user data" button. TotPrePart allows uploading of files with maximum 7500 rows (~20 years of daily data). It is recommended to split the input data set in blocks of 20 years daily timeseries when the intent is to analyze longer time periods. It should be noted that the tool cannot accommodate missing data (i.e., blank rows in required data columns) or erroneous data entries, and hence it is recommended that the integrity of the source data is verified before uploading. An error message will be displayed, and the user will be redirected to the Load Data page if inconsistencies are detected in the user file.

The input data file consists of a tabular file, with the first row dedicated to the parameter names, 1 column dedicated to calendar date, 2 columns dedicated to required input data (TEMP – average daily air temperature [°C] and TOTP – daily total precipitation [mm]) and 3 columns reserved for optional user calibration data (UCD1 to UCD3). The required input data columns have to contain values in all rows, while the optional data columns (i.e., UCD) can be left blank if data is not available. If UCD data is provided, then all the rows in the respective column(s), except for the column headings, must contain numeric values. UCD data sets are not restricted to certain parameters and can include time series for any parameter that the user intends to use for comparing with the output from TotPrePart. Although UCD data is optional, it provides critical information for adjusting the various coefficients of the tool during the calibration procedure. Examples of calibration time series datasets include snowfall amount (as mm or cm) and thickness of the snow layer.

Notations:

• Required data:
  DATE - use yyyy-mm-dd format;
  TEMP - average daily air temperature [°C];
  TOTP - daily total precipitation [mm];

• Optional data:
  UCD - user calibration data (up to three columns; leave blank if no data is available)

Notes:

• The tool requires daily data

• The user input data file has to be uploaded using a file with 1 column dedicated to calendar date, 2 columns dedicated to required input data (TEMP, TOTP) and 3 columns reserved for optional user calibration data (UCD1 to UCD3)

• Use the first row of the data set for column headings

• TotPrePart includes several input data integrity and quality check routines; however, the user is advised to thoroughly check the input dataset before uploading it to the tool to minimize the risk for erroneous output

Once the input dataset is loaded via either the "Try the tool using the test data set" or "Upload user data" button an overlay window appears (i.e., "Select the UCD averaging method") asking the user to specify the method used for calculation of monthly values for each UCD timeseries (i.e., averaging vs. summation). Once this step is completed a new button ("UCD") is added to the right of the Input Data tab at the top of the page and the view switches to Graphical View. The UCD menu available at the top of the page allows the user to change the method for the calculation of monthly values for each UCD at any time. See section 3.7. for instructions regarding the inspection of datasets using tables and graphs as well as for the various options available for exporting the data.

Once the loading and inspecting of the input data is completed the user can click on the ANALYSIS menu entry at the top of the page to advance to the calculation module.

3.4. Analysis Module

On the Analysis Tab the user must first provide the coefficients required by the tool in the "Precipitation (mm) to Snowfall (mm) conversion factor", "Snowfall conversion factor (mm to cm)" and "Calibration mapping" sections of this page. The values of the coefficients can be entered manually using the collapsible menus available under the Analysis Tab or can be uploaded as a set using the "Import configuration file" button. Once specified, the values of the coefficients can be checked using the "Validate" button at the bottom of the page. An error message is displayed if the coefficients include blank, out of range or incorrect format data. "Run Analysis" button replaces the "Validate" button if no errors in coefficient values are found during the validation. The configuration file can be downloaded using the "Export Configuration File" button under the Analysis Tab (including either default values of the coefficients if the first tool run has not been completed or values of the coefficient as set for the last available run of the tool if the analysis has been completed at least once) or by using "Export Configuration" in the "Export Results" menu (available after one successful run of the module). If needed, the users can also reset all the values of the coefficients to default values by using the "Reset to Default" button available at the bottom at the bottom of the page in the Analysis tab.

In the "Precipitation (mm) to Snowfall (mm) conversion factor" section of the page the user have to enter the lower and upper bound air temperature for each air temperature interval as well as the conversion factor of total precipitation (TOTP) to snowfall (SNOF[mm]) associated with each interval. The number of air temperature intervals can be expanded or reduced using the "+" or "-" buttons at the left of coefficient fields. Air temperature values between -70 and 50 oC are allowed. When entering values in the air temperature fields, the user have to check that the intervals do not overlap and the lower bound temperature is smaller than the upper bound temperature for each interval. For the conversion factor (CTMM - air temperature coefficient for conversion of total precipitation to snowfall), the values have to be between 0 and 1.

In the "Snowfall conversion factor (mm to cm)" section of the page the user have to enter the lower and upper bound air temperature for each air temperature interval as well as the conversion factor of the snowfall amount in mm (SNF[mm]) to the snowfall amount in cm (SNF [cm]) for each temperature interval. The number of air temperature intervals can be expanded or reduced using the "+" or "-" buttons at the left of coefficient fields. Air temperature values between -70 and 50 oC are allowed. When entering values in the air temperature fields, the user have to check that the intervals do not overlap and the lower bound temperature is smaller than the upper bound temperature for each interval. For the conversion factor (CTCM - air temperature coefficient for conversion of total precipitation to snowfall), the values have to be between 0 and 100.

In the "Calibration mapping" section of the page the users have to select the pairs of tool output and user calibration data that will be used during the calibration of the tool. The "Calibration Mapping" fields can be ignored if the UCD data is not available in the Input Data file.

TotPrePart starts the calculations once the values of the required coefficients are set and the user clicks on the Run Analysis button at the bottom of the page.

All values entered on this page can be subsequently adjusted during the calibration procedure, with calibration being considered final once no further improvement in the output fitness is observed. See section 3.6 for instructions regarding the calibration of the tool and section 3.7 for instructions regarding the inspection of datasets using tables and graphs as well as for the various options available for exporting the data.

3.5. Output Timeseries

The output from TotPrePart is shown in the table below.

3.6. Calibration Procedure

Calibration of the tool is performed via the Analysis tab of ANALYSIS module and is available only when UCD data is included in the Input data file. Calibration is conducted by first pairing the datasets from the output of the tool with the user calibration data (UCD) using the “Calibration mapping” menu available under the “Analysis” tab. Once the pairing is completed, the user can proceed to adjust coefficients, validate the data (“Validate” button at the bottom of the Analysis page) and run the tool (i.e., “Run Analysis” button at the bottom of the Analysis tab page) and inspect the tool output in the subsequent Calibration overlay window. The fitness of the output for various timesteps and averaging intervals can be inspected in the Calibration overlay window via graphs as well as bivariate statistics. If the calibration is considered unsatisfactory the user can return to the Analysis menu (i.e., “Return” button), adjust the various coefficients of the tool and rerun the analysis. If the calibration is considered satisfactory the user can complete the calculations by proceeding to the next step (i.e., “Proceed to results” in the Calibration Overlay window).

To aid with data inspection and assessment of the fitness of the output data, TotPrePart includes several univariate and bivariate statistics. Univariate statistics, including, average, minimum, maximum and standard deviation are calculated separately for the input (i.e., user provided calibration data) and tool output time series. The graphs and the univariate statistics can be used for example for comparing the general trends, the range of values and the amplitude of variations in both data sets. The bivariate statistics include the coefficient of determination (R2), root mean square error (RMSE) and the normalized root mean square error (NRMSE). NRMSE is calculated by using the average, the interquartile range or the differences between maximum and minimum (see definitions below). The bivariate statistics are used for evaluating the fitness of the output, by providing a measure of the differences between the values calculated by the tool and the user provided calibration data (i.e., UCD). The equations used for calculating each bivariate statistic are shown below.

It is recommended that the calibration is conducted by changing one coefficient at a time over a selected range of values. When no further improvement is observed in the fitness of TotPrePart output the user can advance to adjusting the values of the next coefficient. The values of the various coefficients can be considered final once no further improvement in the fitness of TotPrePart output is observed. Currently, only calibration by trial and error is available, however the integration of an autocalibration routine is in planning stages.

3.7. Data inspection, visualisation and export

Inspection of data via graphical and tabular views can be conducted via the Graphical View, Table View and Export Data menu entries that become available in the Input Data module once the input dataset is loaded to TotPrePart. These menu entries are also available under each ANALYSIS module and allow the user to evaluate the output for each of these modules.

Graphical View allows for plotting of input or output data using various time steps and intervals available via a drop-down menu. The parameters that can be displayed are available in the selection pane located to the right of the plot. Each parameter can be displayed on the primary (left) Y axis or on the secondary (right) Y axis by clicking on the toggle placed at the right of the selection pane. Additional options for customizing the plot become visible in the top right corner when the mouse pointer is placed above the plot. These options include zoom, auto scale, reset axes, show data point labels, download plot, etc. Univariate statistics (average, minimum, maximum, standard deviation) for selected timeseries and bivariate statistics (R², RMSE, NRMSE_ave, NRMSE_IQR, NRMSE_min/max) for inspecting the fitness of the tool output are available under the Stats and Calibration Stats tabs, respectively. These statistics are available either for the entire dataset ("Show Complete Dataset Stats" button) or for a selected subset ("Show stats by Interval" button). The tables shown on the statistics pages can be exported individually by using the corresponding CSV button located to the right of the page.

Table View allows the user to display data in tabular format using various time steps and intervals. The user can also change the number of lines, filter data based on date or adjust the starting date of the data that is displayed. In the initial Table View, the columns displayed by default are limited to "key" parameters, however the user can change the selection of the parameters to be displayed by selecting the parameters listed above the table. In the respective list, the parameters that are displayed in the table are shown in filled boxes, while the ones that are omitted are included in clear boxes. The "key" parameters are shown in red font when not selected to be displayed. Similar to the Graphical View, univariate statistics (average, minimum, maximum, standard deviation) for selected timeseries and bivariate statistics (R², RMSE, NRMSE_ave, NRMSE_IQR, NRMSE_min/max) for inspecting the fitness of the output are available under the Stats and Calibration Stats tabs, respectively. These statistics are available either for the entire dataset ("Show Complete Dataset Stats" button) or for a selected subset ("Show stats by Interval" button). The tables shown on the statistics pages can be exported individually by using the corresponding CSV button located to the right of the page.

The Export Data tab offers additional options for exporting the entire dataset using various time steps and intervals. The Export Data tab also provides options for exporting statistics and the tool configuration (i.e., values of parameters and coefficients used by the user in the each of the tool modules) The data is currently exported in csv format. The CSV button located at the top right of each table in Table View or in Graphical View can be used if the intent is to export only the data shown in the current window.