Hidroana

Biblioteca Python para consulta, download, processamento e visualização de dados hidrológicos da Agência Nacional de Águas e Saneamento Básico (ANA).

O projeto acessa os serviços SOAP da ANA e organiza séries de estações convencionais e telemétricas em arquivos CSV, mapas, gráficos de disponibilidade e médias de chuva por Thiessen.

Recursos

• Consulta do inventário oficial de estações da ANA.
• Download de séries telemétricas de chuva, nível e vazão.
• Download de séries históricas convencionais de cota, chuva e vazão.
• Seleção espacial por Shapefile ou GeoPackage, com buffer opcional.
• Mapas interativos de estações e completude.
• Gráficos de disponibilidade em HTML e PNG.
• Cálculo de chuva média por polígonos de Thiessen.
• Exportação automática em CSV.

Instalação

pip install hidroana

Dependências Principais

• pandas
• numpy
• tqdm
• zeep
• geopandas
• shapely
• geovoronoi
• plotly
• matplotlib

Importação

import hidroana

Funções

get_inventory

Consulta o inventário oficial de estações hidrológicas da ANA.

df = hidroana.get_inventory(
    caminho_saida="inventario_ana.csv",
    var_codEstDE="",
    var_codEstATE="",
    var_tpEst="",
    var_nmEst="",
    var_nmRio="",
    var_codSubBacia="",
    var_codBacia="",
    var_nmMunicipio="",
    var_nmEstado="",
    var_sgResp="",
    var_sgOper="",
    var_telemetrica="",
    save=False
)

Parâmetros

Exemplo

inventario = hidroana.get_inventory(
    var_nmEstado="Santa Catarina",
    var_telemetrica="1",
    save=True,
    caminho_saida="inventario_sc_tele.csv"
)

get_conv_data_list

Baixa séries históricas convencionais de uma lista de estações.

hidroana.get_conv_data_list(
    list_est=['70150000','72300000'],
    d_i='1990-01-01',
    d_f='2020-12-31',
    tipo='3',
    disp=True
)

Parâmetros

Exemplo

hidroana.get_conv_data_list(
    ["2549000"],
    "1990-01-01",
    "2020-12-31",
    tipo="3",
    caminho="./vazao/",
    cons=1,
    disp=True
)

Gráfico de disponibilidade gerado

get_conv_inventory

Baixa séries convencionais para todas as estações compatíveis de um inventário.

resumo = hidroana.get_conv_inventory(
    df,
    tipo,
    caminho="",
    cons=1,
    save_info=False,
    disp=False,
    loc=False
)

Parâmetros

Exemplo

inventario = hidroana.get_inventory(var_nmEstado="Alagoas")

resumo = hidroana.get_conv_inventory(
    inventario,
    tipo="2",
    caminho="./chuva/",
    cons=1,
    save_info=True,
    disp=False,
    loc=True
)

Mapa de disponibilidade gerado

get_telemetric_inventory

Baixa dados telemétricos para todas as estações telemétricas presentes em um inventário.

resumo = hidroana.get_telemetric_inventory(
    df,
    caminho="",
    save_info=False,
    disp=False,
    loc=False,
    shape_area=None
)

Parâmetros

Exemplo

inventario = hidroana.get_inventory(var_nmEstado="Alagoas")

resumo = hidroana.get_telemetric_inventory(
    inventario,
    caminho="./dados_tele/",
    save_info=True,
    disp=True,
    loc=True
)

get_telemetric_list

Baixa dados telemétricos de uma lista específica de estações.

hidroana.get_telemetric_list(
    list_est,
    d_i,
    d_f,
    caminho="",
    disp=False,
    byshape=False
)

Parâmetros

Exemplo

hidroana.get_telemetric_list(
    ["74355000", "74270000"],
    "2020-01-01",
    "2020-12-31",
    caminho="./dados_tele/",
    disp=True
)

get_series_by_shape

Seleciona estações dentro de uma área espacial e baixa automaticamente as séries.

hidroana.get_series_by_shape(
    arquivo,
    d_i,
    d_f,
    buffer_km=0,
    atributo=None,
    valor=None,
    rede="ambos",
    tipo_dado="2",
    caminho="",
    save_inventory=True,
    disp=False,
    loc=False,
    media=False
)

Parâmetros

Exemplo com Bacia

hidroana.get_series_by_shape(
    arquivo="bacia.shp",
    d_i="2000-01-01",
    d_f="2020-12-31",
    buffer_km=10,
    rede="ambos",
    tipo_dado="2",
    caminho="./saida/",
    save_inventory=True,
    disp=True,
    loc=True,
    media=True
)

Exemplo com Filtro por Atributo

hidroana.get_series_by_shape(
    '../CABra_boundaries.shp',
    '1990-01-01',
    '2026-01-01',  
    buffer_km=2,
    rede="ambos",
    atributo= 'ID_CABra',
    valor=296,
    tipo_dado="2",
    caminho="",
    save_inventory=True,
    disp=True,
    loc=True,
    media=True
)

Mapa de disponibilidade gerado

Funções de Apoio

plot_disp

Gera gráfico de disponibilidade de dados em HTML e PNG.

plot_map_estacoes

Gera mapa interativo de estações com completude e quantidade de anos.

media_thiessen

Calcula chuva média usando pesos de Thiessen, ajustando os pesos às estações disponíveis em cada dia.

calcular_pesos_thiessen

Calcula os pesos de Thiessen para um conjunto de estações dentro de uma área.

n_anos_perc

Calcula a quantidade de anos cobertos e a completude percentual de uma série.

voronoi_finite_polygons_2d

Converte regiões infinitas de um diagrama de Voronoi em polígonos finitos.

Arquivos Gerados

Dependendo da função e dos parâmetros usados, a biblioteca pode gerar:

• {codigo}.csv: série temporal de uma estação.
• info_estacoes.csv: resumo de disponibilidade por estação.
• inventario_filtrado.csv: inventário espacialmente filtrado.
• mapa_estacoes_{dado}.html: mapa interativo.
• mapa_estacoes_{dado}.csv: dados usados no mapa.
• giant_plot_disponibilidade_{dado}_{tipo}.html: gráfico interativo de disponibilidade.
• giant_plot_disponibilidade_{dado}_{tipo}.png: gráfico estático de disponibilidade.
• chuva_media_thiessen.csv: chuva média por Thiessen.

Observações Importantes

• As funções fazem requisições pela internet aos serviços da ANA.
• A disponibilidade depende do serviço e dos dados publicados pela ANA.
• Datas devem estar no formato YYYY-MM-DD.
• Algumas estações podem existir no inventário, mas não retornar séries para o período solicitado.
• Em estações telemétricas com código pluviométrico e fluviométrico, muitas vezes o serviço retorna melhor usando o código fluviométrico.

Fonte dos Dados

Agência Nacional de Águas e Saneamento Básico (ANA)

https://www.gov.br/ana/

Autoria

Grenda Menezes

E-mail: grenda.menezes@gmail.com