Rict User Guide Predictandclassify

***DRAFT***

***DRAFT*** River Invertebrates Classification Tool (RICT) User Documentation

1. 1.

Guide to Predict and Classify (Interactive Mode)

Introduction This document provides a guide to the interactive Predict and Classify process within RICT. It contains:

a) b)

c) d)

a summary of the data that needs to be provided to RICT options for how this data can be provided an overview of how to carry out a P&C run references to examples of actual runs carried out for common scenarios, including screenshots

Note that it is focused on how the tool operates rather than the science/rationale behind it. 2.

Summary of Data Required by RICT for a Predict &Classify Run In order to carry out a Predict & Classify run, the following data needs to be provided/specified: -

-

Environmental Variable (EV) data for each relevant site Observed Index values for each relevant site/index Settings for the Run Bias data for each Index/Season Limits for each Index to be classified

a)

Environmental Variable (EV) data for each relevant site

-

EV data needs to be provided in order to feed into the Prediction process which calculates ‘expected’ index values. Currently, the following data is required for each site (although this may change in future if new sets of Predictive Environmental Variables (PEVs) are created): -

-

-

Grid Reference (NGR Letters/Easting/Northing) Altitude Slope Discharge Category Velocity Category (if no Discharge Category) Distance from Source Mean Width Mean Depth Alkalinity Total Hardness (if no Alkalinity) Calcium (if no Alkalinity or Hardness) Conductivity (if no Alkalinity or Hardness or Calcium) % cover of boulders & cobbles % cover of pebbles & gravel % cover of sand % cover of silt & clay

Note that, since RICT caters for multi-year runs, a Year needs to be provided for each Site entry. b)

Observed Index values for each relevant site/index Sites are classified for each relevant index by dividing Observed Value by Expected Value to obtain an Environmental Quality Index (EQI). This is then compared against limits to obtain a classification status (e.g. High). Therefore, Observed Values need to be provided for each Site for each Index that is to be classified. As for EVs, Year needs to be provided for each Site/Index

c)

Settings for the Run In order for the Prediction and Classification run to be carried out in the way the user wishes, a number of settings need to be provided. The key ones are:

-

-

End Group Set Id (e.g. 3 = GB New Model – 43 End Group Set) Season Id (e.g. 5 = Spring and Autumn) Indices Set (e.g. 2 = Original BMWP + MINTA) PEV Set (e.g. 1 = GB) Multi Year Flag (Y/N) Reference Adjustment Flag (Y/N) Taxonomic Prediction Flag (Y/N) Taxonomic Prediction Level (e.g. TL1 = BMWP Family Level) Output File Prefix Run Name

Note that Number of Iterations can also be provided as a setting, but if not provided, it will be set to the default value held within the administration section. d)

Bias data for each Index/Season The classification process takes account of Bias when varying the Observed Values and so Bias Values need to be provided for each Index for the Season Code relevant to the Run. If no Bias values are provided for an Index then zero used … what if no Bias file? E.g. defaults file does not exist?

e)

Limits for each Index to be classified The classification process compares EQIs against limits and so the limits to be used for the run need to be provided for each index.

3.

Options for Providing the Data The input/output formats for RICT are XML. However, there are a number of options for providing/specifying the required data. 3.1

Environmental Variable Data a)

Create an XML File(s) and Upload The XML file(s) must conform to the specified XML schema and an example of a valid file for one site is provided in Appendix 1. The user can either create a new XML file(s) or amend an existing file. Information about how this can be done is being provided separately but, for example, ‘Notepad++’ can easily be used to open, amend and save an existing XML file. Once created the file(s) can be uploaded to RICT during the run – see Section 4.

b)

Load in an EV file in Existing RIVPACS Format An EV file in the existing RIVPACS format (with extension of .asc) can be uploaded to RICT during the run – see Section 4. RICT then automatically converts the RIVPACS format file to the required RICT XML format. Note that, as this facility is specific to the existing RIVPACS EV format, it will not be usable for any new EVs that may be introduced in future.

c)

Create XML file(s) from Excel It is expected that many users will maintain their EV data in Excel, and so a special RICT Data Entry spreadsheet has been created that enables XML files to be generated from Excel that can be processed by RICT. More details are being provided on this separately but, briefly, the EV data has to be entered/copied into the appropriate columns in the ‘Environmental Variables’ worksheet and then the ‘Start Here’ worksheet is used to generate the XML format file. The generated file(s) can then be uploaded to RICT during the run – see Section 4. Note that the RICT Data Entry Spreadsheet has been set up so that data from an existing RIVPACS EV file can be cut and pasted into the spreadsheet if required. Note also that the RICT Data Entry Spreadsheet is only applicable for existing EVs. If new EVs are introduced in future, then a new Data Entry Spreadsheet will be required and a change made to RICT to recognise the new data.

d)

Manually Enter Data Data can be manually entered during the run – see Section 4. Note that manually entered data is subsequently saved as an XML format file. Therefore, this functionality could be used to create an initial XML file which could then be amended as required for future runs.

