Core Module

The core module contains the main MarrmotFlow classes and functions.

Core functionality for MarrmotFlow package.

class marrmotflow.core.MARRMOTWorkflow(name: str = 'MARRMOTModels', cat: GeoDataFrame | str | PathLike = None, forcing_vars: Dict[str, str] = {}, forcing_files: Sequence[str | PathLike] | str | PathLike = None, forcing_units: Dict[str, str] = {}, pet_method: str = 'hamon', model_number: Sequence[int] | int = [7, 37], forcing_time_zone: str = None, model_time_zone: str = None)[source]

Bases: object

A class representing a MARRMOT workflow.

__init__(name: str = 'MARRMOTModels', cat: GeoDataFrame | str | PathLike = None, forcing_vars: Dict[str, str] = {}, forcing_files: Sequence[str | PathLike] | str | PathLike = None, forcing_units: Dict[str, str] = {}, pet_method: str = 'hamon', model_number: Sequence[int] | int = [7, 37], forcing_time_zone: str = None, model_time_zone: str = None) → MARRMOTWorkflow[source]

Initialize the MARRMOT workflow with forcing variables, files, units, PET method, and model number.

Parameters:

forcing_vars (Dict[str, str], optional) – Dictionary of forcing variables and their units, by default {}. The mandatory keys to this dictionary are: - ‘precip’: Precipitation variable name - ‘temp’: Temperature variable name The values must be present in the forcing_files.
forcing_files (Sequence[PathLike] | PathLike, optional) – Sequence of paths to forcing files or a single path, by default None
forcing_units (Dict[str, str], optional) – Dictionary of units for the forcing variables, by default {}. The keys must match the keys in forcing_vars, and the values must be valid pint units.
pet_method (str, optional) – Method for calculating potential evapotranspiration, by default “hamon”
model_number (Sequence[int] | int, optional) – Model number(s) to be used in the workflow, by default [7, 37] (HBV-96 and GR4J)

Raises:

ValueError – If forcing files are not provided or are not in the correct format.
TypeError – If forcing files are not a sequence or a PathLike object.

Notes

pet_method only accepts “hamon” as a valid method. Other methods
will be added in the future.

classmethod from_dict(init_dict: Dict = {}) → MARRMOTWorkflow[source]: Constructor to use a dictionary to instantiate

classmethod from_json(json_str: str) → MARRMOTWorkflow[source]: Constructor to use a loaded JSON string

classmethod from_json_file(json_file: str) → MARRMOTWorkflow[source]: Constructor to use a JSON file path

static datetime64_to_matlab_datenum_fast(dt64)[source]: Python’s datetime64 to MATLAB datenum conversion.

run()[source]: Run the workflow.

save(save_path: str | PathLike)[source]: Save the workflow output to a specified path.

init_forcing_files()[source]: Initialize forcing files.

init_pet()[source]: Initialize potential evapotranspiration (PET) calculation.

init_model_file(model_number: Sequence[int] | int) → None[source]: Initialize the model file for the given model number.

MARRMOTWorkflow Class

class marrmotflow.core.MARRMOTWorkflow(name: str = 'MARRMOTModels', cat: GeoDataFrame | str | PathLike = None, forcing_vars: Dict[str, str] = {}, forcing_files: Sequence[str | PathLike] | str | PathLike = None, forcing_units: Dict[str, str] = {}, pet_method: str = 'hamon', model_number: Sequence[int] | int = [7, 37], forcing_time_zone: str = None, model_time_zone: str = None)[source]

Bases: object

A class representing a MARRMOT workflow.

__init__(name: str = 'MARRMOTModels', cat: GeoDataFrame | str | PathLike = None, forcing_vars: Dict[str, str] = {}, forcing_files: Sequence[str | PathLike] | str | PathLike = None, forcing_units: Dict[str, str] = {}, pet_method: str = 'hamon', model_number: Sequence[int] | int = [7, 37], forcing_time_zone: str = None, model_time_zone: str = None) → MARRMOTWorkflow[source]

Initialize the MARRMOT workflow with forcing variables, files, units, PET method, and model number.

Parameters:

