Help for package tikatuwq

Type:

Package

Title:

Water Quality Analysis Tools for the Brazilian Context

Version:

0.4.6

Maintainer:

Vinicius Saraiva Santos <vinisaraiva@gmail.com>

Description:

Tools to import, clean, validate, and analyze freshwater quality data in Brazil. Implements water quality indices including the Water Quality Index (WQI/IQA), the Trophic State Index (TSI/IET) after Carlson (1977) <doi:10.4319/lo.1977.22.2.0361> and Lamparelli (2004) https://www.teses.usp.br/teses/disponiveis/41/41134/tde-20032006-075813/publico/TeseLamparelli2004.pdf, and the National Sanitation Foundation Water Quality Index (NSF WQI) https://www.nsf.org/education/nsf-water-quality-index. The package also checks compliance with Brazilian standard CONAMA Resolution 357/2005 https://conama.mma.gov.br/?id=450&option=com_sisconama&task=arquivo.download and generates reproducible reports for routine monitoring workflows.

License:

MIT + file LICENSE

Encoding:

UTF-8

Language:

en-US

LazyData:

true

LazyDataCompression:

Depends:

R (≥ 4.1)

Imports:

dplyr, readr, tibble, rlang, stats, utils, ggplot2, tidyr, lubridate, stringr, glue, scales, broom, purrr

Suggests:

testthat (≥ 3.0.0), spelling, rmarkdown, knitr, pkgdown

VignetteBuilder:

knitr

URL:

https://github.com/tikatuwq/tikatuwq, https://tikatuwq.github.io/tikatuwq/

BugReports:

https://github.com/tikatuwq/tikatuwq/issues

Config/testthat/edition:

RoxygenNote:

7.3.3

NeedsCompilation:

Packaged:

2025-09-17 18:21:17 UTC; Vini

Author:

Vinicius Saraiva Santos

[aut, cre]

Repository:

CRAN

Date/Publication:

2025-09-22 12:00:02 UTC

tikatuwq: Ferramentas para analise de qualidade da agua (Brasil)

Description

Indices (IQA CETESB/NSF, IET Carlson/Lamparelli), checagem CONAMA 357/2005, visualizacoes e texto analitico automatico (rule-based).

Author(s)

Maintainer: Vinicius Saraiva Santos vinisaraiva@gmail.com (ORCID)

Padroniza/unifica unidades (esqueleto)

Description

Ponto de extensao para normalizar unidades (mg/L, uS/cm, etc.). Por ora retorna o data.frame sem alteracoes.

Usage

clean_units(df, units_map = NULL)

Arguments

df

data.frame/tibble de entrada.

units_map

opcional; mapa de unidades.

Value

O mesmo df (placeholder).

Conformity check (default Class = "2") - detailed

Description

For each parameter present in df, adds columns:

⁠*_ok⁠ (TRUE/FALSE),
⁠*_status⁠ ("ok", "acima_do_maximo", "abaixo_do_minimo"),
⁠*__lim_min⁠ and ⁠*__lim_max⁠ (limits used),
⁠*__delta⁠ (difference to the relevant limit; >0 if above max, <0 if below min, 0 if ok).

Usage

conama_check(df, classe = "2")

Arguments

df

tibble/data.frame com colunas de parametros (ph, turbidez, od, dbo, etc.).

classe

string da classe ("especial", "1", "2", "3", "4" ou conforme tabela).

Details

Se existirem multiplas linhas de limite para o mesmo parametro, a funcao:

considera ⁠*_ok⁠ como TRUE se QUALQUER linha for atendida; e
escolhe, para status/lim_min/lim_max/delta, a primeira linha que atende; se nenhuma atende, escolhe a que produz a menor violacao (menor |delta|).

Value

df com colunas adicionais por parametro.

Limits for Brazilian CONAMA 357/2005

Description

Returns the parameter limits defined by CONAMA Resolution 357/2005 for a given water-use class.

Usage

conama_limits(class)

Arguments

class

Integer or character. Target class (e.g., 1, 2, 3, 4 or "special"), according to CONAMA 357/2005.

Value

A tibble/data frame with one row per parameter and the regulatory thresholds. Typical columns:

parameter: parameter name (character)
class: CONAMA class label (character/integer)
limit_min: minimum allowed value (numeric, may be NA)
limit_max: maximum allowed value (numeric, may be NA)
unit: measurement unit (character)
criterion: textual rule if applicable (character)

Examples

# class 2 thresholds
head(conama_limits(2))

Conformity report (table)

Description

Conformity report (table)

Relatorio de conformidade (tabela), com formato opcional

Usage

conama_report(
  df,
  classe = "2",
  only_violations = TRUE,
  pretty = FALSE,
  decimal_mark = ",",
  big_mark = "."
)

conama_report(
  df,
  classe = "2",
  only_violations = TRUE,
  pretty = FALSE,
  decimal_mark = ",",
  big_mark = "."
)

Arguments

df

dados de entrada

classe

classe CONAMA

only_violations

se TRUE, retorna apenas linhas com status != "ok"

pretty

se TRUE, devolve colunas formatadas para exibicao

