• GloWPa
• 1 Installation
• 2 Model Input
• 3 Model Setup
  • 3.1 Model Options
  • 3.2 Logger Settings
  • 3.3 Input Settings
    • 3.3.1 Human Input
    • 3.3.2 Livestock Input
    • 3.3.3 Hydrology Input
    • 3.3.4 Output Settings
    • 3.3.5 Constants
• 4 Run GloWPa
• 5 Model Output
• 6 Contributing
  • 6.1 Setup Development Environment
    • RStudio
    • RStudio Docker
  • 6.2 Contribution Workflow
  • 6.3 Contributing Conventions
  • 6.4 Test Suite
  • 6.5 Manage Packages
• Datasets
  • Global Gridded Population
  • Global Population Dynamics
  • Human Development Index (HDI)
  • Pathogen Properties
  • Sanitation
  • Waste Water Treatment
  • Hydrology
  • Meteorology
  • Livestock
• References

GloWPa

The GloWPa (Global Waterborne Pathogen) model simulates emissions of pathogens (currently Cryptosporidium and Rotavirus) to surface water (Hofstra & Vermeulen, 2016). These pathogens are known to be a leading cause of diarrhoeal diseases among people that are exposed to high concentrations. GloWPa focuses on human and livestock emissions of pathogens that end up in surface water systems through various pathways.

1 Installation

The GloWPa model R package can be installed from the GitLab repository using the R package devtools. Install the master version from GitLab:

install.packages("devtools")
devtools::install_gitlab("glowpa/glowpa-r",host="https://git.wur.nl/")

You can also install other versions from GitLab by extending the repository address using the ⁠format username/repo[@ref]⁠. To install tagged versions like e.g. 0.1.0 version you can use:

devtools::install_gitlab("glowpa/glowpa-r@0.1.0",host="https://git.wur.nl/")

Run example:

library(glowpa)
example("glowpa_start")
#> 
#> glwp_s> example_settings <- system.file("extdata/kla", "kla_rotavirus.yaml",
#> glwp_s+   package = "glowpa"
#> glwp_s+ )
#> 
#> glwp_s> glowpa_init(example_settings)
#> Warning in file(con, "r"): file("") only supports open = "w+" and open = "w+b":
#> using the former
#> 
#> glwp_s> glowpa_start()
#> 
#> glwp_s> glowpa_run <- glowpa_get_run()
#> 
#> glwp_s> list.files(glowpa_run$settings$output$dir, pattern = ".tif|.csv")
#> [1] "human_emissions_rotavirus_kla_land.csv" 
#> [2] "human_emissions_rotavirus_kla_land.tif" 
#> [3] "human_emissions_rotavirus_kla_water.csv"
#> [4] "human_emissions_rotavirus_kla_water.tif"
#> [5] "land_emissions.csv"                     
#> [6] "surface_water_emissions.csv"            
#> 
#> glwp_s> terra::plot(log10(glowpa_run$emissions$pathways$rast),
#> glwp_s+   col =
#> glwp_s+     hcl.colors(50, palette = "Geyser")
#> glwp_s+ )

2 Model Input

A set of data sources has been collected and is available on request. The prepare_data function can be used to generate global or country scale model input at a given GADM level and various spatial resolutions based on this pre-defined set of data sources. More information about the data sources can be found in section Datasets

library(glowpa)
datasource_dir <- "/home/data/glowpa/datasources"
# generate global input data at 30min (0.5 deg) resolution using country borders
prepare_data(datasource_dir, "input/global", res = 0.5, country = NA, level = 0)
# generate Uganda input data at 5min resolution using GADM level 1 borders.
prepare_data(datasource_dir, "input/uga"  , res = 5/60, country = "UGA", level = 1)

3 Model Setup

The model setup needs to specified in a yaml configuration file.

3.1 Model Options

population:
  correct: TRUE # TRUE | FALSE
wwtp:
  treatment: AREA # AREA | POINT
livestock: 
  enabled: FALSE # TRUE | FALSE
hydrology:
  enabled: FALSE # TRUE | FALSE
pathogen: rotavirus # rotavirus | cryptosporidium | any other

3.2 Logger Settings

logger:
  enabled: TRUE # TRUE | FALSE
  threshold: <value>    # FATAL | ERROR | WARN | SUCCESS | INFO | DEBUG | TRACE
  file: <path_to_file>
  appender: CONSOLE # CONSOLE | FILE | TEE

3.3 Input Settings

3.3.1 Human Input

