Getting started with tidywater

library(tidywater)

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
)
#> Warning in define_water(ph = 7, temp = 15, alk = 100, tot_hard = 100, na = 100,
#> : Missing values for calcium and magnesium but total hardness supplied. Default
#> ratio of 65% Ca2+ and 35% Mg2+ will be used.
#> Warning in define_water(ph = 7, temp = 15, alk = 100, tot_hard = 100, na = 100,
#> : Missing value for DOC. Default value of 95% of TOC will be used.

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.

dosed_water <- chemdose_ph(mywater, hcl = 5, alum = 20)
mywater@ph
#> [1] 7
dosed_water@ph
#> [1] 6.67

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 moodel, you could also select your own coefficients.

coag_water <- chemdose_toc(dosed_water, alum = 20)

dosed_water@doc
#> [1] 2.85
coag_water@doc
#> [1] 2.424969

We can also solve for chemical doses to change the 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)

We can apply similar principals for disinfection. Note that we have to specify the chlorine dose 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")
#> Warning in chemdose_dbp(., cl2 = 4, time = 24, treatment = "coag"): UV254 is
#> outside the model bounds of 0.016 <= UV254 <= 0.215 cm-1 for coagulated water.
#> Warning in chemdose_dbp(., cl2 = 4, time = 24, treatment = "coag"): Temperature
#> is outside the model bounds of temp=20 Celsius for coagulated water.
#> Warning in chemdose_dbp(., cl2 = 4, time = 24, treatment = "coag"): pH is
#> outside the model bounds of pH = 7.5 for coagulated water

summarize_wq(dist_water, "dbps")

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.