Start Submission Become a Reviewer

Reading: An Open Source Toolbox for Integrating Freshwater Social-Ecological Indicators in Basin Mana...


A- A+
Alt. Display

Software Metapapers

An Open Source Toolbox for Integrating Freshwater Social-Ecological Indicators in Basin Management


Kashif Shaad ,

Conservation International, Moore Center for Science, Arlington, VA, US
X close

Howard Alt

Sustainable Software, Boulder, CO, US
X close


The Freshwater Health Index (FHI) toolbox is an open source software in C# developed to guide ecological management of freshwater systems. It provides functionality to calculate basin-level freshwater social-ecological indicators, with algorithms for selected indicators also integrated with support for processing geospatial datasets. The toolbox archives the data necessary for calculating the indicators and can serve as a collaborative platform in a basin by providing users with the ability to initiate, edit and share a common freshwater basin database. Now available at GitHub and through the FHI website, the FHI toolbox offers a convenient yet rigorous way for basin-level freshwater management to maintain continuity and reproducibility amid numerous indicators assessed for freshwater basins.


Funding statement: This paper was written as part of the Freshwater Health Index development, funded by Victor and William Fung Foundation Limited, Betty and Gordon Moore, the Borrego Foundation, Flora Family Foundation and Starwood Foundation.

How to Cite: Shaad, K. and Alt, H., 2020. An Open Source Toolbox for Integrating Freshwater Social-Ecological Indicators in Basin Management. Journal of Open Research Software, 8(1), p.9. DOI:
  Published on 30 Mar 2020
 Accepted on 06 Mar 2020            Submitted on 13 Aug 2019

1 Introduction