input:
  isoraster: <path_to_file>
  isodata: <path_to_file>
  wwtp: <path_to_file>
  pathogen: <path_to_file>
  population:
    urban: <path_to_file>
    rural: <path_to_file>

Isoraster

The isoraster input file is used to produce gridded output of pathogen emissions by mapping the isodata properties by iso to the model grid cells. The isoraster also determines the model resolution, domain and mask. All no data values will be masked. Example of isoraster grid:

isoraster_file <- system.file("extdata/kla/isoraster_kla.tif", package = "glowpa")
isoraster <- terra::rast(isoraster_file)
terra::plot(isoraster)

Isodata

Example of the isodata file:

isodata_file <- system.file("extdata/kla/glowpa_isodata_kla.RDS", package = "glowpa")
df_isodata <- readRDS(isodata_file)
head(df_isodata)

The supporting table with column names and descriptions does contain placeholders for pathogen_type (virus/protozoa) and area_type (urb/rur) to limit the table length.

WWTP

wwtp_file <- system.file("extdata/kla/wwtp_kla.RDS",package = "glowpa")
wwtp <- readRDS(wwtp_file)
head(wwtp)

Pathogen

The pathogen input file is tabular data holding properties of various pathogens selected by the modeler. Currently only the name and pathogen_type is used to estimate the pathogen loads from human emissions. The declared pathogen in the model settings is used to lookup the pathogen properties by name.

Example:

3.3.2 Livestock Input

The methodology to calculate pathogen emissions from livestock animals has been described by Vermeulen et al. (2017).

input:
  temperature:
    year: <path_to_file>
  manure:
    management_systems: <path_to_file>
  livestock:
    animal_isoraster: <path_to_file>
    production_systems: <path_to_file>
    manure_fractions: <path_to_file>
    animals:
      asses: 
        isodata: <path_to_file>
        heads: <path_to_file>
      buffaloes: 
        isodata: <path_to_file>
        heads: <path_to_file>
      camels: 
        isodata: <path_to_file>
        heads: <path_to_file>
      cattle: 
        isodata: <path_to_file>
        heads: <path_to_file>
      chickens: 
        isodata: <path_to_file>
        heads: <path_to_file>
      ducks: 
        isodata: <path_to_file>
        heads: <path_to_file>
      goats: 
        isodata: <path_to_file>
        heads: <path_to_file>
      horses: 
        isodata: <path_to_file>
        heads: <path_to_file>
      mules: 
        isodata: <path_to_file>
        heads: <path_to_file>
      pigs: 
        isodata: <path_to_file>
        heads: <path_to_file>
      sheep:
        isodata: <path_to_file>
        heads: <path_to_file>

Manure Management Systems

The manure management systems input is tabular data holding the fractions of various manure management systems for each livestock type in the administrative areas. The data column can be missing if any of the specified manure management systems is not applicable on a given livestock type. The model will consider this fraction to be zero. The following livestock types must be prepared:

• cattle
• buffaloes
• pigs
• poultry
• sheep
• goats
• horses
• asses
• mules
• camels

According to the description, used for fuel includes both manure going to anaerobic digesters and manure that is burned for fuel. We therefore assume that half of the manure in this category leaves the system, and the other half ends up on land after a 2 log reduction in infectivity.

example:

Livestock Production Systems

The livestock production systems input is tabular data holding the partition between intensive and extensive livestock production systems for each livestock type in the administrative areas. The following livestock types must be used:

• meat
• dairy
• buffaloes
• pigs
• poultry
• sheep
• goats
• horses
• asses
• mules
• camels

For cattle the model takes the average of dairy and meat.

example:

Livestock Manure Fractions

The livestock manure follows pathways to (1)land, (2)other uses and (3)manure storage and requires input to partition the total manure from livestock in the production systems. The livestock manure fractions input dataset (tabular data) holds the fraction to partition the manure from grazing livestock towards land(1) and to other uses(3) in different production system (intensive/extensive) for each livestock type. The manure fraction from livestock to manure storage(3) (fsi/fse) is determined inside the model by $fsi=(1-foi) * (1-fgi)$ for intensive systems and similar for extensive systems. The following livestock types are required:

• meat
• dairy
• buffaloes
• pigs
• poultry
• sheep
• goats
• horses
• asses
• mules
• camels

For cattle the model takes the average of dairy and meat.

Livestock Animal Isoraster

