Getting started with tidywater"
In tidywater: Water Quality Models for Drinking Water Treatment Processes

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(tidywater)

Defining an example water

Most tidywater functions required a water object. Start by creating a water with define_water. There are a lot of optional arguments that correspond to different water quality parameters. Start by specifying everything you know, or at least all the parameters relevant to the modeling you want to do. Parameters are all lowercase and use common abbreviations or chemical formulas. If you aren't sure what the correct argument name is, check the define_water documentation. Concentrations are specified in the most common units - usually mg/L or ug/L depending on the parameter. Units are also in the documentation, so make sure to check carefully until you are familiar with the system.

mywater <- define_water(
  ph = 7, temp = 15, alk = 100, tot_hard = 100, na = 100, cl = 80,
  cond = 100,
  toc = 3, uv254 = .02, br = 50
)

Now that we have a water, we can apply treatment models to it. The main models require a water input and will usually output another water or a number. Functions in tidywater follow the naming convention treatmentapplied_parametersmodeled. For example, when we want to dose chemical and see the impact on pH/alkalinity, we use chemdose_ph. There are a lot of available chemicals, which you can view with the documentation. Most chemicals are specified using the chemical formula in all lowercase, except hydrated coagulants, which are named. Units for the chemical are also specified, and are usually mg/L as chemical.

Coagulation model

First, let's apply a model that will predict the effect of coagulation on the given mywater conditions we set up earlier. Start by determining the impact of adding 5 mg/L HCl and 20 mg/L alum as the coagulant.

dosed_water <- chemdose_ph(mywater, hcl = 5, alum = 20)
mywater@ph
dosed_water@ph

Now dosed_water has updated pH chemistry based on the hydrochloric acid and alum doses. However, other slots in the water, such as TOC, have not been updated. If we also want to know how the coagulant impacts TOC, we need to apply chemdose_toc as well. This function defaults to published model coefficients, but because it's an empirical model, you could also select your own coefficients.

coag_water <- chemdose_toc(dosed_water, alum = 20)

dosed_water@doc
coag_water@doc

The two functions chemdose_ph and chemdose_toc can also be chained together using the pipe operator %>% to calculate the changes to pH and TOC more compactly. Notice that the pH and DOC values returned from piped_coag_water are the same as those calculated above in coag_water.

piped_coag_water <- mywater %>%
  chemdose_ph(hcl = 5, alum = 20) %>%
  chemdose_toc(alum = 20)

piped_coag_water@ph
piped_coag_water@doc

We can also solve for chemical doses to achieve a target pH with solvedose_ph. This function outputs a number instead of a water.

caustic_req <- solvedose_ph(coag_water, target_ph = 8.6, chemical = "naoh")

fin_water <- chemdose_ph(coag_water, naoh = caustic_req)

Disinfection model

We can apply similar principals for disinfection. Note that we have to specify the chlorine dose in mg/L Cl2 in both chemdose_ph and chemdose_dbp because they are calculating two different things. In this example, the DBP function displays some warnings because the water we are modeling is outside the bounds of the original model fitting. This is common, and something you should always be aware of (even if tidywater doesn't warn you). We can use summarize_wq to view different groups of parameters in the water.

dist_water <- chemdose_ph(fin_water, naocl = 4) %>%
  chemdose_dbp(cl2 = 4, time = 24, treatment = "coag")

summarize_wq(dist_water, "dbps")

Summary and Recommended Resources

In this tutorial, we walked through how to set up influent water conditions by specifying water quality parameters using the define_water function. Then, we applied two common treatment models, coagulation and disinfection, and predicted the effect of the chemical addition on pH and TOC and/or DBPs. These functions return a water object with new water quality parameters, which represent effluent water conditions. It is important to note that there are individual functions that update each water quality parameter. Changes to pH and TOC, for example, require separate functions to calculate, which can be chained together using the pipe operator %>%. There are also functions that can solve for the required chemical dose, such as solvedose_ph which solves for the chemical dose needed to achieve a target pH value.

Tidywater functions can also be applied to data frames using the _chain (output a water column) or _once (output numeric columns) suffixes. To learn more about those functions, look at the documentation or read the helper function vignette.

If you want a more detailed introduction to tidywater, check out the intro vignette.