decimal_mark

separador decimal (default ",")

big_mark

separador de milhar (default ".")

Value

tibble com: parametro, valor, lim_min, lim_max, status, delta

tibble

Conformity summary (long format)

Description

Conformity summary (long format)

Usage

conama_summary(df, classe = "2")

Arguments

df

dados de entrada

classe

classe CONAMA

Value

tibble com: parametro, valor, lim_min, lim_max, status, ok, delta

Text summary of conformity (bulleted, formatted)

Description

Text summary of conformity (bulleted, formatted)

Usage

conama_text(
  df,
  classe = "2",
  only_violations = FALSE,
  decimal_mark = ",",
  big_mark = "."
)

Arguments

df

dados de entrada

classe

classe CONAMA

only_violations

se TRUE, lista apenas parametros com violacao

decimal_mark

separador decimal (default ",")

big_mark

separador de milhar (default ".")

Value

character vector (linhas)

Analytical paragraphs generation (rule-based, no AI)

Description

Analytical paragraphs generation (rule-based, no AI)

Usage

generate_analysis(
  df,
  classe_conama = "2",
  incluir_tendencia = TRUE,
  parametros_tendencia = c("turbidez", "od", "pH"),
  contexto = list(rio = NA, periodo = NA, cidade = NA)
)

Arguments

df

Data frame with columns including at least ponto, and preferably parameters used by CONAMA checks and IQA computation

classe_conama

Character scalar with CONAMA class (e.g. "2")

incluir_tendencia

Logical; whether to compute simple time trends

parametros_tendencia

Character vector of parameter names to test trends

contexto

List with optional metadata, accepting PT or EN keys: rio/river, periodo/period, cidade

Value

Character vector of 3-5 analytical paragraphs

Trophic State Index (Carlson) - basic

Description

Trophic State Index (Carlson) - basic

Usage

iet_carlson(secchi = NULL, clorofila = NULL, tp = NULL)

Arguments

secchi

Numeric vector with Secchi depth (m)

clorofila

Numeric vector with chlorophyll-a (µg/L)

tp

Numeric vector with total phosphorus (µg/L)

Value

Data frame with TSI components and overall IET

Trophic State Index - Lamparelli (skeleton v0.2.1)

Description

Trophic State Index - Lamparelli (skeleton v0.2.1)

Usage

iet_lamparelli(
  tp = NULL,
  chla = NULL,
  sd = NULL,
  ambiente = c("rio", "reservatorio")
)

Arguments

tp

Numeric total phosphorus (mg/L)

chla

Numeric chlorophyll-a (µg/L)

sd

Numeric Secchi disk depth (m)

ambiente

Environment type: 'rio' or 'reservatorio'

Value

Data frame with IET components and overall Lamparelli index

Water Quality Index (WQI / IQA)

Description

Computes IQA/WQI for each site/date (or grouping).

Usage

iqa(
  df,
  pesos = c(od = 0.17, coliformes = 0.15, pH = 0.12, dbo = 0.1, nt_total = 0.1, p_total =
    0.1, turbidez = 0.08, tds = 0.08, temperatura = 0.1),
  altitude_m = 0,
  na_rm = FALSE
)

iqa(
  df,
  pesos = c(od = 0.17, coliformes = 0.15, pH = 0.12, dbo = 0.1, nt_total = 0.1, p_total =
    0.1, turbidez = 0.08, tds = 0.08, temperatura = 0.1),
  altitude_m = 0,
  na_rm = FALSE
)

Arguments

df

cols: pH, turbidez, od, dbo, nt_total, p_total, tds, temperatura, coliformes

pesos

pesos oficiais (ANA/CETESB)

altitude_m

altitude (m) p/ %sat de OD

na_rm

reescala pesos nos parâmetros presentes

Value

A tibble/data frame with columns such as site, date, iqa (numeric score), and class (qualitative label).

Tabela de curvas Qi (IQA) por parâmetro (estrutura CETESB/NSF)

Description

Tabela de curvas Qi (IQA) por parâmetro (estrutura CETESB/NSF)

Usage

iqa_curve_table(method = c("CETESB_approx"))

NSF Water Quality Index (prototype v0.2.1)

Description

NSF Water Quality Index (prototype v0.2.1)

Usage

nsfwqi(
  df,
  pesos = c(do = 0.17, fc = 0.16, ph = 0.11, bod = 0.11, temp_change = 0.1, po4 = 0.1,
    no3 = 0.1, turbidez = 0.08, sst = 0.07),
  na_rm = FALSE
)

Arguments

df

Data frame containing columns compatible with NSFWQI mapping

pesos

Named numeric vector with parameter weights

na_rm

Logical; allow NA and rescale weights

Value

Data frame with an added 'NSFWQI' column

Boxplots by site/parameter

Description

Boxplots by site/parameter

Usage

plot_box(df, parametro, by = "ponto")

Arguments

df

Data frame with water quality data.

parametro

Character; parameter column name.

by

Character; grouping column (e.g., "site").

Value

A ggplot object (class ggplot) representing the boxplot.

Heatmap of parameters vs. sites