The livestock animal isoraster is used to rasterize the animal the animal isodata properties to the model domain. The animal isoraster file is only required in case the animal iso values do not match the iso values in the model domain.

Livestock Animal Isodata

The livestock animal isodata input datasets holds properties used to model the yearly emitted pathogen particles from animals. An input file needs to be prepared for each animal. The associated livestock type is mentioned in parentheses.

• asses (asses)
• buffaloes (buffaloes)
• camels (camels)
• cattle (cattle)
• chickens (poultry)
• ducks (poultry)
• goats (goats)
• horses (horses)
• mules (mules)
• pigs (pigs)
• sheep (sheep)

example for cattle:

3.3.3 Hydrology Input

The methodology to compute river loads and concentrations has been developed and described by Vermeulen et al. (2019).

input: 
   hydrology:
    runoff: <path_to_directory>
    discharge: <path_to_directory>
    river_temperature: <path_to_directory>
    river_depth: <path_to_directory>
    river_restime: <path_to_directory>
    ssrd: <path_to_directory>
    doc: <path_to_file>
  routing:
    flowdir: <path_to_file>
    flowacc: <path_to_file>

All hydrology and routing input files are required when the option hydrology.enabled is set to TRUE.

Example of monthly runoff files:

list.files("inst/extdata/global/hydrology/runoff/", pattern = ".tif$")
 [1] "runoff_daymonmean_m01.tif" "runoff_daymonmean_m02.tif"
 [3] "runoff_daymonmean_m03.tif" "runoff_daymonmean_m04.tif"
 [5] "runoff_daymonmean_m05.tif" "runoff_daymonmean_m06.tif"
 [7] "runoff_daymonmean_m07.tif" "runoff_daymonmean_m08.tif"
 [9] "runoff_daymonmean_m09.tif" "runoff_daymonmean_m10.tif"
[11] "runoff_daymonmean_m11.tif" "runoff_daymonmean_m12.tif"

The flow direction should be specified as follows:

-	-	-
32	64	128
16	0	1
8	4	2

3.3.4 Output Settings

output:
  dir: output
  sources: 
    human: # source attribution from sanitation types to land and water
      land: human_sources_land_crypto_global.csv 
      surface_water: human_sources_water_crypto_global.csv
    livestock: # source attribution from animal types to land and water
      land: livestock_sources_land_crypto_global.csv
      surface_water: livestock_sources_water_crypto_global.csv
  sinks: # gridded and tabular pathogen loads in land and water.
      surface_water:
        table: surface_water_emissions_crypto_global.csv
        grid: surface_water_emissions_crypto_global.tif
      land:
        table: land_emissions_crypto_global.csv
        grid: land_emissions_crypto_global.tif
      wwtp:
        table: wwtp_emissions_crypto_global.csv
        grid: wwtp_emissions_crypto_global.tif
      manure_storage:
        table: manure_storage_emissions_global.csv
        grid: manure_storage_emissions_global.tif
  hydrology:  # monthly routed pathogen loads and concentrations in rivers 
    loads: stream_loads_crypto_global_ # -> {output.dir}/hydrology/loads
    concentration: stream_concentration_crypto_global_  # {output.dir}/hydrology/conc

Default output settings:

sources:
  human:
    surface_water: human_sources_surface_water.csv
    land: human_sources_land.csv
  livestock:
    surface_water: livestock_sources_surface_water.csv
    land: livestock_sources_land.csv
sinks:
  surface_water:
    grid: surface_water_emissions.tif
    table: surface_water_emissions.csv
  land:
    grid: land_emissions.tif
    table: land_emissions.csv

3.3.5 Constants

constants:
  runoff_fraction: 0.025
  threshold_discharge: 1

4 Run GloWPa

Example script to run the model:

# load the glowpa model R package
library(glowpa)

# Path to GloWPa model settings. Here we refer to example settings which comes with the GloWPa installation.
# The function system.file will find the full file name of internal package data.
# You can also refer to your own model settings file.
f_settings <- system.file("extdata/kla/kla_rotavirus.yaml", package="glowpa")

# glowpa_init will initialize the model and performs validations on the model settings and input data. 
glowpa::glowpa_init(f_settings)
#> Warning in file(con, "r"): file("") only supports open = "w+" and open = "w+b":
#> using the former

# glowpa_start will start the model simulation
glowpa::glowpa_start()

5 Model Output

# retrieve in-memory model run
glowpa_run <- glowpa::glowpa_get_run()
# read human emissions to surface water from the sanitation sources in each administrative area (tabular data)
df_humans_emissions <- read.csv(file.path(glowpa_run$settings$output$dir ,glowpa_run$settings$output$sources$human$surface_water))

