Calcula o IQA segundo a metodologia CETESB (Apendice D, 2023): subindices \(q_i\) agregados por media geometrica ponderada, \(IQA = \prod_{i=1}^{9} q_i^{w_i}\).
A CETESB publica os \(q_i\) apenas como curvas graficas (Figura 1 do
Apendice D). O pacote usa equacoes analiticas por partes que aproximam essas
curvas; os pesos, os valores fixos fora do dominio (ex.: DBO > 30 -> 2,
OD > 140\
os trechos de DBO (5-15 mg/L), nitrogenio total (10-60 mg/L) e pH (8,5-10)
foram corrigidos apos comparacao com as curvas. A curva de variacao de
temperatura (usada so com temperature_method diferente do padrao) nao
acompanha a curva oficial. Veja
system.file("audit", "IQA_AUDITORIA.md", package = "tikatuwq").
Usage
iqa(
df,
method = c("CETESB", "CETESB_equations", "IGAM", "CETESB_legacy_approx", "NSF_approx"),
altitude_m = 0,
phosphorus_basis = c("P", "PO4"),
microbial_type = c("thermotolerant_coliforms", "e_coli"),
temperature_method = c("cetesb_default", "delta", "reference"),
temperature_reference = NULL,
delta_temperature = NULL,
censor_policy = c("limit", "half_limit", "zero", "na", "preserve"),
allow_partial = FALSE,
details = FALSE,
add_status = TRUE,
locale = c("pt", "en"),
pesos = NULL,
nitrate_unit = NULL,
...
)Arguments
- df
Data frame ou tibble com as colunas de monitoramento. Nomes canonicos reconhecidos:
od,solidos_totais(ouresiduo_total),ph,dbo,coliformes_termotolerantes(oucoliformes),nt_total,p_total,turbidez,temperatura.- method
Metodo de calculo:
"CETESB"(padrao) - equacoes analiticas por partes com media geometrica ponderada."CETESB_equations"- alias de"CETESB"."IGAM"- reproducao computacional documentada do IQA do IGAM (Minas Gerais), motor independente do CETESB e nao homologado pelo IGAM. Ver a secao Metodo IGAM."CETESB_legacy_approx"- subindices por curvas interpoladas aproximadas (legado)."NSF_approx"- subindices por curvas aproximadas com media aritmetica (legado).
- altitude_m
Altitude em metros (escalar ou vetor com uma altitude por linha), entre -500 e 9000 m; usada na concentracao de saturacao de OD.
- phosphorus_basis
Base do fosforo informado:
"P"(default, aplica o fator 3,066 para PO4) ou"PO4". A curva CETESB e de fosfato (PO4); o fator 3,066 consta no Apendice D 2023, p. 5. Emmethod = "IGAM", deve ser informado explicitamente quando a entrada forp_total.- microbial_type
Tipo microbiologico informado:
"thermotolerant_coliforms"(default) ou"e_coli"(multiplica por 1,25 para equivaler a termotolerantes, conforme o Apendice D CETESB 2023, p. 5). Emmethod = "IGAM"nao ha fator; o argumento so escolhe a coluna quando ambas existem.- temperature_method
Componente termico:
"cetesb_default"(default, qi = 94 constante; a CETESB usa "o valor correspondente a melhor qualidade", com \(q^w = 1,58\), compativel com qi = 94),"delta"(usadelta_temperatureou a colunadelta_temperatura; erro se nenhum for informado) ou"reference"(usatemperatura - temperature_reference; erro se faltar algum). Os modos"delta"e"reference"sao experimentais e nao validados: a curva de Delta T do pacote nao tem fonte rastreavel e diverge da curva q6 da CETESB. Eles emitem aviso e marcam"experimental_temperature_curve"emattr(, "iqa_nonstandard"). Delta T < -5 C resulta emNA(qi indefinido pela fonte).- temperature_reference
Temperatura de referencia (escalar ou um valor por linha) quando
temperature_method = "reference".- delta_temperature
Variacao de temperatura (escalar ou um valor por linha) quando
temperature_method = "delta". Tem precedencia sobre a colunadelta_temperatura.- censor_policy
Politica para dados censurados:
"limit"(default: <X -> X),"half_limit"(<X -> X/2),"zero","na", ou"preserve".- allow_partial
Logico; se
FALSE(padrao), exige os 9 componentes. SeTRUE, calcula estimativa parcial (veja a secao Dados ausentes).- details
Logico; se
TRUE, anexa no atributo"components"a tabela deiqa_componentscom os pesos efetivos usados em cada linha, de modo queprod(qi^wi)reproduzIQA_unrounded.- add_status
Logico; se
TRUE(padrao), adiciona a colunaIQA_status.- locale
Idioma dos rotulos qualitativos:
"pt"(padrao) ou"en".- pesos
Vetor nomeado de pesos customizados (opcional). Nomes aceitos sao os canonicos ou aliases dos 9 parametros; componentes omitidos mantem o peso CETESB e o conjunto e renormalizado para soma 1. Pesos devem ser finitos e nao negativos. Com pesos customizados o resultado deixa de ser o IQA CETESB (registrado em
attr(, "iqa_nonstandard")).- nitrate_unit
Usado apenas por
method = "IGAM": unidade da colunanitrato,"N"(mg/L N-NO3, convertido por 62,004/14,007) ou"NO3"(mg/L NO3). Obrigatorio quando houver nitrato; nao ha unidade presumida.- ...
Apenas o argumento legado
na_rm(depreciado, useallow_partial).classificationeschemegeram erro (removidos na 0.11.0). Outros argumentos geram aviso e sao ignorados.
Value
O data frame de entrada com a coluna numerica IQA (0-100, arredondada a
2 casas) e, quando add_status = TRUE, a coluna fator IQA_status.
A classe e atribuida sobre o valor nao arredondado (IQA_unrounded nos
detalhes); o arredondamento e apenas de apresentacao.
Atributos de proveniencia: iqa_method, iqa_method_reference,
iqa_classification, iqa_weights, iqa_custom_weights,
iqa_censor_policy, iqa_phosphorus_basis, iqa_microbial_type,
iqa_temperature_method, iqa_altitude_m, iqa_allow_partial,
iqa_partial_rows, iqa_complete e iqa_nonstandard.
Metodo x classificacao
method define o motor de calculo completo (parametros, curvas, pesos,
politica de ausentes) e a escala de classificacao correspondente:
iqa(df) calcula e classifica pela CETESB. Para aplicar outra escala a
um IQA ja calculado, use classify_iqa; isso nao transforma o
numero em um IQA de outra instituicao.
Mudanca incompativel na 0.11.0: o argumento classification
de iqa(), presente na 0.10.0 ("cetesb", "legacy"), foi
removido. Passa-lo (assim como scheme) gera erro com a orientacao de
migracao: classify_iqa(iqa(df)$IQA, classification = "legacy"). A
chamada posicional da 0.10.0 (iqa(df, "CETESB", "legacy")) tambem gera
erro de migracao, pois o 3o argumento passou a ser altitude_m.
Dados ausentes
Pela CETESB, sem algum dos nove parametros "o calculo do IQA e inviabilizado"
(Apendice D 2023, p. 4). Assim, com allow_partial = FALSE (padrao),
essas linhas recebem NA. Com allow_partial = TRUE, os pesos dos parametros
disponiveis sao renormalizados proporcionalmente (\(w_i / \sum w_{disp}\)).
Esta e uma estimativa parcial do pacote, nao uma regra institucional: o IGAM,
por exemplo, nao calcula o IQA sem OD ou coliformes e reparte o peso dos
demais ausentes igualmente. Linhas parciais ficam registradas no atributo
"iqa_partial_rows" e, com details = TRUE, nas colunas
IQA_partial e missing_params.
Metodo IGAM
method = "IGAM" calcula pelas equacoes do SCQA (SEMAD/UCEMG/PNMA II,
2005) e pelas regras do Projeto Aguas de Minas: pesos 0,17 (OD), 0,15
(microbiologico), 0,12 (pH), 0,10 (DBO, nitrato, fosfato total,
temperatura), 0,08 (turbidez, solidos totais); qs de temperatura constante
igual a 92; sem OD ou microbiologico o IQA nao e calculado; o peso dos
demais ausentes e repartido igualmente. A turbidez usa o coeficiente
1,5 no termo do cosseno (Bucci 2011; Nunes 2008), em vez do
15 impresso em copias do SCQA. A implementacao reproduz 49/49 IQAs
publicados pelo IGAM (sub-bacia da Pampulha, 2017-2018), mas nao e
homologada pelo IGAM e nao foi validada em outras bacias.
Entradas: od (mg/L), temperatura e cloreto (mg/L; a
saturacao de OD do SCQA exige cloreto, sem valor padrao), e_coli ou
coliformes_termotolerantes (sem fator de conversao; se ambas
existirem, informe microbial_type), ph, dbo,
nitrato (exige nitrate_unit), fosfato_total (PO4) ou
p_total (exige phosphorus_basis explicito), turbidez e
solidos_totais. Nitrogenio total, ortofosfato e TDS nao substituem
nitrato, fosfato total e solidos totais. allow_partial, pesos
e os argumentos de temperatura do CETESB nao se aplicam (erro).
O IQA e arredondado a 1 casa (como o IGAM publica) e a classe IGAM e
atribuida sobre esse valor; details = TRUE traz o valor bruto, os qi
e os pesos efetivos. Nota completa: system.file("methodology",
"IGAM_VALIDATION.md", package = "tikatuwq").
Valores invalidos
Concentracoes negativas, pH fora de [0, 14], temperatura fora de [-2, 50] C e
valores nao finitos sao convertidos em NA com aviso (e nao truncados
para zero).
Examples
d <- data.frame(
od = 6.5, temperatura = 25, dbo = 2, coliformes = 200,
ph = 7.2, nt_total = 1.2, p_total = 0.05, turbidez = 8,
solidos_totais = 120
)
out <- iqa(d)
out$IQA
#> [1] 74.96
out$IQA_status
#> [1] Boa
#> Levels: Pessima < Ruim < Regular < Boa < Otima
# Outra escala para o mesmo numero: use classify_iqa()
classify_iqa(out$IQA, classification = "igam")
#> [1] Bom
#> Levels: Muito Ruim < Ruim < Medio < Bom < Excelente
# Metodos disponiveis e escopo de validacao
iqa_methods()
#> method implemented documented reference_validated available
#> 1 CETESB TRUE TRUE TRUE TRUE
#> 2 IGAM TRUE TRUE TRUE TRUE
#> 3 CETESB_legacy_approx TRUE TRUE FALSE TRUE
#> 4 NSF_approx TRUE TRUE FALSE TRUE
#> classification
#> 1 cetesb
#> 2 igam
#> 3 cetesb
#> 4 cetesb
#> limitation
#> 1 qi equations approximate the graphical CETESB curves (secondary sources); validated against a published worked example (von Sperling 2007 via IBEAS 2015); pH 9-10 and delta-T curve pending
#> 2 not endorsed by IGAM; turbidity k = 1.5 from the literature (SCQA copies print 15); reproduces 49/49 published IGAM IQAs, all from the Pampulha sub-basin (2017-2018), nitrate mostly censored; requires chloride and an explicit nitrate unit
#> 3 legacy; interpolated approximate curves
#> 4 legacy; interpolated approximate curves, arithmetic mean
#> reference
#> 1 CETESB (2023) Apendice D; CPRH PNMA II; von Sperling (2007) via IBEAS (2015)
#> 2 SEMAD/UCEMG/PNMA II (2005) SCQA Relatorio 1; IGAM portal; Bucci (2011, UFJF); Nunes (2008, UFV)
#> 3 -
#> 4 -
# IQA pelo metodo IGAM (reproducao documentada, nao homologada pelo IGAM).
# Amostra sintetica; as unidades de nitrato (mg/L N) e de fosforo total
# (mg/L P) sao declaradas explicitamente.
g <- data.frame(
od = 7, temperatura = 25, cloreto = 10, e_coli = 100, ph = 7.3,
dbo = 2, nitrato = 1, p_total = 0.1, turbidez = 5, solidos_totais = 100
)
iqa(g, method = "IGAM", altitude_m = 0, nitrate_unit = "N",
phosphorus_basis = "P") # IQA 75.5, "Bom"
#> od temperatura cloreto e_coli ph dbo nitrato p_total turbidez solidos_totais
#> 1 7 25 10 100 7.3 2 1 0.1 5 100
#> IQA IQA_status
#> 1 75.5 Bom
# Auditoria: pesos efetivos e termos por componente
comps <- attr(iqa(d, details = TRUE), "components")
prod(unlist(comps[1, grep("^term_", names(comps))]))
#> [1] 74.9575