chemdose_chlordecay: Calculate chlorine decay

In tidywater: Water Quality Models for Drinking Water Treatment Processes

Calculate chlorine decay

Description

calculates the decay of chlorine or chloramine based on the U.S. EPA's Water Treatment Plant Model (U.S. EPA, 2001). For a single water use chemdose_chlordecay; for a dataframe use chemdose_chlordecay_chain. For most arguments in the ⁠_chain⁠ helper "use_col" default looks for a column of the same name in the dataframe. The argument can be specified directly in the function instead or an unquoted column name can be provided.

Usage

chemdose_chlordecay(
  water,
  cl2_dose,
  time,
  treatment = "raw",
  cl_type = "chlorine",
  use_chlorine_slot = FALSE
)

chemdose_chlordecay_chain(
  df,
  input_water = "defined_water",
  output_water = "disinfected_water",
  cl2_dose = "use_col",
  time = "use_col",
  treatment = "use_col",
  cl_type = "use_col",
  use_chlorine_slot = "use_col"
)

Arguments

water	Source water object of class "water" created by define_water
cl2_dose	Applied chlorine or chloramine dose (mg/L as cl2). Model results are valid for doses between 0.995 and 41.7 mg/L for raw water, and for doses between 1.11 and 24.7 mg/L for coagulated water.
time	Reaction time (hours). Chlorine decay model results are valid for reaction times between 0.25 and 120 hours.Chloramine decay model does not have specified boundary conditions.
treatment	Type of treatment applied to the water. Options include "raw" for no treatment (default), "coag" for water that has been coagulated or softened.
cl_type	Type of chlorination applied, either "chlorine" (default) or "chloramine".
use_chlorine_slot	Defaults to FALSE. When TRUE, uses either free_chlorine or combined_chlorine slot in water (depending on cl_type). If 'cl2_dose' argument, not specified, chlorine slot will be used. If 'cl2_dose' specified and use_chlorine_slot is TRUE, all chlorine will be summed.
df	a data frame containing a water class column, which has already been computed using define_water_once. The df may include a column named for the applied chlorine dose (cl2), and a column for time in hours.
input_water	name of the column of water class data to be used as the input for this function. Default is "defined_water".
output_water	name of the output column storing updated parameters with the class, water. Default is "disinfected_water".

Details

Required arguments include an object of class "water" created by define_water, applied chlorine/chloramine dose, type, reaction time, and treatment applied (options include "raw" for no treatment, or "coag" for coagulated water). The function also requires additional water quality parameters defined in define_water including TOC and UV254. The output is a new "water" class with the calculated total chlorine value stored in the 'free_chlorine' or 'combined_chlorine' slot, depending on what type of chlorine is dosed. When modeling residual concentrations through a unit process, the U.S. EPA Water Treatment Plant Model applies a correction factor based on the influent and effluent residual concentrations (see U.S. EPA (2001) equation 5-118) that may need to be applied manually by the user based on the output.

For large datasets, using fn_once or fn_chain may take many minutes to run. These types of functions use the furrr package for the option to use parallel processing and speed things up. To initialize parallel processing, use plan(multisession) or plan(multicore) (depending on your operating system) prior to your piped code with the fn_once or fn_chain functions. Note, parallel processing is best used when your code block takes more than a minute to run, shorter run times will not benefit from parallel processing.#'

Value

chemdose_chlordecay returns an updated disinfectant residual in the free_chlorine or combined_chlorine water slot in units of M. Use convert_units to convert to mg/L.

chemdose_chlordecay_chain returns a data frame containing a water class column with updated chlorine residuals.

Source

U.S. EPA (2001)

See references list at: https://github.com/BrownandCaldwell-Public/tidywater/wiki/References

Examples

example_cl2 <- define_water(8, 20, 66, toc = 4, uv254 = 0.2) %>%
  chemdose_chlordecay(cl2_dose = 2, time = 8)

example_cl2 <- define_water(8, 20, 66, toc = 4, uv254 = 0.2, free_chlorine = 3) %>%
  chemdose_chlordecay(cl2_dose = 2, time = 8, use_chlorine_slot = TRUE)


library(dplyr)

example_df <- water_df %>%
  mutate(br = 50) %>%
  define_water_chain() %>%
  chemdose_chlordecay_chain(input_water = "defined_water", cl2_dose = 4, time = 8)

example_df <- water_df %>%
  mutate(
    br = 50,
    free_chlorine = 2
  ) %>%
  define_water_chain() %>%
  mutate(
    cl2_dose = seq(2, 24, 2),
    ClTime = 30
  ) %>%
  chemdose_chlordecay_chain(
    time = ClTime,
    use_chlorine_slot = TRUE,
    treatment = "coag",
    cl_type = "chloramine"
  )

# Initialize parallel processing
library(furrr)
# plan(multisession)
example_df <- water_df %>%
  mutate(br = 50) %>%
  define_water_chain() %>%
  chemdose_chlordecay_chain(cl2_dose = 4, time = 8)

# Optional: explicitly close multisession processing
# plan(sequential)

tidywater documentation built on Aug. 8, 2025, 7:15 p.m.