How to use ChatGPT to learn Hydrology - Part III: vibe coding, hydroTSM and reproducible practical projects

Sun, 16 Aug 2026 00:00:00 +0000

Estimated reading and practice time: 20-25 minutes.

This tutorial starts from an explicit assumption: you already know how to program in R. The objective is therefore not to review vectors, data.frame objects, functions or loops, but to learn how to use AI to accelerate hydrological analysis while retaining technical control over data, methods, code, results and interpretation.

In IIO422, practical work must be reproducible and every student must be able to understand and modify the procedures used.

We will therefore use a controlled vibe-coding approach.

1. What vibe coding means in this course

It does not mean:

Do the practical assignment in R.

It means working iteratively:

hydrological question
→ specification
→ proposed code
→ execution and testing
→ audit
→ interpretation
→ modification

AI acts as a copilot. You decide what problem should be solved, whether the data are valid, which method is appropriate and whether the result is hydrologically plausible.

2. The practical component is one final project divided into TP-01 and TP-02

For assessment:

Practical = 0.45 × TP-01 + 0.55 × TP-02

Each TP combines:

35% Reproducible Hydrological Project - team
15% Technical Evidence Dossier - team
30% Hydrological Defence - individual
20% Supervised Practical Challenge - individual

The implication is direct: a script produced by ChatGPT may improve the team submission while simultaneously reducing your individual mark if you cannot explain it.

3. Map of practical competences

The practical work combines:

hydrometeorological time-series analysis;
catchment characterisation;
water balance;
Budyko;
probabilistic methods;
extreme events;
hydrological design;
hydrological simulation;
reproducibility;
interpretation for water management and infrastructure safety.

4. TP-01: hydrological processes and annual water balance

The syllabus specifies that TP-01 includes, among other elements:

physical and hydroclimatic catchment characterisation;
catchment delineation and geomorphological analysis;
collection and basic quality control of hydrometeorological information;
analysis of precipitation, temperature, evapotranspiration and streamflow;
water-balance estimation;
application of the Budyko framework;
analysis of water supply and demand;
simplified hydrological modelling;
interpretation from a water-resources management perspective.

Starting prompt for TP-01

Act as a hydrological reviewer for TP-01.

Do not write code yet.

Help me turn the overall objective into verifiable questions:
1. What are the physical characteristics of the catchment?
2. What is its hydroclimatic regime?
3. What data do I need?
4. How will I check data quality?
5. How will I close the water balance?
6. How will I use Budyko?
7. What can I conclude about water supply and demand?
8. What uncertainty must I report?

5. Use base R + hydroTSM for time series

hydroTSM is appropriate for manipulating, aggregating, analysing and visualising hydrological time series.

library(zoo)
library(hydroTSM)

Potentially useful functions include:

hydroTSM::daily2monthly()
hydroTSM::daily2annual()
hydroTSM::monthlyfunction()
hydroTSM::annualfunction()
hydroTSM::fdc()
hydroTSM::hydroplot()
hydroTSM::plot_pq()
hydroTSM::climograph()

Do not use a function simply because ChatGPT suggested it.

Verify that the function exists.

Explain:
- input;
- output;
- units;
- handling of NA;
- temporal assumptions;
- a reasonable base-R alternative.

6. Initial data audit

Before analysis:

I have daily P, T, ET and Q series.

Design an audit covering:
- temporal coverage;
- regularity;
- NA;
- duplicates;
- units;
- physically impossible values;
- changes in station or source;
- temporal consistency among variables.

The quality of the analysis depends on this stage.

7. Temporal aggregation: think before coding

P and Q do not necessarily use the same aggregation operator.

I have:
daily P in mm/day
daily mean Q in m3/s
catchment area in km2

Before writing code, make me derive how to obtain:
- monthly P;
- monthly mean Q;
- monthly volume;
- monthly equivalent runoff depth in mm.

You should be able to reconstruct the conversion dimensionally.

8. Budyko and annual water balance

TP-01 explicitly requires the Budyko framework.

I have annual P, ET/PET and Q.

Help me build a Budyko diagnostic.

Before coding:
1. check units;
2. define the dimensionless indices;
3. ask what each axis means;
4. identify potentially anomalous years;
5. separate physical interpretation from possible data error.

9. Simplified hydrological modelling and airGRteaching

The syllabus includes simplified models for annual water-balance analysis and lists airGRteaching as a course resource.

