Quick Start Guide

This guide will help you get started with MarrmotFlow quickly. We’ll walk through a basic example of setting up and running a MARRMOT workflow.

Basic Workflow Example

Here’s a minimal example to get you started:

import geopandas as gpd
from marrmotflow import MARRMOTWorkflow

# Load catchment data
catchments = gpd.read_file("path/to/your/catchments.shp")

# Define forcing variables mapping
forcing_vars = {
    "precip": "precipitation",  # Variable name in your forcing files
    "temp": "temperature"       # Variable name in your forcing files
}

# Define units for forcing variables
forcing_units = {
    "precip": "mm/day",
    "temp": "celsius"
}

# Create a workflow
workflow = MARRMOTWorkflow(
    name="BasicWorkflow",
    cat=catchments,
    forcing_files=["forcing_data.nc"],
    forcing_vars=forcing_vars,
    forcing_units=forcing_units,
    pet_method="penman_monteith",
    model_number=[7, 37]  # HBV-96 and GR4J models
)

Understanding the Components

Catchment Data

MarrmotFlow expects catchment data as a GeoPandas GeoDataFrame or a path to a spatial file (shapefile, GeoJSON, etc.):

# From file
catchments = gpd.read_file("catchments.shp")

# Or pass the file path directly
workflow = MARRMOTWorkflow(
    cat="catchments.shp",
    # ... other parameters
)

Forcing Variables

The forcing_vars dictionary maps the standardized variable names used by MarrmotFlow to the actual variable names in your forcing data files:

forcing_vars = {
    "precip": "your_precipitation_variable_name",
    "temp": "your_temperature_variable_name"
}

Forcing Units

Specify the units of your forcing variables using Pint-compatible unit strings:

forcing_units = {
    "precip": "mm/day",      # or "mm/d", "millimeter/day"
    "temp": "celsius"        # or "degC", "degree_Celsius"
}

Model Selection

MarrmotFlow supports various MARRMOT model structures. You can specify one or multiple models:

# Single model
model_number = 7  # HBV-96

# Multiple models
model_number = [7, 37]  # HBV-96 and GR4J

Common model numbers include:

7: HBV-96
37: GR4J
1: Collie River Basin 1
2: Wetland model

PET Methods

MarrmotFlow supports different methods for calculating potential evapotranspiration:

# Available methods
pet_method = "penman_monteith"  # Default and recommended
pet_method = "hamon"           # Alternative method

Time Zones

You can specify time zones for forcing data and model execution:

workflow = MARRMOTWorkflow(
    # ... other parameters
    forcing_time_zone="UTC",
    model_time_zone="America/Edmonton"
)

Next Steps

Now that you have a basic understanding of MarrmotFlow, you can:

Explore the User Guide for more detailed information
Check out the Examples for more complex scenarios
Review the API Reference for complete API documentation

Common Issues

Import Error: If you encounter import errors, make sure all dependencies are installed:

pip install -e ".[dev]"

File Not Found: Ensure your file paths are correct and files exist:

import os
print(os.path.exists("your_file_path"))

Unit Errors: Make sure your unit strings are valid Pint units:

import pint
ureg = pint.UnitRegistry()
print(ureg.parse_expression("mm/day"))  # Should not raise an error