index.md
hetoolkit
Overview
The hetoolkit package comprises a collection of 23 functions,
developed by APEM Ltd on behalf of the Environment Agency, to assemble,
process, visualise and model hydroecological (HE) data. The full set of
functions are listed under the Reference tab above. Note that they
include deprecated versions of three functions that are retained for
back-compatibility.
Background
There is growing awareness of the need for better empirical evidence in water resources decision-making. HE modelling is an emerging field that offers the opportunity to develop statistically powerful tools to predict the ecological impacts of water resources activities, such as abstraction, by relating data on an ecological receptor to antecedent hydrological (plus other environmental) predictors. The most powerful models are those that ‘pool’ data from multiple sites that span the environmental gradient(s) of interest (e.g. abstraction pressure) to create a large calibration dataset, making it possible to predict the ecological impacts of changes in flow under a range of environmental conditions.
HE modelling has various areas of intended application, from no deterioration investigations and water company drought plan environmental assessments to local flow constraint proposals. Any water company or consultant using the toolkit for an official purpose such as these should first ensure they are familiar with the relevant statutory guidance and other Environment Agency publications. They may also find the FAQs tab above helpful.
Short of full HE model development and beyond the specific field of
hydroecology, the hetoolkit package has various potential uses, such
as collating Environment Agency monitoring data, summarising flow data
and pairing environmental and ecological datasets.
Workflow
The different functions link together as shown in the flow chart below:
Installation
To install the latest release of hetoolkit use the following code:
install.packages("remotes")
library(remotes)
remotes::install_github("APEM-LTD/hetoolkit")
library(hetoolkit)
As an alternative, the ‘devtools’ package can be used:
install.packages("devtools")
library(devtools)
install_github("APEM-LTD/hetoolkit")
library(hetoolkit)
It is recommended that you install hetoolkit into a blank project and
use the renv package to avoid clashes with previously installed
versions of dependent packages.
After running the install_github commands, you may get a message stating that some packages have a more recent version available, followed by a menu. This appears if any of the dependent packages required for the toolkit have a more recent version available than you currently have installed. Packages may be updated, however this is not required for the hetoolkit package to run.
To skip the updates, either enter 3 in the console or simply press return. Note that if you run one of the full code blocks above all at once (ie, highlight all four lines and run them together) then this is skipped and no updates are made to the packages.
You may also get warning messages regarding unused arguments on installing the packages. These relate to arguments in function definitions that have been removed from the main body of the function but not the definition. These will be removed but in the meantime will not affect the running of the toolkit.
Development
The hetoolkit package was developed by APEM LTD on behalf on the
Environment Agency. For further information please contact the
Environment
Agency.
Change history
Version Date Details 1.0.0 May-2021 New release 2.0.0 Dec-2022 Added new function impute_flows. Major updates to calc_flowstats, predict_indices and join_he. Bug fixes and vignette updates. 2.1.0 Mar-2023 Added new function import_wq. Minor corrections to documentation (typos, etc). Updates to import_rhs to bring it in line with other import functions. Minor bug fixes. 2.1.1 May-2023 Updates to website. Minor update to predict_indices. 2.1.2 Jan-2024 Added new function import_inv_taxa. Bug fix to import_rhs, minor update to import_wq.Details of recent changes to the current version of the package, including website updates, are listed in the Updates tab above.
Help and advice
Questions about using the HE Toolkit and HE modelling more generally can be sent to the EA National Hydroecology Team (hydroecologyteam@environment-agency.gov.uk). Please also see the list of FAQs under the Articles menu above.
Examples
Some examples of how to use the toolkit for HE modelling can be found in the vignette and case studies, under the Articles menu above. Beyond the toolkit’s core functions these illustrate a range of methods relevant to the processing and analysis of HE data, from generalised additive modelling to harmonising taxonomic data.
Reporting Bugs
If you believe you’ve found a bug in hetoolkit, please log an issue
(and, if possible, a reproducible example) at
https://github.com/APEM-LTD/hetoolkit/issues. For more feature
requests, feedback and other general queries, please contact the
hetoolkit development team at APEM via hetoolkit@apemltd.co.uk.
Citations
To cite the hetoolkit package in publications please use:
Dunbar, M., Brown, R., Gordon, I., Gallagher, K. and Davey, A. (2023) hetoolkit: Hydro-Ecology Toolkit, R package version 2.1.0. ; https://github.com/APEM-LTD/hetoolkit
For full citation, including BibTex entry, use citation(“hetoolkit”).
References
FBA, 2020. River Invertebrate Classification Tool (RICT2) User Guide V1.5 (2020) [Online] Available at: https://www.fba.org.uk/FBA/Public/Discover-and-Learn/Projects/User%20Guides.aspx
Licence
The R-Code included within the Hydro-Ecology Toolkit package is licensed under GPL-V3 (see: https://www.gnu.org/licenses/gpl-3.0.en.html).
The Hydro-Ecology Toolkit package contains public sector information licensed under the Open Government Licence v3.0. Licence information is available at: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
Disclaimer
This software has been approved for release by the Environment Agency (EA). Although the software has been subjected to review and testing, the EA reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the EA as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that the EA shall not be held liable for any damages resulting from its authorized or unauthorized use.
