# cabral-e/previsao-demanda-hidrica-horaria architecture

> Architecture diagram of the GitHub repository cabral-e/previsao-demanda-hidrica-horaria, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cabral-e/previsao-demanda-hidrica-horaria
- Repository: https://github.com/cabral-e/previsao-demanda-hidrica-horaria

## Overview

Este repositório implementa um estudo reprodutível de previsão horária do nível de um reservatório e comparação entre erro preditivo e custo computacional. O fluxo principal parte da planilha de origem, prepara e divide temporalmente a série, constrói atributos, executa modelos por horizonte e registra previsões e custos; análises estatísticas e de Pareto consolidam os resultados para relatórios e figuras. O README documenta também EDA, seleção de defasagens e preparação para publicação. Relações entre módulos não amostrados foram incluídas apenas quando sustentadas pelo SOURCE INDEX ou pelo README.

Main entry points: [`src/evaluation/runner.py`](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/runner.py) (Executor de experimentos), [`src/evaluation/registry.py`](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/registry.py) (Registro de experimentos), [`src/data/load.py`](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/load.py) (Carga da base), [`src/evaluation/metrics_report.py`](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/metrics_report.py) (Métricas e Diebold–Mariano)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dados e preparação"]
  node_data_load["Carga da base<br/>[load.py]"]
  node_inspection["Inspeção<br/>[inspection.py]"]
  node_temporal_filter["Filtro temporal<br/>[temporal_filter.py]"]
  node_treatment["Tratamento<br/>[treatment.py]"]
  node_eda["Análise exploratória<br/>[eda.py]"]
  node_split["Divisão temporal<br/>[split.py]"]
end

subgraph group_features_models["Atributos e modelos"]
  node_lag_evaluation["Seleção de defasagens<br/>[lag_evaluation.py]"]
  node_feature_build["Construção de atributos<br/>[build.py]"]
  node_baselines["Baselines<br/>[baseline.py]"]
  node_sarima["SARIMA<br/>[sarima.py]"]
  node_svr["SVR<br/>[svr.py]"]
  node_lightgbm["LightGBM direto e recursivo<br/>[lightgbm_model.py]"]
  node_direct_forecaster["Previsor direto<br/>[ml_direct.py]"]
  node_recursive_forecaster["Previsor recursivo<br/>[ml_recursive.py]"]
end

subgraph group_evaluation["Execução e avaliação"]
  node_protocol["Protocolo de avaliação<br/>[protocol.py]"]
  node_runner["Executor de experimentos<br/>[runner.py]"]
  node_cost["Medição de custo<br/>[cost.py]"]
  node_metrics["Métricas<br/>[metrics.py]"]
  node_registry[("Registro de experimentos<br/>[registry.py]")]
  node_cost_batch["Remedição de custos<br/>[cost_batch.py]"]
  node_cost_report["Consolidação de custos<br/>[cost_report.py]"]
  node_metrics_report["Métricas e Diebold–Mariano<br/>[metrics_report.py]"]
  node_strategy_check["Verificação de estratégia<br/>[strategy_check.py]"]
  node_composite["Score composto<br/>[composite.py]"]
  node_pareto["Fronteira de Pareto<br/>[pareto.py]"]
  node_consolidate["Tabela final<br/>[consolidate.py]"]
end

subgraph group_outputs["Resultados e visualização"]
  node_predictions[("Previsões persistidas<br/>[runner.py]")]
  node_figure_generation["Geração de figuras<br/>[make_figures.py]"]
  node_plots["Gráficos<br/>[plots.py]"]
  node_style["Estilo visual<br/>[style.py]"]
end

subgraph group_support["Suporte interno"]
  node_paths["Caminhos e configuração<br/>[paths.py]"]
  node_persistence["Persistência auditável<br/>[persistence.py]"]
end

node_researcher(("Pesquisador"))
node_source_workbook["Planilha Sanepar"]

