From 6edb6bc4d3b8388edf01e705087971f59da6af1b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 12 Jul 2026 21:43:43 +0000 Subject: [PATCH 1/2] Address review suggestions for equation docs and method counts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update alternative method count from 15 to 18 in methodology and README - Document Jensen-Heise lack of temperature clamp in equations and methodology - Fix PT spelling: Calibracao -> Calibração in et0_methods.md - Remove duplicate completed entry in tasks/todo.md Co-authored-by: Bruno --- README.md | 8 ++++---- docs/equations/et0_methods.md | 6 ++++-- docs/methodology.md | 5 ++++- tasks/todo.md | 2 -- 4 files changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7dcbbb1..79239d0 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ [![Results](https://img.shields.io/badge/results-summary_rankings.csv-informational.svg)](outputs/tables/summary_rankings.csv) [![Contact](https://img.shields.io/badge/contact-GitHub%20Issues-lightgrey.svg)](https://github.com/brunomartinsmv/eto-methods-comparison/issues) -**A reproducible analysis framework for comparing up to 15 empirical and semi-empirical ET0 estimation methods against Penman-Monteith (FAO-56).** +**A reproducible analysis framework for comparing up to 18 empirical and semi-empirical ET0 estimation methods against Penman-Monteith (FAO-56).** This repository is organized as an open, citable research compendium. The current stage includes the executable ETo pipeline, method rankings, uncertainty/sensitivity diagnostics, data-quality reports, optional PCA of meteorological drivers, tests, citation metadata, licensing, contribution guidance, and documentation for reproducing the analysis. ## Key Findings -This repository now configures **15 alternative ET0 methods plus Penman-Monteith FAO-56 as reference**. The current demonstration workflow runs end to end for two contrasting Brazilian climates: +This repository now configures **18 alternative ET0 methods plus Penman-Monteith FAO-56 as reference**. The current demonstration workflow runs end to end for two contrasting Brazilian climates: - **Piracicaba, SP** (Cwa — humid subtropical with dry winter) - **Manaus, AM** (Af — tropical rainforest) @@ -352,7 +352,7 @@ The pipeline is designed for **any location** with meteorological data. Here's h ### Required Meteorological Variables -To compute the full configured set of 15 ET0 methods, you generally need daily data for: +To compute the full configured set of 18 alternative ET0 methods, you generally need daily data for: **Minimum requirements (for basic methods):** - Date @@ -528,7 +528,7 @@ The repository also includes [`CITATION.cff`](CITATION.cff), which GitHub can us ## Methods Overview -The repository configuration targets **15 alternative ET0 estimation methods** plus **Penman-Monteith FAO-56** as the reference. The `compute-eto` command calculates those methods from standardized meteorological variables and writes daily calculated series to `outputs/results/{site}_daily_eto.csv`. +The repository configuration targets **18 alternative ET0 estimation methods** plus **Penman-Monteith FAO-56** as the reference. The `compute-eto` command calculates those methods from standardized meteorological variables and writes daily calculated series to `outputs/results/{site}_daily_eto.csv`. **Reference standard:** - **Penman-Monteith (FAO-56)** — Energy balance + aerodynamic approach, requires full met data diff --git a/docs/equations/et0_methods.md b/docs/equations/et0_methods.md index 0393a9b..d849af9 100644 --- a/docs/equations/et0_methods.md +++ b/docs/equations/et0_methods.md @@ -174,7 +174,7 @@ Mesma forma do Hargreaves-Samani original, com coeficiente \(c_{local}\) ajustad $$\mathrm{ET_0} = c_{local} \cdot \frac{R_a}{\lambda} \cdot (T_{max} - T_{min})^{0{,}5} \cdot (T_{mean} + 17{,}8)$$ -### Calibracao +### Calibração O valor de \(c_{local}\) provém da planilha legada e não é refitado pelo comando `calibrate` (que opera sobre `et_hargreaves_samani`, não sobre a coluna corrigida). Ver [`../methodological_assumptions.md`](../methodological_assumptions.md). @@ -360,7 +360,9 @@ com \(C_T = 0{,}025\) e \(T_x = 3\) °C (padrões). ### Derivação -Forma linear em \(T\) condicionada a \(R_s\): a evapotranspiração só responde quando \(T_{mean} > T_x\), refletindo limiar de atividade evaporativa. +Forma linear em \(T\) condicionada a \(R_s\), com limiar \(T_x\) de atividade evaporativa. + +**Nota de implementação:** a função `jensen_heise` em `scripts/eto_methods.py` avalia \((T_{mean} - T_x)\) sem clamp; valores negativos de ET₀ são possíveis quando \(T_{mean} < T_x\). A formula acima descreve a forma empírica, não um truncamento no código. --- diff --git a/docs/methodology.md b/docs/methodology.md index 5c42b85..c5ed826 100644 --- a/docs/methodology.md +++ b/docs/methodology.md @@ -8,7 +8,7 @@ Para **derivações LaTeX completas** de cada método e das variáveis meteorol ## Escopo configurado dos metodos -O repositorio agora configura 15 metodos alternativos de ET0 e usa Penman-Monteith FAO-56 como referencia. Manaus e Piracicaba sao localidades demonstrativas configuradas em `configs/sites.yml`; o projeto nao esta limitado a essas cidades. Novas localidades podem ser adicionadas por configuracao e por dados de entrada compatíveis. +O repositorio agora configura 18 metodos alternativos de ET0 e usa Penman-Monteith FAO-56 como referencia. Manaus e Piracicaba sao localidades demonstrativas configuradas em `configs/sites.yml`; o projeto nao esta limitado a essas cidades. Novas localidades podem ser adicionadas por configuracao e por dados de entrada compatíveis. O comando `compute-eto` calcula os metodos com `status: computed` a partir de variaveis meteorologicas padronizadas em `data/cleaned/` e escreve `outputs/results/{site}_daily_eto.csv`. Metodos com `status: precomputed_only` sao preservados da planilha quando presentes no input limpo. As metricas preferem essas series calculadas quando o arquivo existe; caso contrario, usam as colunas `et_*` pre-calculadas dos dados limpos como fallback historico. @@ -305,6 +305,9 @@ $$\mathrm{ETo} = \frac{R_s}{\lambda}\,0{,}025\,(T_{mean} - 3)$$ **Requisitos de dados** Temperatura media e radiacao global. +**Nota de implementacao** +A implementacao em `scripts/eto_methods.py` nao aplica clamp em \(T_{mean} - T_x\); quando \(T_{mean} < T_x\), o resultado pode ser negativo. Ver [`equations/et0_methods.md`](equations/et0_methods.md). + --- ## 15. Net Radiation diff --git a/tasks/todo.md b/tasks/todo.md index 3003363..62ddb3d 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -21,8 +21,6 @@ - [x] Cleaning gap limits and long-gap warnings (`clean --max-gap`) - [x] Full LaTeX equation derivations per method (`docs/equations/`) -- [x] Expand equation documentation with full LaTeX derivations per method (`docs/equations/`) - ## Deferred - Implement Thornthwaite-family methods in Python (currently `precomputed_only`) From 7de4c0ccf5886377f71a16bd254ffad864d34f22 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 12 Jul 2026 21:50:20 +0000 Subject: [PATCH 2/2] docs: clarify compute-eto covers 15 computed methods, not all 18 configured Co-authored-by: Bruno --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 79239d0..01b85d0 100644 --- a/README.md +++ b/README.md @@ -528,7 +528,7 @@ The repository also includes [`CITATION.cff`](CITATION.cff), which GitHub can us ## Methods Overview -The repository configuration targets **18 alternative ET0 estimation methods** plus **Penman-Monteith FAO-56** as the reference. The `compute-eto` command calculates those methods from standardized meteorological variables and writes daily calculated series to `outputs/results/{site}_daily_eto.csv`. +The repository configuration targets **18 alternative ET0 estimation methods** plus **Penman-Monteith FAO-56** as the reference. The `compute-eto` command calculates the **15 methods with `status: computed`** from standardized meteorological variables and writes daily calculated series to `outputs/results/{site}_daily_eto.csv`. **Reference standard:** - **Penman-Monteith (FAO-56)** — Energy balance + aerodynamic approach, requires full met data