Module 0: Introduction & Prerequisites

Introduction & Prerequisites¶

Welcome! This tutorial series is designed specifically for water professionals—hydrologists, hydraulic engineers, and groundwater modellers—who want to learn Python for their work.

Time required: 10 minutes
Prerequisites: None—start here!

Why Python for Water Modelling?¶

The Current Reality¶

If you’re a water modeller, you probably use:

• Excel for data processing and simple calculations

• Specialized software (HEC-RAS, MIKE, MODFLOW GUI, SWMM, etc.)

• Copy-paste workflows to move data between tools

• Manual processes that need to be repeated for each new dataset

This works... until:

• You need to process data from 50 stations instead of 5

• You want to rerun last year’s analysis with updated data

• A colleague asks “how did you do that calculation?”

• You need to document your workflow for a report

• The data format changes slightly

The Python Advantage¶

Python doesn’t replace your specialized software—it enhances your workflow:

Real-World Examples¶

Hydrology:

• Automated flow statistics for multiple gauging stations

• Rainfall-runoff analysis and visualization

• Flood frequency analysis with uncertainty quantification

• Time series gap-filling and quality control

Groundwater:

• Pre/post-processing for MODFLOW models with FloPy

• Automated calibration workflows

• Pumping test analysis and visualization

• Piezometric surface mapping

Hydraulics:

• Rating curve development and validation

• Stage-discharge relationship analysis

• Sediment transport calculations

• Automated report generation

What You’ll Learn in This Series¶

This tutorial series takes you from zero programming experience to writing useful Python scripts for water modelling.

Learning Path¶

Module 0: Introduction (you are here)
    ↓
Module 1a: Installing VS Code
    ↓
Module 1b: Python Extension Setup
    ↓
Module 2a: Understanding Environment Management
    ↓
Module 2b: Installing & Using uv
    ↓
Module 3a: Python Basics for Water Modellers
    ↓
Module 3b: AI-Assisted Coding
    ↓
Module 4a: Getting Hydrological Data
    ↓
Module 4b: Discharge Analysis
    ↓
Module 5: Resources & Next Steps

By the End, You Will Be Able To:¶

✅ Set up a professional Python development environment
✅ Load and process hydrological data (CSV, Excel)
✅ Calculate statistics and analyze time series
✅ Create publication-quality plots and charts
✅ Write reproducible analysis scripts
✅ Use AI assistants to help write and debug code
✅ Find and use Python packages for water modelling (FloPy, pandas, etc.)
✅ Continue learning independently

What We WON’T Cover¶

This is a beginner’s guide. We won’t cover:

• Advanced programming concepts (classes, decorators, etc.)

• Software engineering best practices

• Complex statistical methods

• Building web applications

• Machine learning / AI modelling

Good news: Once you complete this series, you’ll have the foundation to learn those topics if needed!

Essential Terminology (Glossary)¶

Before we start, let’s define some terms you’ll encounter. Don’t worry if these don’t fully make sense yet—they will as you work through the tutorials.

Development Tools¶

Python Concepts¶

Environment Management¶

File Types You’ll See¶

Common Abbreviations¶

• CSV = Comma-Separated Values (spreadsheet format)

• API = Application Programming Interface (how programs talk to each other)

• CLI = Command-Line Interface (using the terminal)

• GUI = Graphical User Interface (clicking buttons)

• IDE = Integrated Development Environment (VS Code)

Don’t memorize these! Just refer back to this section when you encounter unfamiliar terms.

What “Success” Looks Like¶

By the time you complete these tutorials, here’s a realistic example of what you’ll be able to do:

Example Workflow: Analyzing Discharge Data¶

Your task: Analyze daily discharge data from a Swiss river station.

What you’ll write (about 30 lines of code):

import pandas as pd
import matplotlib.pyplot as plt

# Load data
df = pd.read_csv('aare_discharge.csv')
df['date'] = pd.to_datetime(df['date'])
df = df.set_index('date')

# Calculate statistics
Q_mean = df['discharge_m3s'].mean()
Q_max = df['discharge_m3s'].max()
Q_90 = df['discharge_m3s'].quantile(0.90)

print(f"Mean discharge: {Q_mean:.2f} m³/s")
print(f"Maximum discharge: {Q_max:.2f} m³/s")
print(f"Q90 (high flow): {Q_90:.2f} m³/s")

# Create hydrograph
plt.figure(figsize=(12, 4))
plt.plot(df.index, df['discharge_m3s'])
plt.ylabel('Discharge (m³/s)')
plt.title('Aare River - Daily Discharge')
plt.savefig('hydrograph.png', dpi=300)

What this does:

• Loads discharge data from a CSV file

• Calculates mean, maximum, and 90th percentile flows

• Creates a professional hydrograph

• Saves it as a high-resolution image

Time to write: 5 minutes (once you know the basics)
Time to run: 1 second
Time to rerun with new data: 1 second (just change the filename!)

You’ll Also Be Able To:¶

• Ask an AI assistant: “Add monthly statistics to this script” → Get working code

• Modify the script to process 100 stations instead of 1

• Create subplots showing different aspects of the data

• Handle missing values and data quality issues

• Export results to Excel for reports

• Share your script with colleagues who can reproduce your exact results

This isn’t years of study—it’s hours of learning to unlock these capabilities.