node_researcher -->|"inicia etapas"| node_data_load
node_source_workbook -->|"fornece base"| node_data_load
node_data_load -->|"carrega dados"| node_inspection
node_inspection -->|"apoia filtro"| node_temporal_filter
node_inspection -->|"apoia tratamento"| node_treatment
node_data_load -->|"lê base"| node_temporal_filter
node_data_load -->|"lê base"| node_treatment
node_data_load -->|"carrega série"| node_split
node_data_load -->|"fornece série"| node_eda
node_split -->|"fornece divisão"| node_eda
node_data_load -->|"fornece dados"| node_lag_evaluation
node_split -->|"fornece divisão"| node_lag_evaluation
node_feature_build -->|"constrói atributos"| node_lag_evaluation
node_feature_build -->|"gera atributos"| node_direct_forecaster
node_feature_build -->|"gera atributos"| node_recursive_forecaster
node_direct_forecaster -->|"apoia previsão"| node_recursive_forecaster
node_direct_forecaster -->|"implementa estratégia"| node_lightgbm
node_recursive_forecaster -->|"implementa variante"| node_lightgbm
node_protocol -->|"define avaliação"| node_runner
node_baselines -->|"executa experimento"| node_runner
node_sarima -->|"executa experimento"| node_runner
node_svr -->|"executa experimento"| node_runner
node_lightgbm -->|"executa experimento"| node_runner
node_runner -->|"obtém origens"| node_protocol
node_runner -->|"mede execução"| node_cost
node_runner -->|"calcula métricas"| node_metrics
node_runner -->|"registra experimento"| node_registry
node_runner -->|"grava previsões"| node_predictions
node_cost_batch -->|"remede modelos"| node_baselines
node_cost_batch -->|"remede modelos"| node_sarima
node_cost_batch -->|"remede modelos"| node_svr
node_cost_batch -->|"remede modelos"| node_lightgbm
node_registry -->|"fornece registros"| node_cost_report
node_metrics_report -->|"compara métricas"| node_cost_report
node_registry -->|"fornece experimentos"| node_metrics_report
node_metrics -->|"calcula medidas"| node_metrics_report
node_registry -->|"fornece registros"| node_strategy_check
node_registry -->|"fornece experimentos"| node_composite
node_metrics_report -->|"fornece métricas"| node_composite
node_cost_report -->|"fornece custos"| node_composite
node_registry -->|"fornece experimentos"| node_pareto
node_cost_report -->|"fornece custos"| node_pareto
node_metrics_report -->|"fornece métricas"| node_pareto
node_registry -->|"fornece experimentos"| node_consolidate
node_metrics_report -->|"fornece métricas"| node_consolidate
node_registry -->|"fornece resultados"| node_figure_generation
node_metrics_report -->|"fornece métricas"| node_figure_generation
node_figure_generation -->|"gera gráficos"| node_plots