forcing_vars (Dict[str, str], optional) – Dictionary of forcing variables and their units, by default {}. The mandatory keys to this dictionary are: - ‘precip’: Precipitation variable name - ‘temp’: Temperature variable name The values must be present in the forcing_files.
forcing_files (Sequence[PathLike] | PathLike, optional) – Sequence of paths to forcing files or a single path, by default None
forcing_units (Dict[str, str], optional) – Dictionary of units for the forcing variables, by default {}. The keys must match the keys in forcing_vars, and the values must be valid pint units.
pet_method (str, optional) – Method for calculating potential evapotranspiration, by default “hamon”
model_number (Sequence[int] | int, optional) – Model number(s) to be used in the workflow, by default [7, 37] (HBV-96 and GR4J)

Raises:

ValueError – If forcing files are not provided or are not in the correct format.
TypeError – If forcing files are not a sequence or a PathLike object.

Notes

pet_method only accepts “hamon” as a valid method. Other methods
will be added in the future.

classmethod from_dict(init_dict: Dict = {}) → MARRMOTWorkflow[source]: Constructor to use a dictionary to instantiate

classmethod from_json(json_str: str) → MARRMOTWorkflow[source]: Constructor to use a loaded JSON string

classmethod from_json_file(json_file: str) → MARRMOTWorkflow[source]: Constructor to use a JSON file path

static datetime64_to_matlab_datenum_fast(dt64)[source]: Python’s datetime64 to MATLAB datenum conversion.

run()[source]: Run the workflow.

save(save_path: str | PathLike)[source]: Save the workflow output to a specified path.

init_forcing_files()[source]: Initialize forcing files.

init_pet()[source]: Initialize potential evapotranspiration (PET) calculation.

init_model_file(model_number: Sequence[int] | int) → None[source]: Initialize the model file for the given model number.

Class Methods

The following methods are available on the MARRMOTWorkflow class:

Parameters

The MARRMOTWorkflow class accepts the following parameters:

MARRMOTWorkflow Parameters
Parameter	Type	Required	Description
name	str	Yes	Name identifier for the workflow
cat	GeoDataFrame or PathLike	Yes	Catchment data as GeoDataFrame or path to spatial file
forcing_vars	Dict[str, str]	Yes	Mapping of standard variable names to data variable names
forcing_files	Sequence[PathLike] or PathLike	No	Path(s) to forcing data files
forcing_units	Dict[str, str]	No	Units for forcing variables (using Pint notation)
pet_method	str	No	PET calculation method (‘penman_monteith’ or ‘hamon’)
model_number	Sequence[int] or int	No	MARRMOT model number(s) to use (default: [7, 37])
forcing_time_zone	str	No	Time zone of forcing data
model_time_zone	str	No	Time zone for model execution

Examples

Basic workflow creation:

from marrmotflow import MARRMOTWorkflow
import geopandas as gpd

# Load catchment data
catchments = gpd.read_file("catchments.shp")

# Create workflow
workflow = MARRMOTWorkflow(
    name="BasicWorkflow",
    cat=catchments,
    forcing_files=["climate_data.nc"],
    forcing_vars={"precip": "precipitation", "temp": "temperature"},
    forcing_units={"precip": "mm/day", "temp": "celsius"},
    model_number=[7, 37]
)

Advanced workflow with multiple models:

workflow = MARRMOTWorkflow(
    name="MultiModelAnalysis",
    cat="large_watershed.shp",
    forcing_files=[
        "precip_2010_2020.nc",
        "temp_2010_2020.nc"
    ],
    forcing_vars={
        "precip": "total_precipitation",
        "temp": "2m_temperature"
    },
    forcing_units={
        "precip": "m/day",
        "temp": "kelvin"
    },
    pet_method="penman_monteith",
    model_number=[7, 37, 1, 2],
    forcing_time_zone="UTC",
    model_time_zone="America/Edmonton"
)

Error Handling

The MARRMOTWorkflow class raises the following exceptions:

exception marrmotflow.core.ValueError

Raised when required parameters are missing or invalid:

Missing catchment data
Invalid forcing variable mapping
Unsupported PET method
Invalid model numbers

exception marrmotflow.core.TypeError

Raised when parameter types are incorrect:

Catchment data is not a GeoDataFrame or PathLike
Forcing files are not in expected format

exception marrmotflow.core.FileNotFoundError

Raised when specified files cannot be found:

Catchment file does not exist
Forcing data files cannot be accessed

Type Definitions

The core module defines the following types:

marrmotflow.core.PathLike: Type alias for file paths, supporting both string and os.PathLike objects. alias of str | PathLike

alias of str | PathLike