Ensuring freshwater security requires an integrated assessment of the multi-faceted challenges in a freshwater basin that go beyond methods and indicators typically biased toward a discipline-specific (e.g., hydrology, ecology, economics) framing of the problem [9]. The Freshwater Health Index approach (FHI; [10]) was developed to help integrate the multiple and, at times, contradicting aspects of freshwater resource management. It asserts that evaluation of various freshwater ecosystem services, the trade-offs involved, and their sustainable management are best characterized by considering freshwater systems as a social-ecological unit linking human water uses, freshwater ecosystems and governance. As a first practical step in moving toward such systems thinking, FHI developed a set of indicators that measure “freshwater health” and highlight areas for management. This requires combining empirical and modelled datasets into indicators that monitor the state of freshwater ecosystems, assess how they are governed and identify the range of benefits they provide. The indicators through current baseline, historic assessment and future scenario development can help draw out the trade-offs in services involved, such as between hydropower, navigation and ecological impacts [5, 11]; land development, irrigation and urban water supply [3, 12], etc. Stakeholder engagement and interaction is key to this process of communication and ensures dissemination of relatable and actionable information to all. Details of the FHI process and its results from application in 5 study areas are available on the FHI website (

The FHI toolbox has been developed specifically to systematize and facilitate this process of collating monitored and modelled data for a broad range of audiences working at a drainage basin scale. Several scripts and software applications are available that compute one or more of the indices (or indicator frameworks) related to some aspect of freshwater management. The FHI toolbox attempts to harness and improve upon those learnings and package them in a common coherent framework. The primary function of the FHI toolbox is to support the calculation of the freshwater social-ecological indicators that make up the FHI. At the same time, it plays an important role in engaging the multiple agencies and stakeholders required to support sustainable water resource management. In this respect, it can be promoted as an extension of the collaborative basin management forums and platforms that exist – rather than as an alternative to them.

2 Implementation and architecture

2.1 Software framework

The FHI toolbox uses the Model-View-ViewModel (MVVM) architecture [1] and consists of two main projects. The first, Fhi, consists of the user interface with Views & ViewModels written as a Windows Presentation Foundation (WPF) application. FhiModel covers the Model component of MVVM, i.e., it contains all the data structures that are serialized into a FHIX file format. Two additional project Tests and WiX install cover tests for critical or complicated functionality in the toolbox and the production of the .msi installer, respectively. The toolbox provides the option to store and retrieve data from a local file, saved with the extension .fhix at a location specified by the user.

The choice to use the MVVM architecture was driven by the flexibility it offers in supporting different user interfaces applied to the model. The Model-View-ViewModel (MVVM) architecture is commonly used for Windows Presentation Foundation (WPF) applications [8] with several .NET frameworks and tools available that support it. The key criteria for selection was the isolation of the Model component, so that another user interface, such as a web front-end, could use the same data and algorithms in FhiModel. Also, the structure and decorations of the Model classes is such that the entire model can be serialized into a FHIX file with a minimum of application overhead.

Although the MVVM architecture is commonly criticized for being heavy weight [4], this challenge was mitigated by using simple publicly available classes instead of using a heavy weight framework like Prism [6].

2.2 Toolbox layout and key features

The key organizing principle of the FHI toolbox (Figure 1) is that indicators provide a level of abstraction of the underlying data. This not only allows a common baseline understanding of a basin (beyond a discipline-specific framing), when it comes to knowledge-sharing, it also has fewer barriers compared to actual monitored or modelled data.

Figure 1 

FHI toolbox and FHIX database in the landscape of various stakeholders and data in a basin.

To use the toolbox, either an existing database for a basin (.FHIX file) must be loaded or a new database initiated. The toolbox follows a layered approach to unify the interface for users that are either (1) exploring the “health” of a basin as encapsulated by the indicators; (2) adjusting parameters used for calculating the indicators; or (3) entering data for various social-ecological components of the freshwater basin. The top-level graphical user interface (GUI) displays the key GIS layers associated with the basin and offers three pathways to explore the “health” of a basin, namely:

  • Ecosystem Vitality (EV): Indicators and data linked to the state of the freshwater ecosystems
  • Ecosystem Services (ES): Indicators and data linked to freshwater-related services delivered to people dependent on the basin
  • Governance and Stakeholders (GS): Indicators and data linked to water governance, policy and management of the basin.

As a user moves from the top-level abstraction to underlying layers through the GUI, the ability to adjust indicator parameters and input data, as summarized in Table 1, are made available for edits. Any changes saved to the database of a basin only impacts the local copy of the database with no user-entered data uploaded to a web portal. This is a deliberate trade-off made to encourage confidence among institutions to use the best available data in the toolbox, without concerns of ‘losing control’ over the data – a common concern with water-realted data. The toolbox supports data porting, through which information from multiple versions of a database can be combined. Through this, original data providers retain control of what information from their version of the database gets transferred to a sharable version. This might be only the indicator score (on a scale of 0–100) with their interpretation of the score, or it could be the full backend datasets, as applicable.

Table 1

Indicator calculations (in brief) supported by the FHI toolbox.

Indicator/s Input data in brief Calculation parameters

Flow deviation Discharge time-series for regulated and unregulated conditions for outlet and other locations in the basin.
Groundwater Storage Total basin area and area impacted by over-extraction of groundwater.
Water quality Monitored time series data for water quality gauges. Selection of water quality parameters and the associated threshold
Land cover naturalness Spatial data on land cover for the basin. Weights (or degree of naturalness) associated with each land cover type
Channel modification Spatial data on land cover for the basin. Buffer zone considered along water body and weights associated with each cover type
Connectivity Vector river network and location of dams (and other instream structures obstructing flow) ‘Passability’ of each instream structure. Defined as the probability that an aquatic species will successfully cross the obstruction
Species of concern List of freshwater-associated native species in the basin, associated ‘Red list’ code and (optional) population estimates
Invasive species List of freshwater-associated invasive species in the basin and (optional) population estimates
Provisioning and regulating services Supply data of these services over the basin Criteria for ‘non-compliance’ based on demand
Recreation services Evaluated outside the toolbox through surveys and economic analysis
Conservation areas Map of protected area Target protection area or length (of water body) in a basin
Governance Output from survey of basin stakeholders

Freshwater social-ecological indicators are aggregated to higher-level summaries in the toolbox through geometric weighted averages. This aggregation should reflect the preferences among stakeholders within a basin so, to be an accurate reflection of the perceptions, are derived from AHP or similar weighting exercises completed by stakeholders. The resulting weights are entered into the toolbox and provide an additional level of context for the basin.

The primary use of the toolbox and database, therefore, is the “horizontal” circulation of information – i.e. to collect indicators scores and their descriptions from various dimensions of the freshwater social-ecological system that can be made available to a wide range of stakeholders, either through the interactive interface of the toolbox or through documents generated from it. However, the database also supports the archiving of both time series and geospatial data, with the toolbox providing the interface to manage this archived data. The import and export functionalities of the toolbox thus impose a minimum standard for data organization, portability and replicability of an FHI assessment carried out using the toolbox.

2.3 Sample application: single indicator

Consider a case where a user tries to apply a single indicator for a specific area within the Freshwater Health Index social-ecological domain. Further, by testing alternative data inputs and modifying the parameter space, insights into trends and sensitivity to prevalent conditions can be derived. For example [7], demonstrated the application of a connectivity index for five development scenarios in the Srepok, Sesan and Sekong basin of the Lower Mekong. The index used, the Dendritic Connectivity Index [2], is one of the indicators that can be now calculated through the FHI toolbox by following the sequence of steps guided by the toolbox GUI listed in Workflow 1. By applying different dam development scenarios (modifying input data) as well as testing the influence of dam state (modifying calculation parameters), initial insights are drawn regarding the impact of (and alternates to) the current development trajectory.

Workflow 1. Steps in toolbox GUI to calculate the Dendric Connectivity Index:

  • > Import River Network [Polyline shapefile or WKT CSV format]
  • > Select river outlet and create directional map through the import wizard
  • > Import dam/obstruction locations [Point shapefile or WKT CSV format]
  • > Snap points on the network or remove with import wizard (if not auto snapped)
  • > Edit and apply indicator parameter [passability for each dam]
  • > Adjust weights for migration patterns (internal & external pathways) if applicable

The toolbox derives the spatial layout of the river network from the input. Next, based on the outlet specified by the user, it creates a model of the river that includes direction of flow for each segment on the river network. The interface also allows limited corrections to both the river and dam dataset. For instance, if a point in the dam dataset does not fall near the river network – due to manual digitization errors or projection issues, etc. – then, the import wizard helps relocate the point or remove it from the assessment altogether. Storing the location and direction data in the FHIX database allows near real-time update of calculations for the river connectivity upon changing parameters.

2.4 Sample application: collation and archiving

At one level as seen with section 2.3, the FHI toolbox just enables calculation of the indicators listed in Table 1 with a GUI guided sequences of steps for each akin to the Workflow 1. However, the applications of the FHI framework in the Dongjiang basin in China [10] highlights additional challenges. These include 1) collecting and managing diverse datasets when considering repeatability of assessment, 2) facilitating the interpretation of results and 3) communicating the uncertainty of underlying data. The higher-level functions of toolbox that integrates organisation of indicators, handles indicator metadata and applies weights are central to addressing these challenges. The two panels on the left in Figure 2 lay out the main sections for navigation to individual indicator workflows. Each indicator has a metadata menu (right panel, Figure 2), accessible by right-click action over the indicator names.

