Metadata-Version: 2.4
Name: iqa_calculator
Version: 2.1.0
Summary: Open-source CETESB Water Quality Index (IQA/WQI) calculator
Home-page: https://github.com/seitbnao/iqa_calculator
Author: Djunio Rosa de Melo Filho
Author-email: d291223@dac.unicamp.br
License: GPL-3.0-only
Project-URL: Source, https://github.com/seitbnao/iqa_calculator
Project-URL: Issues, https://github.com/seitbnao/iqa_calculator/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# Calculadora de IQA / WQI Calculator

`iqa_calculator` calcula o Índice de Qualidade das Águas (IQA) pela
formulação CETESB: nove subíndices, pesos de referência e agregação
geométrica ponderada. A versão 2.1.0 corrige inconsistências de transcrição das equações,
normaliza o caminho de importação para Linux e acrescenta rastreabilidade.

## Instalação

```bash
python -m pip install iqa_calculator
```

## Uso básico

```python
from iqa import IQA

resultado = IQA(
    oxigenio_dissolvido=8.0,       # mg O2/L
    coliformes_fecais=200,         # NMP/100 mL
    ph=7.0,
    dbo=5.0,                       # mg O2/L
    nitrogenio_total=1.0,          # mg N/L
    fosforo_total=0.1,             # mg P/L
    turbidez=2.0,                  # UNT
    solidos_totais=100.0,          # mg/L
)
print(resultado)
# {'iqa': 73.73, 'qualidade': 'Boa'}
```

Altitude e temperatura da água podem ser informadas para o cálculo da
saturação de oxigênio; os padrões são 200 m e 22 °C. `WQI` é um alias de
`IQA`.

## Rastreabilidade

```python
detalhes = IQA(..., return_details=True)
```

Além do índice e da classe, a resposta passa a incluir os nove subíndices, os
pesos efetivamente usados, a saturação percentual de oxigênio e a concentração
de fosfato empregada.

## Convenção para fósforo

Por padrão, `fosforo_total` deve ser fornecido em mg P/L e é convertido para
mg PO4/L pelo fator estequiométrico 3,066 antes da curva de qualidade. Se o
valor de entrada já estiver em mg PO4/L, use
`fosforo_como_fosfato=True`. Esta escolha fica registrada no retorno detalhado.

## Pesos personalizados

`weights` aceita uma sequência de nove valores, na ordem documentada abaixo,
ou um dicionário parcial com os nomes dos parâmetros. Pesos válidos são
normalizados para soma unitária; valores negativos, não finitos ou soma nula
são rejeitados.

| Ordem | Chave | Peso de referência |
|---:|---|---:|
| 1 | `oxigenio_dissolvido` | 0,17 |
| 2 | `coliformes_fecais` | 0,15 |
| 3 | `ph` | 0,12 |
| 4 | `dbo` | 0,10 |
| 5 | `nitrogenio_total` | 0,10 |
| 6 | `fosforo_total` | 0,10 |
| 7 | `temperatura` | 0,10 |
| 8 | `turbidez` | 0,08 |
| 9 | `solidos_totais` | 0,08 |

## Escopo e limitação

O IQA sintetiza condições relacionadas principalmente ao abastecimento após
tratamento convencional. Ele não substitui a interpretação dos parâmetros
individuais nem inclui contaminantes tóxicos, pesticidas, metais ou outros
indicadores específicos. O subíndice térmico permanece fixo em 94 porque a API
recebe a temperatura da amostra para saturação de oxigênio, mas não a variação
térmica em relação à condição de equilíbrio.

## Verificação

```bash
python -m pip install -r requirements-dev.txt
python -m pytest -q
```

A suíte 2.1.0 contém 70 testes, incluindo 45 valores de fronteira das curvas,
regressão do resultado composto, conversão de fósforo, pesos e domínios de
entrada.

## Licença

Distribuído sob a GNU General Public License v3.0 (GPL-3.0-only).