A useful introduction is to work with a daily model and then analyse the outputs at annual scale.

A typical workflow is:

PREP <- airGRteaching::PrepGR(
 ObsDF = BasinObs,
 HydroModel = "GR4J",
 CemaNeige = FALSE
)

CAL <- airGRteaching::CalGR(
 PrepGR = PREP,
 CalCrit = "KGE2",
 CalPer = c("1990-01-01", "1994-12-31")
)

SIM <- airGRteaching::SimGR(
 PrepGR = PREP,
 Param = CAL,
 EffCrit = "KGE2",
 SimPer = c("1995-01-01", "1999-12-31")
)

Do not memorise these calls. You should understand:

input data;
units;
warm-up period;
calibration;
simulation;
efficiency criterion;
parameters;
water balance;
the difference between statistical fit and hydrological realism.

Controlled vibe coding with airGRteaching

I am using GR4J with airGRteaching.

Work step by step:
1. review format and units;
2. check periods;
3. generate only PrepGR;
4. wait for me to execute it;
5. interpret the output;
6. only then generate CalGR;
7. make me explain the criterion;
8. continue with SimGR;
9. finish with a defence question.

10. TP-02: frequency analysis and hydrological extremes

The syllabus states that TP-02 includes:

exploratory analysis of maximum-value series;
selection and fitting of probability distributions;
parameter estimation;
goodness-of-fit analysis;
estimation of rainfall and streamflow for different return periods;
analysis of record-length effects;
uncertainty evaluation;
simulation of a flood event with HEC-HMS;
comparison of observed and simulated streamflow;
implications for design and infrastructure safety.

Use this list directly as your work plan.

11. Exploratory analysis and descriptive statistics

Before fitting a distribution:

Do not fit anything yet.

Design an EDA for annual maxima:
- coverage;
- outliers;
- visual trend;
- descriptive parameters;
- skewness;
- independence;
- sample size;
- recommended plots.

Do not use a fitted distribution to conceal a poorly reviewed series.

12. Probabilistic treatment

You should be able to explain:

sample;
random variable;
distribution function;
exceedance;
non-exceedance;
quantiles;
return period;
statistical parameters.

Make me explain F(x), 1-F(x), T and a quantile
without equations first.

Then translate the reasoning into R.

13. Fitting probability distributions

Do not ask:

Which distribution is best?

Ask:

I have annual maxima.

Make me define:
- candidate distributions;
- estimation method;
- support;
- graphical diagnostics;
- goodness of fit;
- tail behaviour;
- extrapolation uncertainty.

Then request code in small blocks.

14. Effect of record length

This is an explicit component of TP-02.

I have 40 years of annual maxima.

Design an experiment comparing estimates from 15, 25 and 40 years.

Before coding:
- define what remains fixed;
- define what metric will be compared;
- decide how uncertainty will be shown;
- identify what conclusions cannot be generalised.

15. Return period and risk

I want to estimate a T-year event.

Before using a q*() function:
make me derive the correct non-exceedance probability
for the quantile function I am using.

For risk:

Make me derive the probability of at least one exceedance
during n years of service life.

Do not give me the formula initially.

16. Intensities, IDF curves and design hyetographs

I have an IDF table.

Help me construct a design hyetograph.

Before coding:
1. define T;
2. define duration;
3. define time step;
4. choose a temporal pattern;
5. check conservation of total rainfall depth;
6. explain which assumption controls the temporal distribution.

17. SCS-CN

Let us implement SCS-CN.

First define:
- P;
- CN;
- potential maximum retention;
- initial abstraction;
- effective rainfall.

Then generate a simple R function.
Include unit checks and limiting cases.

If the code runs but you cannot explain what changes when CN changes, you do not yet understand the method.

18. HEC-HMS flood simulation

TP-02 explicitly includes a flood simulation using HEC-HMS.

ChatGPT can help you:

review model structure;
interpret parameters;
document scenarios;
diagnose results;
compare observed and simulated streamflow.

But it should not invent parameter values.

I am configuring HEC-HMS.

Do not propose parameter values yet.

Make me review:
- catchment;
- loss method;
- transform method;
- baseflow;
- routing, where relevant;
- design storm;
- time step;
- initial conditions;
- simulation period.

19. Compare observed and simulated flow critically

Do not reduce evaluation to a single metric.

I have Qobs and Qsim.

Design an evaluation including:
- hydrograph;
- peak;
- peak timing;
- volume;
- bias;
- one global performance metric;
- an error that matters for infrastructure safety.