# read gridded output
rast_surface_water <- terra::rast(file.path(glowpa_run$settings$output$dir, glowpa_run$settings$output$sinks$surface_water$grid))

# download administrative boundaries of Uganda
uga = geodata::gadm('UGA',path = '.', level=3, resolution = 1)

# plot map of the log10 pathogen emissions per grid per year
terra::plot(log10(rast_surface_water), main='rotavirus surface water emissions in Kampala (UGA)', type='interval', breaks=seq(5,17), col= colorRampPalette(c("midnightblue","blue3","yellow","red3","darkred"), interpolate='linear')(12), plg=list(title='log10 particals/grid/year'))

# plot boundaries
terra::plot(uga,add=T)

6 Contributing

6.1 Setup Development Environment

You can use RStudio or Docker to setup a development environment. A Docker image including RStudio and project dependencies are available inside the git project.

RStudio

Step 1: Get the source code

git clone https://git.wur.nl/glowpa/glowpa-r.git

Step 2: Install dependencies:

# somehow renv does not resolve the git repo when using install and fails to find the package on the CRAN repo.
renv::install(exclude = "pathogenflows")
renv::install("git::https://git.wur.nl/glowpa/pathogenflows.git@be452603dc14512b57c3288635bec0960f7d9ce4")

RStudio Docker

Step 1: Install Docker and Docker Compose

Step 2: Get the source code

git clone https://git.wur.nl/glowpa/glowpa-r.git

Step 3: Run

cd glowpa
docker compose build rstudio
docker compose up rstudio -d

It will take a while before the Docker Image is built, because it will install all depending project dependencies. Rstudio Server runs on port 8989 and the glowpa folder is a shared volume on your host machine. Nagivate to localhost:8989.

Step 4:

Open the glowpa RStudio project.

6.2 Contribution Workflow

Step 1: Follow instructions in Setup Development Environment.

Step 2: Create an GitLab issue and describe the changes you want to implement in the model.

Step 3: Create a new feature branch from the GitLab issue.

Step 4: Fetch the newly created feature branch from the remote repository and checkout the feature branch. The feature-branch can be any name generated from the GitLab issue.

git fetch
git checkout feature-branch

Step 5: Implement, commit and push new changes to the feature branch. Please following our (code) conventions.

Step 6: Create a GitLab merge request to start the review process.

Step 7: Once the reviewer accept your changes your changes will be merged with the main model source code.

6.3 Contributing Conventions

• Run tests and perform an automatic check if the package can be build and installed. Fix all failed tests and warnings.

  devtools::check(error_on = "warning")
  

• Use the styler and lintr packages to style the code files in the R directory to improve code readability.

  # automatic styler
  styler::style_dir("R") 
  # try to solve most of the found warning from the lintr
  lintr::lint_dir("R")
  

• Document (exported) functions and data using roxygen and generate automatic documentation.

  devtools::document()
  

• Bump the version number once the code is ready to be merged to the main branch. We follow the tidyverse package version conventions for our stable and in-development versions.

  <major>.<minor>.<patch>        # released version
  <major>.<minor>.<patch>.<dev>  # in-development version
  

  usethis::use_version()
  

• Please keep the model documentation in the README file up to date.

6.4 Test Suite

Unit and regression tests are made using the testthat package. An overall test-report is available. The regression tests currently generates maps and reports from the land and surface water pathogen emissions which can are compared against earlier versions. Moreover, snapshot tests are included to detect any changes in model output values by running three model setups.

Kampala Model

• maps
• test report

Uganda Livestock Model

• maps
• test report

Rhine basin Model

• test report

6.5 Manage Packages

Check status of development environment.

renv::status(dev = T)

Updating the package lock file for development.

renv::snapshot(type = "explicit", dev = T)

Datasets

The GloWPa model installation includes a global dataset at 0.5 degree resolution which can be used as an example. The used input datasets are described in the sections below.

Global Gridded Population

Data source used to create global gridded population data.

Source: WorldPop - Population Counts - Unconstrained global mosaics 2000-2020 (1km)
Citation(s): WorldPop (2018)

---

Global Population Dynamics

The fraction urban population at country level has been taken from the world urbanization prospects 2018.

Source: United Nations, Department of Economic and Social Affairs, Population Division (2018). World Urbanization Prospects: The 2018 Revision.
Citation(s): United Nations, Department of Economic and Social Affairs, Population Division (2018)