3.2

Observed Index Values a)

Create an XML File(s) and Upload As for 3.1 a). An example file is provided in Appendix 2.

c)

Load in an Observed Index file in Existing RIVPACS Format An Observed Index file in the existing RIVPACS format (with extension of .oe1) can be uploaded to RICT during the run – see Section 4. Note that, as this facility is specific to the existing RIVPACS Observed Index format, it will not be usable for any new Indices that may be introduced in future.

c)

Create XML file(s) from Excel As for 3.1 c) except for entering/copying the data into the ‘Observed and Expected’ worksheet.

d)

Manually Enter Data As for 3.1 d)

3.3

Settings for the Run

a)

Use the Settings in the Default Settings File The system has a default settings file defined which contains the settings that will be used for a run if no other settings file is provided – see Appendix 3 for example. Before scheduling the run it is then possible to amend individual settings as required. Therefore, if there are only a couple of settings that are different from the defaults then it is easiest to use the default settings and then amend them prior to scheduling a run. Note that any changes made are applicable for that run only and do not change the underlying default settings file.

b)

Change the Default Settings File It is possible to change the file that is defined as the Default Settings file via the Administration function (see separate guide). This might be useful if a number of future runs are to have the same settings. Note that it will still be possible to amend individual settings prior to scheduling a run.

c)

Upload a Settings File Rather than change the Default Settings file, it is possible to upload a Settings File for use during the particular run. This would be useful if multiple settings for the run are different from the defaults. The user can either create a new Settings file or amend an existing file. Information about how this can be done is being provided separately but, for example, ‘Notepad++’ can easily be used to open, amend and save an existing XML file.

Note that it will still be possible to amend individual settings prior to scheduling a run. Note also that the Settings for a particular run are subsequently saved as an XML format file. Therefore, a new Settings file could be created by using the Default Settings file and then amending the required settings prior to scheduling the run. 3.4

Bias data for each Index/Season a)

Use the Default Bias File The system has a default bias file defined which contains the bias values that will be used for a run if no other bias file is provided – see Appendix 4 for example. Before scheduling the run it is then possible to amend bias values as required. Note that any changes made are applicable for that run only and do not change the underlying default bias file.

b)

Change the Default Bias File It is possible to change the file that is defined as the Default Bias file via the Administration function (see separate guide). This might be useful if a number of future runs are to have the same bias values. Note that it will still be possible to amend bias values prior to scheduling a run.

c)

Upload a Bias File Rather than change the Default Bias file, it is possible to upload a Bias File for use during the particular run. This would be useful if the required bias values are significantly different from the defaults. The user can either create a new Bias file or amend an existing file. Information about how this can be done is being provided separately but, for example, ‘Notepad++’ can easily be used to open, amend and save an existing XML file. Note that it will still be possible to amend bias values prior to scheduling a run. Note also that the bias values for a particular run are subsequently saved as an XML format file. Therefore, a new Bias file could be created by using the Default Bias file and then amending the required values prior to scheduling the run.

3.5

Limits for each Index to be classified a)

Use the Default Limits File The system has a default limits file defined which contains the limits that will be used for a run if no other limits file is provided – see Appendix 5 for example. Before scheduling the run it is then possible to amend limits as required. Note that any changes made are applicable for that run only and do not change the underlying default limits file.

b)

Change the Default Limits File It is possible to change the file that is defined as the Default Limits file via the Administration function (see separate guide). This might be useful if a number of future runs are to have the same limits. Note that it will still be possible to amend limits prior to scheduling a run.

c)

Upload a Limits File Rather than change the Default Limits file, it is possible to upload a Limits File for use during the particular run. This would be useful if the required limits are significantly different from the defaults. The user can either create a new Limits file or amend an existing file. Information about how this can be done is being provided separately but, for example, ‘Notepad++’ can easily be used to open, amend and save an existing XML file. Note that it will still be possible to amend limits prior to scheduling a run. Note also that the limits for a particular run are subsequently saved as an XML format file. Therefore, a new Limits file could be created by using the Default Limits file and then amending the required values prior to scheduling the run.

4.

Overview of Carrying out a Predict and Classify Run The stages for carrying out a Predict and Classify Run are as follows: a)

Access and Log In to RICT (if not already done) Full details of how to access and log in to RICT are provided in a separate document. However, it basically involves typing in the relevant URL to your browser and then entering your Username and Password. This will display the Home screen:

b)

Navigate to the Run Menu Click on Run Menu which will result in a page similar to the following being displayed:

c)

Create a New Run Click on ‘Create a New Run’ which will result in the following page being displayed:

d)

Select Run Type Click on ‘Predict and Classify’ which will result in the following page being displayed:

e)

Upload Files (if required) If any files are to be uploaded then click on Browse, which will result in a page similar to the following being displayed:

