Functions

Oferece um conjunto de funções utilitárias para auxiliar no processamento, filtragem e manipulação de dados hidrológicos, além de funcionalidades para interação com elementos gráficos do Bokeh.

Índice

1. Visão Geral
2. Check adequations
3. Clamp date
4. Filter adequations
5. Filter by date
6. Filtrar por ano
7. Filtrar por mês
8. Transform to datetime long format
9. Set x range
10. Set y range list
11. Random color
12. Format dict for table

Visão Geral

O módulo utils centraliza um conjunto de funções de apoio que visam otimizar diversas operações, incluindo:

• Verificação de Adequações: Funcionalidades para verificar e filtrar adequações pendentes em períodos específicos.
• Manipulação de Datas: Métodos para restringir e filtrar dados de DataFrames com base em intervalos de datas (ano, mês, janela, delta de dias).
• Transformação de Dados: Capacidade de reestruturar DataFrames para diferentes formatos, como o formato longo de data/hora.
• Configuração de Gráficos Bokeh: Funções para ajustar os ranges dos eixos X e Y de gráficos Bokeh dinamicamente.
• Geração de Cores Aleatórias: Um utilitário para gerar cores RGB aleatórias.
• Formatação de Dados para Tabela: Ferramentas para formatar dicionários de dados em DataFrames adequados para exibição em tabelas.
• Atualização de ColumnDataSource: Método seguro para atualizar dados em um ColumnDataSource do Bokeh, mantendo a seleção.

Check adequations

Verifica se existem adequações pendentes em um intervalo de tempo.

Parâmetros: source_dates (np.ndarray): As datas do ColumnDataSource exibidas no gráfico. adequation_dates (pd.Series): As datas das adequações pendentes.

Returns: bool: True se houver adequações pendentes no período, False caso contrário.

Clamp date

Restringe uma data dentro de um intervalo mínimo e máximo. Se a data fornecida estiver fora dos limites definidos por min_date e max_date, ela será ajustada para o valor mais próximo dentro desse intervalo.

Parâmetros: date (date): A data a ser ajustada. min_date (date): O menor valor permitido para a data. max_date (date): O maior valor permitid* para a data.

Raises: ValueError: Se min_date for maior que max_date.

Returns: date: A data ajustada dentro do intervalo permitido.

Filter adequations

Filtra as adequações. Utilizado na supervisão.

Parâmetros: input_df (pd.DataFrame): O DataFrame de entrada contendo as adequações. id_adequacao (int | None): Opção de filtro por ID da adequação. Padrão é None. adequacao_label (str): O rótulo (nome da coluna) do ID da adequação. Padrão é "id_adequacao". periodo (tuple[str] | None): Opção de filtro por período de trabalho (tupla com data de início e fim no formato string). Padrão é None. period_label (str): O rótulo (nome da coluna) do período de trabalho. Padrão é "data_hora_registro".

Returns: pd.DataFrame: Um DataFrame contendo as adequações filtradas.

Filter by date

Filtra um DataFrame por data.

Parâmetros: input_df (pd.DataFrame): O DataFrame de entrada. date (date): A data de referência. Padrão é None. delta (int): A margem de dias antes e depois da data de referência. Padrão é 15.

Returns: pd.DataFrame: O DataFrame filtrado por data.

Filtrar por ano

Filtra um DataFrame por ano.

Parâmetros: dataframe (pd.DataFrame): O DataFrame de entrada. year (int): O ano de referência para a filtragem. delta_antes (int): Quantidade de dias a serem incluídos antes do início do ano. Padrão é 0. delta_depois (int): Quantidade de dias a serem incluídos depois do final do ano. Padrão é 0.

Returns: pd.DataFrame: O DataFrame filtrado por ano.

Filtrar por mês

Filtra um DataFrame por mês.

Parâmetros: dataframe (pd.DataFrame): O DataFrame de entrada. year (int): O ano do mês de referência. month (int): O mês de referência. delta_antes (int): Quantidade de dias a serem incluídos antes do início do mês. Padrão é 0. delta_depois (int): Quantidade de dias a serem incluídos depois do final do mês. Padrão é 0.

Returns: pd.DataFrame: O DataFrame filtrado por mês.

Transform to datetime long format

Transforma um DataFrame de formato wide para long, adiciona uma coluna combinada de data e hora, detectando automaticamente os sufixos de horário das colunas base.

Parâmetros: source_df (pd.DataFrame): O DataFrame de entrada. base_column (str): Nome da coluna base que é sufixada com horários (e.g., "data_07h"). id_vars (list[str]): Colunas a serem mantidas durante a operação de melt. Padrão é ["data"]. time_map (dict[str, str]): Mapeamento opcional dos sufixos para valores de hora (e.g., {"07h": "07:00:00"}). Padrão é None. date_column_name (str): Nome da coluna de data. Padrão é "data". time_column_name (str): Nome da coluna de hora. Padrão é "hora". datetime_column_name (str): Nome da coluna de data e hora combinadas. Padrão é "data_hora".

Returns: pd.DataFrame: O DataFrame transformado com a coluna de data e hora.

Set x range

Ajusta o range do eixo x de um gráfico com base nas datas fornecidas.

Parâmetros: plot (figure): O objeto de gráfico Bokeh. start_date (date): A data de início desejada para o eixo x. end_date (date): A data de fim desejada para o eixo x. min_date (date): A data mínima absoluta permitida para o range do eixo x. Padrão é None. max_date (date): A data máxima absoluta permitida para o range do eixo x. Padrão é None. date_padding (int): Dias de margem (padding) a serem adicionados ao início e fim do range. Padrão é 1.

Set y range list

Ajusta um y range com base nos valores máximos e mínimos de uma lista de DataFrames.

Parâmetros: range_to_set (Range1d): O objeto Range1d (o y range) a ser ajustado. filtered_data_list (List[pd.Series] | List[pd.DataFrame]): A lista de DataFrames ou Series a serem inspecionados para determinar os limites do range.

Random color

Retorna uma tupla contendo uma cor RGB aleatória.

Returns: (r, g, b) (tuple): Uma tupla com três valores inteiros aleatórios entre 0 e 255, representando as componentes RGB.

Format dict for table

Formata um dicionário de dados (tipicamente resultados de filtragem por hora) em um DataFrame adequado para exibição em uma tabela.

Parâmetros: dict (dict): O dicionário de entrada contendo os dados a serem formatados.

Returns: pd.DataFrame: O DataFrame formatado pronto para exibição em tabela, com a coluna 'data' como índice.

Update source and selection

Atualiza os dados de um DataFrame de forma segura.

Parâmetros: source (ColumnDataSource): O ColumnDataSource a ser atualizado. new_data (pd.DataFrame): O DataFrame contendo os novos dados para o ColumnDataSource.