Description

Heatmap of parameters vs. sites

Usage

plot_heatmap(df_long)

Arguments

df_long

Long-format data frame (site/parameter/value).

Value

A ggplot object (class ggplot) representing the heatmap.

Plot IQA by site/date

Description

Plot IQA by site/date

Usage

plot_iqa(df)

Arguments

df

Data frame returned by iqa() (or with equivalent columns).

Value

A ggplot object (class ggplot) representing IQA across sites/dates.

Time series by parameter

Description

Time series by parameter

Usage

plot_series(df, parametro, facet = NULL)

Arguments

df

Data frame with a data column (Date/POSIXct) and the chosen parameter column.

parametro

Character; parameter to plot (name of the numeric column).

facet

Character or NULL; optional grouping column name to facet/color.

Value

A ggplot object (class ggplot) showing the time series.

Interpola Qi a partir de uma curva definida por pontos (x, qi)

Description

Interpola Qi a partir de uma curva definida por pontos (x, qi)

Usage

qi_interp(x, tbl)

Leitura padrao de dados de qualidade da agua

Description

Aceita CSV com virgula ou ponto como separador decimal e ignora texto de unidades (ex.: "0,04 mg/L"). Lê tudo como texto, normaliza nomes e converte colunas numericas de forma robusta. Aplica um ajuste de seguranca em pH evidentemente fora da faixa (ex.: 72 -> 7.2).

Usage

read_wq(path, tz = "America/Bahia")

Arguments

path

Caminho do arquivo CSV.

tz

Fuso para datas (mantido por compatibilidade; datas sao Date).

Value

Um tibble com colunas normalizadas.

Render a report (R Markdown / Quarto) from the internal template

Description

By default, writes to a temporary directory to comply with CRAN policies. The function returns the full path to the generated file.

Usage

render_report(
  df,
  meta = list(river = NA, period = NA),
  output_file = "wq_report.html",
  output_dir = tempdir(),
  template = system.file("templates", "report_rmd.Rmd", package = "tikatuwq")
)

Arguments

df

Data frame with input data used by the template

meta

Named list with contextual metadata (e.g., river, period)

output_file

Output file name (default 'wq_report.html')

output_dir

Directory where the file will be written (default tempdir())

template

Path to the internal template file

Value

Invisible character path to the generated report

Descriptive summaries by group

Description

Descriptive summaries by group

Usage

resume_wq(df, by = c("ponto", "mes"), funs = c("mean", "median", "sd"))

Arguments

df

Data frame

by

Character vector of grouping columns

funs

Character vector of summary functions (kept for compatibility)

Value

Grouped summary data frame

Valida presenca de colunas minimas

Description

Garante que o conjunto minimo de colunas exista no dataset.

Usage

validate_wq(
  df,
  required = c("ph", "turbidez", "od", "dbo", "nt_total", "p_total", "tds",
    "temperatura", "coliformes")
)

Arguments

df

data.frame/tibble de entrada.

required

vetor de nomes de colunas obrigatorias.

Value

O df de entrada se estiver valido; caso contrario, erro.

Demo water quality dataset

Description

A tiny example dataset used in examples and the vignette. Columns are aligned with the package functions (Portuguese variable names).

Usage

data(wq_demo)

Format

A data frame with 20 rows and 11 variables:

ponto: chr, monitoring point id
data: Date, sampling date
ph: numeric
od: numeric, dissolved oxygen (mg/L)
turbidez: numeric, NTU
dbo: numeric, mg/L
coliformes: integer, MPN/100 mL
p_total: numeric, mg/L
nt_total: numeric, mg/L
temperatura: numeric, Celsius
tds: numeric, total dissolved solids (mg/L)

Source

Simulated for package examples.

tikatuwq: Ferramentas para analise de qualidade da agua (Brasil)

Description

Author(s)

See Also

Padroniza/unifica unidades (esqueleto)

Description

Usage

Arguments

Value

Conformity check (default Class = "2") - detailed

Description

Usage

Arguments

Details

Value

Limits for Brazilian CONAMA 357/2005

Description

Usage

Arguments

Value

Examples

Conformity report (table)

Description

Usage

Arguments

Value

Conformity summary (long format)

Description

Usage

Arguments

Value

Text summary of conformity (bulleted, formatted)

Description

Usage

Arguments

Value

Analytical paragraphs generation (rule-based, no AI)

Description

Usage

Arguments

Value

Trophic State Index (Carlson) - basic

Description

Usage

Arguments

Value

Trophic State Index - Lamparelli (skeleton v0.2.1)

Description

Usage

Arguments

Value

Water Quality Index (WQI / IQA)

Description

Usage

Arguments

Value

Tabela de curvas Qi (IQA) por parâmetro (estrutura CETESB/NSF)

Description

Usage

NSF Water Quality Index (prototype v0.2.1)

Description

Usage

Arguments

Value

Boxplots by site/parameter

Description

Usage

Arguments

Value

Heatmap of parameters vs. sites

Description

Usage

Arguments

Value

Plot IQA by site/date

Description

Usage

Arguments

Value

Time series by parameter