Algorithms
Define uma estrutura para a implementação de diferentes algoritmos de processamento de dados hidrológicos, como ajuste de Referência de Nível (RN), interpolação e offset, além de uma função para regressão entre dados de régua e PCD.
Índice
Visão Geral
O módulo algorithms centraliza a lógica para diversas técnicas de tratamento de dados hidrológicos, oferecendo:
- Estrutura Abstrata: Uma classe base (
Algorithm) que define a interface para todos os algoritmos de processamento. - Ajuste de RN: Um algoritmo específico para realizar o ajuste de valores de cota com base em uma mudança de Referência de Nível.
- Interpolação: Algoritmos para preencher lacunas em séries de dados através de interpolação por spline (quadrática e cúbica) e regressão polinomial.
- Offset: Um método para aplicar um valor de ajuste constante a um intervalo de dados.
- Regressão Régua-PCD: Uma função utilitária para corrigir dados de PCD usando um modelo de regressão baseado em dados de régua.
- Validação de Dados: Funções para garantir que os pontos de ancoragem usados nos algoritmos não sejam nulos.
Algorithm
Classe base abstrata para todos os algoritmos de processamento de dados.
Init
Inicializa uma nova instância de Algorithm.
Calc
Método abstrato que deve ser implementado por todas as subclasses. Ele define a interface para o cálculo principal do algoritmo.
Parâmetros:
args: Argumentos posicionais flexíveis.
kwargs`: Argumentos nomeados flexíveis.
Returns:
Any: O resultado do cálculo do algoritmo.
Null anchor points
Função para chechar se há pontos inconsistentes selecionados na adequação.
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada, com índices inteiros.
selected_rows (List[int]): Uma lista dos índices das linhas selecionadas na tabela.
numeric_label (str): O nome da coluna numérica a ser verificada.
Returns:
bool: True se todos os dados selecionados forem consistentes (não nulos), False caso contrário.
Adjust RN
Implementa o algoritmo para o ajuste de Referência de Nível (RN) em séries de dados hidrológicos.
Calc RN
Realiza o ajuste de RN, adicionando um valor constante a todos os dados numéricos de uma data de referência para trás.
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada.
numeric_label (str): O rótulo da coluna que descreve os dados numéricos associados às datas.
date (str): A data de referência do ajuste. Os valores numéricos dessa data e das anteriores serão alterados.
value (float): O valor de ajuste a ser adicionado.
Returns:
pd.DataFrame: O DataFrame com os ajustes numéricos aplicados da data mínima até a data de referência.
Interpolation
Implementa métodos de interpolação e regressão para preencher lacunas ou suavizar dados.
Calc interpolation
Aplica um método de interpolação ou regressão para corrigir pontos selecionados no DataFrame, retornando o DataFrame interpolado e o coeficiente de determinação (R²).
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada.
numeric_label (str): O rótulo da coluna que descreve os dados numéricos associados às datas.
order (int | Any): A ordem do polinômio a ser utilizada (grau da interpolação/regressão).
selected_rows (list[int]): Os índices das linhas selecionadas na tabela que servirão como pontos de ancoragem.
method (str | Any): O método de interpolação a ser utilizado ("Interpolação por Spline" ou "Regressão").
Raises:
ValueError: Se nenhum ponto for selecionado, se os pontos de ancoragem forem nulos, se o método ou a ordem forem inválidos, ou se não houver pontos suficientes para o grau especificado.
Returns:
tuple: Uma tupla contendo:
pd.DataFrame: O DataFrame com a interpolação dos pontos selecionados.
float: O Coeficiente de Determinação (R²) do modelo.
Spline
Realiza a interpolação dos dados utilizando o método de spline (quadrática ou cúbica), com base nos pontos selecionados.
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada.
numeric_label (str): O rótulo da coluna numérica.
order (int): A ordem do polinômio (2 para spline quadrática, 3 para spline cúbica).
selected_rows (list[int]): Os índices das linhas selecionadas para ancoragem.
Raises:
ValueError: Se a ordem não for 2 ou 3.
Returns:
pd.DataFrame: O DataFrame com os valores interpolados dentro do intervalo dos pontos selecionados.
Regressão
Realiza a interpolação dos dados utilizando o método de regressão polinomial, com base nos pontos selecionados.
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada.
numeric_label (str): O rótulo da coluna numérica.
order (int): A ordem do polinômio para a regressão.
selected_rows (list[int]): Os índices das linhas selecionadas para ancoragem.
Returns:
pd.DataFrame: O DataFrame com os valores ajustados pela regressão dentro do intervalo dos pontos selecionados.
Offset
Implementa a técnica de adequação por offset, aplicando um ajuste de valor constante a um intervalo de datas.
Calc offset
Realiza a aplicação de um offset (ajuste constante) aos dados numéricos dentro de um período definido.
Parâmetros:
input_df (pd.DataFrame): O DataFrame de entrada.
numeric_label (str): O rótulo da coluna que descreve os dados numéricos.
start_date (str): A data de início do período para aplicação do offset.
end_date (str): A data de fim do período para aplicação do offset.
value (float): O valor de ajuste a ser adicionado ou subtraído.
Raises:
ValueError: Se a data inicial for maior que a data final.
Returns:
tuple: Uma tupla contendo:
pd.DataFrame: O DataFrame com os ajustes numéricos aplicados.
pd.DataFrame: O subset do DataFrame que contém as mudanças aplicadas pelo offset.
Regressão régua PCD
Aplica um modelo de regressão linear para corrigir valores faltantes na coluna cota_sipam_pcd de um DataFrame, utilizando dados da coluna cota_sipam_regua como base de correção.
Parâmetros:
input_df (pd.DataFrame): DataFrame com DatetimeIndex, contendo as colunas cota_sipam_pcd e cota_sipam_regua.
order (int): A ordem do polinômio para a regressão.
Raises:
ValueError: Se o período selecionado for insuficiente para realizar a regressão com o grau especificado.
Returns:
tuple: Uma tupla contendo:
np.ndarray: Um array com os valores corrigidos da coluna 'cota_sipam_pcd'.
float: O Coeficiente de Determinação (R²) do modelo de regressão.