Learning Approach: Modern Tools¶

This tutorial series uses modern tools that make learning Python much easier than it used to be.

🤖 AI-Assisted Learning¶

Traditional approach: Spend hours searching Stack Overflow, reading documentation, debugging errors.

Modern approach: Use AI assistants (ChatGPT, Claude) to:

• Generate code from plain language descriptions

• Explain what existing code does

• Debug errors and suggest fixes

• Learn as you go

Example conversation with AI:

You: "Write Python code to calculate the mean of a column called 'discharge' in a CSV file"

AI: [provides working code with explanations]

You: "Now add a plot showing discharge over time"

AI: [adds plotting code]

You: "I got an error: KeyError 'discharge'"

AI: [explains the error and how to fix it]

We’ll teach you how to use AI effectively in Module 3b.

📦 Modern Package Management (uv)¶

Traditional approach:

• Manually download and install Python

• Use pip to install packages (slow)

• Manage virtual environments manually

• Deal with version conflicts

Modern approach with uv:

• One command installs everything

• Automatically manages environments

• Lightning fast (written in Rust, a high-performance programming language)

• Just works™

We’ll set this up in Module 2.

🎯 Focus on Practical Skills¶

We skip theory that doesn’t help you get work done. Instead:

✅ Learn by doing with real hydrological data
✅ Copy-paste-modify working examples
✅ Ask AI when you don’t understand something
✅ Build real tools you’ll actually use

You don’t need to become a computer scientist—you need to analyze water data efficiently.

Prerequisites & Requirements¶

What You Need¶

Required:

• ✅ A computer (Windows, Mac, or Linux)

• ✅ Internet connection (for downloading tools and packages)

• ✅ About 4 hours total time (spread across modules)

• ✅ Basic computer skills (can install software, navigate folders)

NOT Required:

• ❌ Prior programming experience

• ❌ Math beyond high school level

• ❌ Computer science background

• ❌ Expensive software licenses

Everything we use is FREE and open-source.

System Requirements¶

• Disk Space: ~2 GB (for Python, packages, and VS Code)

• OS: Windows 10+, macOS 10.13+, or modern Linux

• RAM: 4 GB minimum (8 GB recommended)

Time Commitment¶

You can pause and resume at any time—each module is self-contained.

Learning Style¶

This series assumes you:

• Learn best by doing rather than reading theory

• Want to see real examples with water data

• Prefer step-by-step guidance with screenshots

• Need explanations in plain language (no jargon)

• Will use AI assistants to fill knowledge gaps

If you prefer comprehensive computer science education, we’ll link to those resources in Module 5.

Frequently Asked Questions¶

“I’ve never programmed before. Is this really for me?”¶

Yes! This series is designed for complete beginners. We:

• Explain everything in plain language

• Use water modelling examples you understand

• Provide step-by-step instructions

• Show you how to use AI when you get stuck

If you can use Excel, you can learn Python.

“Won’t AI replace programmers? Why learn Python?”¶

AI is a tool that helps you code, not a replacement for understanding:

• You need to know what to ask for

• You need to verify the results make sense

• You need to adapt code to your specific needs

• You need to debug when things go wrong

Think of it this way: Calculators exist, but you still need to know what calculation to do.

“I tried learning Python before and gave up. What’s different?”¶

Common reasons people quit:

• ❌ Generic tutorials not relevant to their work

• ❌ Spent hours on setup before writing any code

• ❌ Got stuck on errors with no help

• ❌ Didn’t see practical value

What’s different here:

• ✅ Water modelling focus from day 1

• ✅ Modern tools (uv) make setup easy

• ✅ AI assistants help when you’re stuck

• ✅ Real examples you can use tomorrow

“How is this different from other Python tutorials?”¶

“Do I need to learn everything about Python?”¶

No! You only need a small subset:

• Reading CSV/Excel files

• Basic data manipulation (pandas)

• Creating plots (matplotlib)

• Writing simple scripts

That’s maybe 10% of Python, but it’s 90% of what you’ll use for water modelling.

“What if I get stuck?”¶

Multiple support options:

1. AI assistants (ChatGPT, Claude) - first line of help

2. Troubleshooting sections in each tutorial

3. Stack Overflow - search or ask questions

4. Python communities - links in Module 5

Getting stuck is part of learning. The difference now: AI can unstick you in seconds.

Ready to Start?¶

You’ve completed the introduction! You now understand:

✅ Why Python is valuable for water modelling
✅ What you’ll learn in this series
✅ Essential terminology you’ll encounter
✅ What success looks like
✅ The modern tools and approach we’ll use
✅ Prerequisites and time commitment

Next Steps¶

Option 1: Continue Immediately
→ Module 1a: Installing VS Code

Option 2: Bookmark and Return Later
Save this link and come back when you have 20 minutes for the first installation module.

Quick Start Checklist¶

Before starting Module 1a, make sure you have:

• A computer with admin rights (to install software)

• Internet connection

• 20 minutes of uninterrupted time

• Permission to install software (if work computer, check with IT)

Questions?¶

If you’re unsure about anything before starting:

• Re-read the FAQ section above

• Check the prerequisites section

• Ask an AI assistant: “I’m about to start learning Python for water modelling. What should I know?”

Ready? Let’s install VS Code! → Module 1a: Installing VS Code