Then navigate to the required file using normal Windows functionality and either double-click on the filename or select the filename and click on Open. The file will then be uploaded to the RICT input area and a page similar to the following will be displayed. As part of the upload RICT will check to see if the format is recognised and, if so, the type of file will be displayed.

The above process should be repeated for all files that are to be uploaded. Once all files have been uploaded then click on Continue. This will result in the files being processed and validated. A page similar to the following is then displayed:

f)

Amend any Data At this point there are options to: -

Amend the Data provided to the run Amend the Settings applicable to the run Amend the Limits applicable to the run Amend the Bias data applicable to the run

i)

Amend the Data provided to the run This option will normally be used to manually enter data but can also be used to amend any data that has been loaded or add more data files to the run.

ii)

Amend the Settings applicable to the run The settings for the run will either have been taken from an uploaded settings file or the default settings file if no file has been uploaded. This option can be used to amend the settings if required. Note that these will only be applicable for the current run. Also note that the settings used will be saved in a settings file that can then be used for future runs if required.

iii)

Amend the Limits applicable to the run As for ii) above

iv)

Amend the Bias data applicable to the run As for ii) above

g)

Schedule the Run Once any required data has been amended, then click on Schedule Run. This will result in the run being scheduled and the Run Menu being displayed with the new run at the top – see below. Note that there is an option to delay the run for a specified period if necessary (e.g. if it is a large run that is best scheduled outwith normal hours) The run will initially be displayed with an ‘in progress’ icon and the page will refresh automatically until the run is complete, when a ‘complete’ icon will be displayed.

Run In progress:

Run complete:

h)

View/Extract Results

Once the job is complete then the results can be viewed/extracted as follows: -

Reports Access to the reports is via the shortcuts menu:

Detail to be added… -

Visualise If there is an internet connection, then the results can be viewed (using a google maps interface) via the shortcuts menu:

This will result in a page similar to the following being displayed:

Note that a more detailed guide of the Run Menu is provided in a separate document.

5.

Examples of Predict & Classify Runs A number of Predict & Classify examples are being prepared: Example 1

-

Upload XML EVs and OE files (use defaults for rest)

Example 2

-

Manual Input of EVs and OEs (use defaults for rest)

Appendix 1 – Sample XML Environmental Variable File WQMASTER 2008-02-14 Single Site 9875 <EV ID="NGR_LETTERS"> NGR_LETTERS NT <EV ID="NGR_EAST"> NGR_EAST 08192 <EV ID="NGR_NORTH"> NGR_NORTH 36934 <EV ID="ALTITUDE"> ALTITUDE 190 <EV ID="SLOPE"> SLOPE 1.1 <EV ID="DISCHARGE"> DISCHARGE 3 <EV ID="DIST_FROM_SOURCE"> DIST_FROM_SOURCE 11.4 <EV ID="MEAN_WIDTH"> MEAN_WIDTH 2.625 <EV ID="MEAN_DEPTH"> MEAN_DEPTH 40 <EV ID="ALKALINITY"> ALKALINITY 80.9581 <EV ID="BOULDER_COBBLES"> BOULDER_COBBLES 12.6667 <EV ID="PEBBLES_GRAVEL"> PEBBLES_GRAVEL 46.6667 <EV ID="SAND"> SAND 30.8333 <EV ID="SILT_CLAY"> SILT_CLAY 9.8333

Appendix 2 – Sample XML Observed/Expected Index File WQMASTER 2008-03-06 SEPA_3 5.655172413793103448 164 29 4.25 51 12 6.739130434782608696 155 23

Appendix 3 – Sample Settings File <Setting Name="End_Group_Set"> 3 <Setting Name="Season"> 5 <Setting Name="Indices_Set"> 2 <Setting Name="PEV_Set"> 1 <Setting Name="Output_File_Prefix"> (Date)_rict_(Run_ID)_ <Setting Name="Run_Name"> Sepa_(Run_ID) <Setting Name="Multi-Year"> N <Setting Name="Ref Adjust"> Y <Setting Name="Predict_Taxa"> N <Setting Name="Predict_Taxonomic_Level"> TL1 <Setting Name="Simulation Iterations"> 500

Appendix 4 – Sample Bias File 1.62 1.62 1.62 1.6524 1.6524 1.6524 1.7982 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Appendix 5 – Sample Limits File <Bucket Classification="H" ID="H" RANK="1"> .8879 10 <Bucket Classification="G" ID="G" RANK="2"> .8879 .7417 <Bucket Classification="M" ID="M" RANK="3"> .7417 .5954 <Bucket Classification="P" ID="P" RANK="4"> .5954 .491 <Bucket Classification="B" ID="B" RANK="5"> .491 0 <Bucket Classification="H" ID="H" RANK="1"> 1.0059 5 <Bucket Classification="G" ID="G" RANK="2"> 1.0059 .8918 <Bucket Classification="M" ID="M" RANK="3"> .8918 .7778 <Bucket Classification="P" ID="P" RANK="4"> .7778 .6533 <Bucket Classification="B" ID="B" RANK="5"> .6533 0