Figure 2 

FHI toolbox panels: (Top-left) Home View; (Bottom-left) Ecosystem Vitality core and baseline indicators; (right) Indicator metadata panel.

Results for application for FHI in 5 basins, namely, Dongjiang basin (China), Alto Mayo Basin (Peru), Bogota Conservation Corridor (Colombia), Guandú Basin (Brazil) and a section of a transboundary basin of the lower Mekong (Cambodia, Lao and Vietnam) is available through the FHI website and linked publications.

3 Availability

Operating system

Windows 10 version 1507 or higher

Programming language

C#, Visual Studios 2019 Community Edition


.NET Framework (>= 4.6.2), .NET Standard (>= 2.0.3) & ArcGIS Runtime SDK for .NET

List of contributors

Kashif Shaad, Howard Alt, Sarah Hauck, Derek Vollmer, Nick Souter, Maira Bezerra, Maria Marques

Software location


Name: GitHub


Licence: MIT license (MIT)

Version published: 1.1

Date published: June 2019

The windows installer for the FHI toolbox is made available at the URL: (



4 Reuse potential

Developed as an open source software and written in C#, the FHI toolbox (and the local database it creates) expands beyond existing systems that focus on data or indicators from a smaller subset of disciplines affecting freshwater management. These indicators span the biophysical state of the freshwater ecosystems, the perceived gap between demand and supply of freshwater services as well as the state and operation of water governance in a given basin, which are relevant to freshwater basins globally. Building on the practical experience of bringing stakeholders together and working on the translation of science to policy (gathered during the development of the FHI methods), this toolbox aims to facilitate a process of information exchange while providing a robust grounding in locally-relevant data – and assist in making the process replicable. A quick start manual, a series of how-to videos, and tutorial datasets for the toolbox have been made available at

While the FHI toolbox introduces a new element when considering integrated freshwater management at the basin scale, it is by no means exhaustive. As the application of freshwater social-ecological indicators expand into new contexts and geographies; the development and proliferation of novel data monitoring methods for all dimensions of freshwater sciences continues; and the emphasis on ecological management of freshwater systems increases, the range of indicators included in this initial version and their calculation requirements will need to refine and grow. Additionally, while the current version has been deliberately developed as a desktop application with a local database, a web-based application supported by a federated database and more advanced analytic tools is another plausible future direction for development. The authors have attempted to design the software architecture anticipating this on-going need for change and adaptation. The FHI toolbox is available under the MIT license and encourages third-party contributions. The FHI website ( is also available to report bugs, raise questions and propose enhancements, as well as to access training material for the toolbox.


Special thanks to the FHI Science team and the Conservation International field teams in China, Cambodia, Brazil, Peru and Colombia for providing active input that helped shape the toolbox.

Competing Interests

The authors have no competing interests to declare.


  1. Anderson, C 2012 The Model-View-ViewModel (MVVM) Design Pattern. In: Pro Business Applications with Silverlight 5. Berkeley, CA: Apress. DOI: 

  2. Cote, D, Kehler, D G, Bourne, C and Wiersma, Y F 2009 A new measure of longitudinal connectivity for stream networks. Landscape Ecology, 24(1): 101–113. DOI: 

  3. Cruz, B B, Manfré, L A, Ricci, D S, Brunoro, D, Appolinario, L, Jr and Quintanilha, J A 2017 Environmental fragility framework for water supply systems: A case study in the Paulista Macro Metropolis area (SE Brazil). Environmental Earth Sciences, 76(12): 441. DOI: 

  4. Gossman, J 2006 Advantages and disadvantages of M-V-VM. URL: 

  5. Kuriqi, A, Pinheiro, A N, Sordo-Ward, A and Garrote, L 2017 Trade-off between environmental flow policy and run-of-river hydropower generation in Mediterranean climate. Eur. Water, 60: 123–130. 

  6. Lagunas, B and Siegel, D 2015 Prism, GitHub Repository. URL: 

  7. Shaad, K, Souter, N J, Farrell, T, Vollmer, D and Regan, H M 2018 Evaluating the sensitivity of dendritic connectivity to fish pass efficiency for the Sesan, Srepok and Sekong tributaries of the Lower Mekong. Ecological Indicators, 91: 570–574. DOI: 

  8. Smith, J 2009 Patterns – WPF Apps With The Model-View-ViewModel Design Pattern. URL: 

  9. Vogel, R M, Lall, U, Cai, X, Rajagopalan, B, Weiskel, P K, Hooper, R P and Matalas, N C 2015 Hydrology: The interdisciplinary science of water. Water Resources Research, 51(6): 4409–4430. DOI: 

  10. Vollmer, D, Shaad, K, Souter, N J, Farrell, T, Dudgeon, D, Sullivan, C A, McNally, A, et al. 2018 Integrating the social, hydrological and ecological dimensions of freshwater health: The Freshwater Health Index. Science of the Total Environment, 627: 304–313. DOI: 

  11. Wild, T B, Reed, P M, Loucks, D P, Mallen-Cooper, M and Jensen, E D 2019 Balancing hydropower development and ecological impacts in the Mekong: Tradeoffs for sambor mega dam. Journal of Water Resources Planning and Management, 145(2): 05018019. DOI: 

  12. Zabalza-Martínez, J, Vicente-Serrano, S M, López-Moreno, J I, Borràs Calvo, G, Savé, R, Pascual, D, Tague, C L, et al. 2018 The Influence of Climate and Land-Cover Scenarios on Dam Management Strategies in a High Water Pressure Catchment in Northeast Spain. Water, 10(11): 1668. DOI: 

comments powered by Disqus