click node_data_load "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/load.py"
click node_inspection "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/inspection.py"
click node_temporal_filter "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/temporal_filter.py"
click node_treatment "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/treatment.py"
click node_eda "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/eda.py"
click node_split "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/split.py"
click node_lag_evaluation "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/features/lag_evaluation.py"
click node_feature_build "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/features/build.py"
click node_baselines "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/baseline.py"
click node_sarima "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/sarima.py"
click node_svr "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/svr.py"
click node_lightgbm "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/lightgbm_model.py"
click node_direct_forecaster "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/ml_direct.py"
click node_recursive_forecaster "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/ml_recursive.py"
click node_protocol "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/protocol.py"
click node_runner "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/runner.py"
click node_cost "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost.py"
click node_metrics "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/metrics.py"
click node_registry "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/registry.py"
click node_cost_batch "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost_batch.py"
click node_cost_report "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost_report.py"
click node_metrics_report "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/metrics_report.py"
click node_strategy_check "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/strategy_check.py"
click node_composite "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/composite.py"
click node_pareto "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/pareto.py"
click node_consolidate "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/consolidate.py"
click node_predictions "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/runner.py"
click node_figure_generation "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/make_figures.py"
click node_plots "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/plots.py"
click node_style "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/style.py"
click node_paths "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/utils/paths.py"
click node_persistence "https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/utils/persistence.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_load,node_inspection,node_temporal_filter,node_treatment,node_eda,node_split toneBlue
class node_lag_evaluation,node_feature_build,node_baselines,node_sarima,node_svr,node_lightgbm,node_direct_forecaster,node_recursive_forecaster toneAmber
class node_protocol,node_runner,node_cost,node_metrics,node_registry,node_cost_batch,node_cost_report,node_metrics_report,node_strategy_check,node_composite,node_pareto,node_consolidate toneMint
class node_predictions,node_figure_generation,node_plots,node_style toneRose
class node_paths,node_persistence,node_researcher,node_source_workbook toneIndigo
```

## Components

### Dados e preparação

- [Carga da base](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/load.py): `src/data/load.py`
- [Inspeção](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/inspection.py): `src/data/inspection.py`
- [Filtro temporal](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/temporal_filter.py): `src/data/temporal_filter.py`
- [Tratamento](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/treatment.py): `src/data/treatment.py`
- [Análise exploratória](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/eda.py): `src/data/eda.py`
- [Divisão temporal](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/data/split.py): `src/data/split.py`

### Atributos e modelos

- [Seleção de defasagens](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/features/lag_evaluation.py): `src/features/lag_evaluation.py`
- [Construção de atributos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/features/build.py): `src/features/build.py`
- [Baselines](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/baseline.py): `src/models/baseline.py`
- [SARIMA](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/sarima.py): `src/models/sarima.py`
- [SVR](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/svr.py): `src/models/svr.py`
- [LightGBM direto e recursivo](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/lightgbm_model.py): `src/models/lightgbm_model.py`
- [Previsor direto](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/ml_direct.py): `src/models/ml_direct.py`
- [Previsor recursivo](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/models/ml_recursive.py): `src/models/ml_recursive.py`

### Execução e avaliação

- [Protocolo de avaliação](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/protocol.py): `src/evaluation/protocol.py`
- [Executor de experimentos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/runner.py): `src/evaluation/runner.py`
- [Medição de custo](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost.py): `src/evaluation/cost.py`
- [Métricas](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Registro de experimentos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/registry.py): `src/evaluation/registry.py`
- [Remedição de custos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost_batch.py): `src/evaluation/cost_batch.py`
- [Consolidação de custos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/cost_report.py): `src/evaluation/cost_report.py`
- [Métricas e Diebold–Mariano](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/metrics_report.py): `src/evaluation/metrics_report.py`
- [Verificação de estratégia](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/strategy_check.py): `src/evaluation/strategy_check.py`
- [Score composto](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/composite.py): `src/evaluation/composite.py`
- [Fronteira de Pareto](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/pareto.py): `src/evaluation/pareto.py`
- [Tabela final](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/consolidate.py): `src/evaluation/consolidate.py`

### Resultados e visualização

- [Previsões persistidas](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/evaluation/runner.py): `src/evaluation/runner.py`
- [Geração de figuras](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/make_figures.py): `src/visualization/make_figures.py`
- [Gráficos](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/plots.py): `src/visualization/plots.py`
- [Estilo visual](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/visualization/style.py): `src/visualization/style.py`

### Suporte interno

- [Caminhos e configuração](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/utils/paths.py): `src/utils/paths.py`
- [Persistência auditável](https://github.com/cabral-e/previsao-demanda-hidrica-horaria/blob/main/src/utils/persistence.py): `src/utils/persistence.py`

### Other components

- **Pesquisador**
- **Planilha Sanepar**

## Connections

- Pesquisador → Carga da base: inicia etapas
- Planilha Sanepar → Carga da base: fornece base
- Carga da base → Inspeção: carrega dados (evidence: `src/data/inspection.py`)
- Inspeção → Filtro temporal: apoia filtro (evidence: `src/data/temporal_filter.py`)
- Inspeção → Tratamento: apoia tratamento (evidence: `src/data/treatment.py`)
- Carga da base → Filtro temporal: lê base (evidence: `src/data/temporal_filter.py`)
- Carga da base → Tratamento: lê base (evidence: `src/data/treatment.py`)
- Carga da base → Divisão temporal: carrega série (evidence: `src/data/split.py`)
- Carga da base → Análise exploratória: fornece série (evidence: `src/data/eda.py`)
- Divisão temporal → Análise exploratória: fornece divisão (evidence: `src/data/eda.py`)
- Carga da base → Seleção de defasagens: fornece dados (evidence: `src/features/lag_evaluation.py`)
- Divisão temporal → Seleção de defasagens: fornece divisão (evidence: `src/features/lag_evaluation.py`)
- Construção de atributos → Seleção de defasagens: constrói atributos (evidence: `src/features/lag_evaluation.py`)
- Construção de atributos → Previsor direto: gera atributos (evidence: `src/models/ml_direct.py`)
- Construção de atributos → Previsor recursivo: gera atributos (evidence: `src/models/ml_recursive.py`)
- Previsor direto → Previsor recursivo: apoia previsão (evidence: `src/models/ml_recursive.py`)
- Previsor direto → LightGBM direto e recursivo: implementa estratégia (evidence: `src/models/lightgbm_model.py`)
- Previsor recursivo → LightGBM direto e recursivo: implementa variante (evidence: `src/models/lightgbm_model.py`)
- Protocolo de avaliação → Executor de experimentos: define avaliação (evidence: `src/evaluation/runner.py`)
- Baselines → Executor de experimentos: executa experimento (evidence: `src/models/baseline.py`)
- SARIMA → Executor de experimentos: executa experimento (evidence: `src/models/sarima.py`)
- SVR → Executor de experimentos: executa experimento (evidence: `src/models/svr.py`)
- LightGBM direto e recursivo → Executor de experimentos: executa experimento (evidence: `src/models/lightgbm_model.py`)
- Executor de experimentos → Protocolo de avaliação: obtém origens (evidence: `src/evaluation/runner.py`)
- Executor de experimentos → Medição de custo: mede execução (evidence: `src/evaluation/runner.py`)
- Executor de experimentos → Métricas: calcula métricas (evidence: `src/evaluation/runner.py`)
- Executor de experimentos → Registro de experimentos: registra experimento (evidence: `src/evaluation/runner.py`)
- Executor de experimentos → Previsões persistidas: grava previsões (evidence: `src/evaluation/runner.py`)
- Remedição de custos → Baselines: remede modelos (evidence: `src/evaluation/cost_batch.py`)
- Remedição de custos → SARIMA: remede modelos (evidence: `src/evaluation/cost_batch.py`)
- Remedição de custos → SVR: remede modelos (evidence: `src/evaluation/cost_batch.py`)
- Remedição de custos → LightGBM direto e recursivo: remede modelos (evidence: `src/evaluation/cost_batch.py`)
- Registro de experimentos → Consolidação de custos: fornece registros (evidence: `src/evaluation/cost_report.py`)
- Métricas e Diebold–Mariano → Consolidação de custos: compara métricas (evidence: `src/evaluation/cost_report.py`)
- Registro de experimentos → Métricas e Diebold–Mariano: fornece experimentos (evidence: `src/evaluation/metrics_report.py`)
- Métricas → Métricas e Diebold–Mariano: calcula medidas (evidence: `src/evaluation/metrics_report.py`)
- Registro de experimentos → Verificação de estratégia: fornece registros (evidence: `src/evaluation/strategy_check.py`)
- Registro de experimentos → Score composto: fornece experimentos (evidence: `src/evaluation/composite.py`)
- Métricas e Diebold–Mariano → Score composto: fornece métricas (evidence: `src/evaluation/composite.py`)
- Consolidação de custos → Score composto: fornece custos (evidence: `src/evaluation/composite.py`)
- Registro de experimentos → Fronteira de Pareto: fornece experimentos (evidence: `src/evaluation/pareto.py`)
- Consolidação de custos → Fronteira de Pareto: fornece custos (evidence: `src/evaluation/pareto.py`)
- Métricas e Diebold–Mariano → Fronteira de Pareto: fornece métricas (evidence: `src/evaluation/pareto.py`)
- Registro de experimentos → Tabela final: fornece experimentos (evidence: `src/evaluation/consolidate.py`)
- Métricas e Diebold–Mariano → Tabela final: fornece métricas (evidence: `src/evaluation/consolidate.py`)
- Registro de experimentos → Geração de figuras: fornece resultados (evidence: `src/visualization/make_figures.py`)
- Métricas e Diebold–Mariano → Geração de figuras: fornece métricas (evidence: `src/visualization/make_figures.py`)
- Geração de figuras → Gráficos: gera gráficos (evidence: `src/visualization/make_figures.py`)