20. Error diagnosis: a core competence

The course deliberately incorporates incorrect results, plots, code or methods.

Practise like this:

Generate an R block for frequency analysis
with exactly two plausible errors.

Do not identify them.

I must:
1. detect them;
2. explain the hydrological consequence;
3. correct them;
4. compare the result.

21. Reproducibility

A suggested structure is:

TP/
├── README.md
├── data/
│ ├── raw/
│ └── processed/
├── R/
│ ├── 01_qc.R
│ ├── 02_tp01_hydroclimate.R
│ ├── 03_budyko_balance.R
│ ├── 04_frequency.R
│ ├── 05_design_event.R
│ └── 06_outputs.R
├── models/
├── output/
│ ├── figures/
│ └── tables/
└── evidence/

The team should provide data, metadata, scripts, parameters, configuration files and everything else required to regenerate the results.

22. Use ChatGPT as a reproducibility auditor

Act as a reproducibility auditor.

Look for:
- absolute paths;
- undeclared dependencies;
- manually created objects;
- scripts run out of order;
- hidden parameters;
- inconsistent units;
- non-reproducible outputs;
- non-existent functions;
- undocumented steps.

23. Technical Evidence Dossier

The dossier replaces the traditional long written report.

A useful evidence chain is:

question
→ method
→ result
→ evidence
→ interpretation
→ uncertainty
→ limitation

Do not fill space with generic definitions.

24. Prepare for the Hydrological Defence

I will give you the complete project.

Ask random questions about:
- catchment delineation;
- data;
- QC;
- water balance;
- Budyko;
- hydroTSM;
- frequency analysis;
- distributions;
- T;
- uncertainty;
- IDF;
- SCS-CN;
- HEC-HMS;
- modelling;
- results;
- limitations.

Ask one question at a time.

Every team member should understand the complete project.

25. Prepare for the Supervised Practical Challenge

The individual challenge lasts approximately 30-45 minutes and has three parts:

conceptual diagnosis;
technical solution;
hydrological interpretation.

Generate a 35-minute individual challenge.

Use a small dataset.
Include:
A. conceptual diagnosis;
B. an R task;
C. hydrological interpretation.

Insert one plausible error.
Do not use tidyverse.

26. The modification rule

After any AI-generated code:

Now make me modify it for:
- another period;
- another unit;
- another treatment of NA;
- another T;
- another distribution;
- another hydrological assumption.

If you cannot modify it, you are not ready to defend it.

27. Declare AI use

Each TP should identify:

tool;
purpose;
component;
verification.

For example:

Tool: ChatGPT.
Purpose: debugging a function that converts Q to mm.
Component: 03_budyko_balance.R.
Verification: independent dimensional derivation,
known-value test case and comparison with a manual calculation.

28. Master prompt for the practical project

Act as a tutor in R programming and Hydrology.

I already know R.
Do not use tidyverse.
Prefer base R and hydroTSM.
Where relevant, consider airGRteaching and HEC-HMS.

Do not be the author of the project.

Rules:
1. start with the hydrological question;
2. separate data, method and assumptions;
3. provide code in small blocks;
4. do not invent data or functions;
5. require units;
6. include checks;
7. make me execute before continuing;
8. require interpretation;
9. make me modify the code;
10. finish with a defence question.

29. Final competence

By the end of the course, you should be able to:

audit hydrometeorological series;
characterise a catchment;
analyse P, T, ET and Q;
quantify a water balance;
interpret Budyko;
analyse water supply and demand;
use a simplified hydrological model;
construct and interpret an FDC;
perform frequency analysis;
fit and compare probability distributions;
estimate design events;
evaluate uncertainty and record-length effects;
construct design storms;
apply SCS-CN;
configure and review a simulation in HEC-HMS;
compare observed and simulated streamflow;
reproduce the full workflow;
defend the decisions made.

If ChatGPT helps you develop these capacities, vibe coding is functioning as assisted learning.

If it merely produces a script that “runs”, it is hiding what you still do not know.

Sources and documentation

IIO422-Hydrology course syllabus, Universidad de La Frontera, 2026.

Academic integrity: AI is permitted as support for learning and practical-project preparation, but not during assessments. Any AI-generated content remains the student’s responsibility and must be verifiable, reproducible and defensible.

HEC-HMS | Dr. Mauricio Zambrano-Bigiarini