***DRAFT*** ***DRAFT***

River Invertebrates Classification Tool (RICT)

User Documentation

1. Guide to Predict and Classify (Interactive Mode)

1. Introduction

This document provides a guide to the interactive Predict and Classify process within RICT.

It contains:

a) a summary of the data that needs to be provided to RICT

b) options for how this data can be provided
c) an overview of how to carry out a P&C run
d) 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
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Datasets NS1:noNamespaceSchemaLocation="ev.xsd" xmlns:NS1="http://www.w3.org/2001/XMLSchema-instance">
<Creator>WQMASTER</Creator>
<Creation_Date>2008-02-14</Creation_Date>
<Name>Single Site</Name>
<Dataset ID="9875" Year="2007">
<Name>9875</Name>
<EV ID="NGR_LETTERS">
<Description>NGR_LETTERS</Description>
<Value>NT</Value>
</EV>
<EV ID="NGR_EAST">
<Description>NGR_EAST</Description>
<Value>08192</Value>
</EV>
<EV ID="NGR_NORTH">
<Description>NGR_NORTH</Description>
<Value>36934</Value>
</EV>
<EV ID="ALTITUDE">
<Description>ALTITUDE</Description>
<Value>190</Value>
</EV>
<EV ID="SLOPE">
<Description>SLOPE</Description>
<Value>1.1</Value>
</EV>
<EV ID="DISCHARGE">
<Description>DISCHARGE</Description>
<Value>3</Value>
</EV>
<EV ID="DIST_FROM_SOURCE">
<Description>DIST_FROM_SOURCE</Description>
<Value>11.4</Value>
</EV>
<EV ID="MEAN_WIDTH">
<Description>MEAN_WIDTH</Description>
<Value>2.625</Value>
</EV>
<EV ID="MEAN_DEPTH">
<Description>MEAN_DEPTH</Description>
<Value>40</Value>
</EV>
<EV ID="ALKALINITY">
<Description>ALKALINITY</Description>
<Value>80.9581</Value>
</EV>
<EV ID="BOULDER_COBBLES">
<Description>BOULDER_COBBLES</Description>
<Value>12.6667</Value>
</EV>
<EV ID="PEBBLES_GRAVEL">
<Description>PEBBLES_GRAVEL</Description>
<Value>46.6667</Value>
</EV>
<EV ID="SAND">
<Description>SAND</Description>
<Value>30.8333</Value>
</EV>
<EV ID="SILT_CLAY">
<Description>SILT_CLAY</Description>
<Value>9.8333</Value>
</EV>
</Dataset>
</Datasets>
Appendix 2 – Sample XML Observed/Expected Index File
<Datasets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="oei.xsd">
<Creator>WQMASTER</Creator>
<Creation_Date>2008-03-06</Creation_Date>
<Name>SEPA_3</Name>
<Dataset Site_ID="9875" Year="2007">
<Index ID="ASPT" Name="ASPT">
<Observed_Value>5.655172413793103448</Observed_Value>
</Index>
<Index ID="BMWP" Name="BMWP">
<Observed_Value>164</Observed_Value>
</Index>
<Index ID="NTAXA" Name="NTAXA">
<Observed_Value>29</Observed_Value>
</Index>
</Dataset>
<Dataset Site_ID="10480" Year="2007">
<Index ID="ASPT" Name="ASPT">
<Observed_Value>4.25</Observed_Value>
</Index>
<Index ID="BMWP" Name="BMWP">
<Observed_Value>51</Observed_Value>
</Index>
<Index ID="NTAXA" Name="NTAXA">
<Observed_Value>12</Observed_Value>
</Index>
</Dataset>
<Dataset Site_ID="11030" Year="2007">
<Index ID="ASPT" Name="ASPT">
<Observed_Value>6.739130434782608696</Observed_Value>
</Index>
<Index ID="BMWP" Name="BMWP">
<Observed_Value>155</Observed_Value>
</Index>
<Index ID="NTAXA" Name="NTAXA">
<Observed_Value>23</Observed_Value>
</Index>
</Dataset>
</Datasets>
Appendix 3 – Sample Settings File
<Datasets xmlns:xdb="http://xmlns.oracle.com/xdb" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="settings.xsd">
<Dataset ID="0" Name="Rict">
<Setting Name="End_Group_Set">
<Value>3</Value>
</Setting>
<Setting Name="Season">
<Value>5</Value>
</Setting>
<Setting Name="Indices_Set">
<Value>2</Value>
</Setting>
<Setting Name="PEV_Set">
<Value>1</Value>
</Setting>
<Setting Name="Output_File_Prefix">
<Value>(Date)_rict_(Run_ID)_</Value>
</Setting>
<Setting Name="Run_Name">
<Value>Sepa_(Run_ID)</Value>
</Setting>
<Setting Name="Multi-Year">
<Value>N</Value>
</Setting>
<Setting Name="Ref Adjust">
<Value>Y</Value>
</Setting>
<Setting Name="Predict_Taxa">
<Value>N</Value>
</Setting>
<Setting Name="Predict_Taxonomic_Level">
<Value>TL1</Value>
</Setting>
<Setting Name="Simulation Iterations">
<Value>500</Value>
</Setting>
</Dataset>
</Datasets>
Appendix 4 – Sample Bias File
<?xml version="1.0" encoding="WINDOWS-1252" standalone='no'?>
<Datasets NS0:noNamespaceSchemaLocation="bias.xsd" xmlns:NS0="http://www.w3.org/2001/XMLSchema-instance">
<Dataset Index_Name="NTAXA" Season_ID="1">
<Value>1.62</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="2">
<Value>1.62</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="3">
<Value>1.62</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="4">
<Value>1.6524</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="5">
<Value>1.6524</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="6">
<Value>1.6524</Value>
</Dataset>
<Dataset Index_Name="NTAXA" Season_ID="7">
<Value>1.7982</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="1">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="2">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="3">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="4">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="5">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="6">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="ASPT" Season_ID="7">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="1">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="2">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="3">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="4">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="5">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="6">
<Value>0</Value>
</Dataset>
<Dataset Index_Name="BMWP" Season_ID="7">
<Value>0</Value>
</Dataset>
</Datasets>
Appendix 5 – Sample Limits File
<Datasets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="limits.xsd">
<Dataset Type="Default" ID="Default" Description="Default Limit Set">
<Index NAME="NTAXA">
<Bucket Classification="H" ID="H" RANK="1">
<Lower_Bound Operator="gte">.8879</Lower_Bound>
<Upper_Bound Operator="gte">10</Upper_Bound>
</Bucket>
<Bucket Classification="G" ID="G" RANK="2">
<Upper_Bound Operator="lt">.8879</Upper_Bound>
<Lower_Bound Operator="gte">.7417</Lower_Bound>
</Bucket>
<Bucket Classification="M" ID="M" RANK="3">
<Upper_Bound Operator="lt">.7417</Upper_Bound>
<Lower_Bound Operator="gte">.5954</Lower_Bound>
</Bucket>
<Bucket Classification="P" ID="P" RANK="4">
<Upper_Bound Operator="lt">.5954</Upper_Bound>
<Lower_Bound Operator="gte">.491</Lower_Bound>
</Bucket>
<Bucket Classification="B" ID="B" RANK="5">
<Upper_Bound Operator="lt">.491</Upper_Bound>
<Lower_Bound Operator="gte">0</Lower_Bound>
</Bucket>
</Index>
<Index NAME="ASPT">
<Bucket Classification="H" ID="H" RANK="1">
<Lower_Bound Operator="gte">1.0059</Lower_Bound>
<Upper_Bound Operator="gte">5</Upper_Bound>
</Bucket>
<Bucket Classification="G" ID="G" RANK="2">
<Upper_Bound Operator="lt">1.0059</Upper_Bound>
<Lower_Bound Operator="gte">.8918</Lower_Bound>
</Bucket>
<Bucket Classification="M" ID="M" RANK="3">
<Upper_Bound Operator="lt">.8918</Upper_Bound>
<Lower_Bound Operator="gte">.7778</Lower_Bound>
</Bucket>
<Bucket Classification="P" ID="P" RANK="4">
<Upper_Bound Operator="lt">.7778</Upper_Bound>
<Lower_Bound Operator="gte">.6533</Lower_Bound>
</Bucket>
<Bucket Classification="B" ID="B" RANK="5">
<Upper_Bound Operator="lt">.6533</Upper_Bound>
<Lower_Bound Operator="gte">0</Lower_Bound>
</Bucket>
</Index>
</Dataset>
</Datasets>