Reproducible freshwater monitoring workflows for Brazil, including water quality indices, regulatory compliance checks, and automated reporting.
TikatuWQ is an open-source R package designed to
analyze, visualize, and report water quality data according to Brazilian
environmental standards.
It implements the main indices used in the country
IQA/NSFWQI and IET (Carlson and
Lamparelli) and provides automated checks for CONAMA
Resolution 357/2005 compliance — including the legal frequency
rule (Art. 15).
The package also includes seasonal analysis, pollutant load computation,
exceedance probability, multivariate PCA, trend analysis, data
validation, and automatic report generation.
**Author:** Vinícius Saraiva Santos
**Institution:** Federal University of Southern Bahia (UFSB) – Graduate Program in Biosystems
**Research Group:** Tropical Ecosystems Research Center (NuPEcoTropic)
**Project:** Tikatu – Ecosystem of tools for water quality monitoring and interpretation
**License:** MIT
**Software DOI:** https://doi.org/10.5281/zenodo.17407297
**Manuscript status:** scientific article currently under review in an international journal
The tikatuwq package was designed to support reproducible scientific workflows in freshwater monitoring and environmental assessment. Environmental monitoring datasets often present challenges such as heterogeneous formats, inconsistent parameter names, and the need to interpret regulatory thresholds.
By integrating data validation, environmental indices, regulatory compliance checks, visualization, and automated reporting in a single analytical framework, tikatuwq enables researchers to move efficiently from raw monitoring data to interpretable environmental assessments.
The package is particularly suited for:
This package includes a real water quality dataset extracted from
INEMA (the Bahia State Environmental Agency) monitoring campaigns
conducted in the Rio Buranhem watershed (Porto Seguro, Bahia, Brazil)
between 2021 and 2024. The included data provide site IDs, sampling
dates, and diverse physicochemical variables measured during field
campaigns. See documentation for wq_demo for details on
columns and usage in analyses.
All main documentation and vignettes use this realistic sample for demonstration and reproducible workflows.
A typical analysis workflow using tikatuwq follows a reproducible pipeline:
read_wq → validate_wq → index calculation → regulatory check → visualization → reporting
library(tikatuwq)
data(wq_demo)
head(wq_demo)
# IQA calculation with validated analytical CETESB equations
wq_demo |> validate_wq() |> iqa(allow_partial = TRUE) |> plot_iqa()
# Detailed component-level audit of the 9 CETESB sub-indices
iqa_components(wq_demo)
# Trophic state visualization
wq_demo |> iet_carlson(.keep_ids = TRUE) |> plot_iet(method = "carlson")
# Seasonal analysis
wq_demo |>
assign_season(region = "bahia") |>
compare_seasons(param = "turbidez", by = "ponto")The TikatuWQ package was developed by
Vinícius Saraiva Santos (author and maintainer)
as part of the Tikatu Research Project, conducted
within the Nucleus for Research in Tropical Ecosystems –
NuPEcoTropic, a research group linked to the Federal
University of Southern Bahia (UFSB) and coordinated by
Prof. Dr. Fabrício Berton Zanchi.
This work was carried out as part of the activities of the Postgraduate Program in Biosystems (PPG Biossistemas) at UFSB, under the supervision of Prof. Dr. Fabrício Berton Zanchi.
The Tikatu Project, developed and coordinated by Vinícius Saraiva Santos, integrates research focused on environmental monitoring and modeling.
🔬 Scientific & Metrological Audit of the Brazilian IQA (CETESB/INEMA)
iqa()
now implements validated piecewise analytical equations for all 9 CETESB
sub-indices (\(Q_1\) to \(Q_9\)), including altitude- and
temperature-corrected DO saturation (\(C_s\)), exact exponential-base curves
(\(\text{DBO}_5\), \(\text{NT}\), \(\text{Turb}\), \(\text{PT}\)), and strict piecewise
polynomials.phosphorus_basis = "P".microbial_type = "e_coli", applying the official CETESB
conversion factor.tds) is no longer accepted as an
interchangeable alias for Total Solids
(solidos_totais/residuo_total) in strict
CETESB mode, preventing systematic overestimation of water quality.iqa_components() and iqa(..., details = TRUE)
returning raw values, analytical sub-indices (\(Q_i\)), official weights (\(W_i\)), and weighted factors (\(Q_i^{W_i}\)) for full scientific
reproducibility.classify_iqa() updated to official CETESB rating
thresholds: Péssima (\(\le
19\)), Ruim (\(19\text{--}36\)), Regular (\(36\text{--}51\)), Boa (\(51\text{--}79\)), Ótima (\(> 79\)).conama_check() now accepts
environment = c("all", "lotic", "lentic", "intermediate")
for automatic selection of regulatory phosphorus thresholds and
pH-conditioned ammonia limits.✔️ R CMD check --as-cran: 0 errors | 0 warnings
| 0 notes
✔️ 299 automated unit tests passing
✔️ Compatible with CRAN, Windows, Linux, and macOS
⚠️ Breaking change — IQA now uses the correct weighted geometric mean
iqa() now defaults to method = "CETESB",
which computes the weighted geometric mean ∏(Qi^Wi) as
specified by CETESB and the original NSF WQI formulation (Brown et al.,
1970). The previous (incorrect) arithmetic mean behavior is preserved
via method = "NSF_approx". Users relying on the default
will see more accurate — and generally lower — IQA values.
New functions in v0.9.0:
conama_freq_check() — implements the legal frequency
rule of CONAMA 357/2005 Art. 15: a parameter is considered in conformity
only when ≥ 80% of at least 6 samples per year are within limits.assign_season() — classifies each sample as
"chuvoso" (wet) or "seco" (dry) based on
regional Brazilian hydrological calendars.compare_seasons() — compares water quality parameters
between wet and dry seasons.plot_iet() — bar chart for the Trophic State Index with
color-coded trophic classes.compute_load() — computes pollutant load (kg/day,
t/day, kg/year, g/s).exceedance_prob() — empirical exceedance probability
with Wilson confidence intervals.wq_pca() — PCA wrapper with biplot, screeplot, and
loadings plots.nsfwqi() — updated with geometric mean aggregation and
multilingual status labels.## Install the released version from CRAN:
install.packages("tikatuwq")
## Installation via GitHub
install.packages("remotes")
# development version
remotes::install_github("tikatuwq/tikatuwq", dependencies = TRUE)
# stable version (by tag)
remotes::install_github("tikatuwq/tikatuwq@v0.10.0", build_vignettes = TRUE)df <- read_wq(system.file("extdata","exemplo_chamagunga.csv", package="tikatuwq"))
# Table with only violations, ready for report
conama_report(df, "2", only_violations = TRUE, pretty = TRUE)
# Short textual summary
cat(paste(conama_text(df, "2", only_violations = TRUE), collapse = "\n"))
# Legal frequency rule (CONAMA 357/2005 Art. 15)
conama_freq_check(df, classe = "2", by = "ponto")Water quality indices -
iqa(df, method = "CETESB", na_rm = TRUE, ...) — Water
Quality Index; weighted geometric mean (CETESB/NSF default). -
iet_carlson(df) / iet_lamparelli(df) — Trophic
State Index. - nsfwqi(df, na_rm = TRUE, add_status = TRUE)
— NSF WQI with geometric mean aggregation.
CONAMA compliance and balneability -
conama_limits(class) — limits from CONAMA 357/2005. -
conama_check(df, class) — compliance by parameter
(*_ok columns). -
conama_freq_check(df, classe, by) — Art. 15 frequency rule
(≥ 80% conformity in ≥ 6 samples/year). -
balnear_check(df, by) — balneability classification under
CONAMA 274/2000 (Excelente → Imprópria).
Seasonal analysis and trend -
assign_season(df, region) — classifies samples by
hydrological season using regional calendars. -
compare_seasons(df, param, test) — statistical comparison
between wet and dry seasons. -
mk_seasonal(df, param, period) — seasonal Mann-Kendall
trend test (Hirsch et al., 1982); returns Z, p-value, tau, and Sen’s
slope.
Load and risk -
compute_load(df, param, flow_col, unit_out) — pollutant
load (kg/day, t/day, etc.). -
exceedance_prob(df, param, threshold, direction, by) —
empirical exceedance probability with Wilson CI.
Multivariate -
wq_pca(df, params, color_by) — PCA with biplot, screeplot,
and loadings plot.
Visualization - plot_iqa(),
plot_iet(), plot_series(),
plot_box(), plot_heatmap(),
plot_trend() — return ggplot objects. -
plot_map(), plot_map_quality() — interactive
Leaflet maps; plot_map_quality() colors sites by
IQA/IET/NSF WQI class.
Data and reports - read_wq(path) —
reads water quality datasets (CSV). - validate_wq(df) —
validates/normalizes columns and units. -
generate_analysis(), render_report() —
automated textual and document reporting.
If you use tikatuwq in your research, please cite it as follows:
Santos, V. S. (2025). tikatuwq: Water Quality Assessment and Environmental Compliance in Brazil (v0.10.0). Zenodo. https://doi.org/10.5281/zenodo.17407297
BibTeX entry:
@Manual{Santos2025tikatuwq,
title = {tikatuwq: Water Quality Assessment and Environmental Compliance in Brazil},
author = {Vinicius Saraiva Santos},
year = {2025},
note = {R package version 0.10.0},
doi = {10.5281/zenodo.17407297},
url = {https://github.com/tikatuwq/tikatuwq},
}