---

The fraction of young children at country level has been taken from the world population prospects 2019

Source: United Nations, Department of Economic and Social Affairs, Population Division (2019). World Population Prospects 2019, Online Edition. Rev. 1
Citation(s): United Nations, Department of Economic and Social Affairs, Population Division (2019)

Human Development Index (HDI)

Source: United Nations Development Programme - Human Development Index
Citation(s): Programme United Nations Development (2024)

Pathogen Properties

Incidence, shedding rate and shedding duration are based on literature and explained in Hofstra et al. (2013) for cryptosporidium and Kiulia et al. (2015) for rotavirus.

The data used to estimate the decay of cryptosporiudium in livestock manure storage can be found in Vermeulen et al. (2017). Properties used to calculate the decay during transport from land to water and inside rivers are described by Vermeulen et al. (2019).

Sanitation

The fraction of population with access to various levels of sanitation at country level are taken from the WHO/UNICEF JMP global database. The JPM sanitation classification has been re-classified to flushSewer(1), flushSeptic(2), flushPit(3), flushUnknown(4), flushOpen(5), pitSlab(6), pitNoSlab(7), hangingToilet(8), bucketLatrine(9), compostingToilet(10), openDefecation(11) and other(12).

Source: https://washdata.org/data/downloads
citation(s): World Health Organization and UNICEF (2023)

Waste Water Treatment

Based on the model configuration either grid or point level treatment is applied.

grid level treatment
The treatment data has been taken from the work of Puijenbroek et al. (2019) at country level. The values can be found in the supplementary data of the paper.

The removal and liquid fractions are taken from the sketcher tool of Matt Verbyla. Ultimately, fEmitted_inEffluent_after_treatment is used in the GloWPa model, not any of the other variables from this part.

---

point level treatment
The HydroWASTE v1.0 dataset has been used to select the location of waste water treatment plants. The WWTP’s are only considered when the status is either ‘not reported’ (assumed operational) or operational. The emitted fraction is estimated based on the treatment level and pathogen type.
Source: HydroWASTE v1.0
Citation: Ehalt Macedo et al. (2022)

---

Hydrology

surface runoff and river discharge
The VIC model is used to produce daily surface runoff and river discharge based on WATCH forcing data. The model output is averaged over the period 1970-2000 to produce 30-year monthly climatology (Vermeulen et al., 2019).

---

flow direction
The 0.5 degrees flow direction is based in the global flow direction map DDM30 (Döll & Lehner, 2002) which is also used to produce the river discharge using the VIC model.

---

river geometry and residence time
The river geometry equations are taken from Leopold & Maddock (1953) to calculate river width, depth and flow velocity from river discharge. More details can be found in Vermeulen et al. (2019).

---

water temperature
The monthly mean river water temperature are taken from estimates by the VIC-RBM model framework (Vliet et al., 2012).

---

DOC
The Global Nutrient Export from Watersheds (Global NEWS) model provides estimates of river export of DOC for the world (Harrison et al., 2005; Mayorga et al., 2010).

Meteorology

solar radiation and air temperature
Monthly climatology is created from the WATCH forcing data over the period 1970-2000 (Weedon et al., 2011).

Livestock

animal heads
*Species: cattle, sheep, goats, pigs, chickens, and ducks * Source: GLW - Gridded Livestock of the World (~1km)
Citation: Robinson et al. (2014)

Species: buffaloes, horses, camels, mules, and donkeys
Source: FAOSTAT (heads) and GLW (spatial distribution)
Citation: Food and Agriculture Organization of the United Nations (FAO) (2024) and Robinson et al. (2014)

---

body mass
Source: IPCC guidelines for National Greenhouse Gas inventories
Citation: IPCC (2006)

---

excretion rates and prevalence
Literature Review

---

manure production Source: IPCC guidelines for National Greenhouse Gas inventories
Level: continent level Citation(s): IPCC (2006)

---

intensive and extensive farming systems
Source: IMAGE model based on FAO report
Citation(s): Bouwman et al. (2013)

---

manure storage systems
cattle, buffaloes, pigs
Source: IPCC Guidelines for National Greenhouse Gas Inventories (2006)
level: continent level
Citation: IPCC (2006)

chickens, ducks, sheep, goats, buffaloes, horses, asses, camels
Source: USEPA report on Global methane emissions from livestock and poultry manure
level: country level
Citation: Safley et al. (1992)

References