mhm-tools 0.2__py3-none-any.whl

mhm_tools/__init__.py

@@ -0,0 +1,31 @@
+"""Tools to pre- and post-process data for and from mHM.
+
+.. toctree::
+   :hidden:
+
+   self
+
+Subpackages
+===========
+
+Built-in processing and tool functions.
+
+.. autosummary::
+   :toctree: api
+   :caption: Subpackages
+
+   common
+   post
+   pre
+"""
+
+try:
+    from ._version import __version__
+except ModuleNotFoundError:  # pragma: no cover
+    # package is not installed
+    __version__ = "not_available"
+
+from . import common, post, pre
+
+__all__ = ["__version__"]
+__all__ += ["common", "post", "pre"]

mhm_tools/_cli/_2d_map.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""
+Compute and plot a 2D map for a given NetCDF dataset.
+
+This CLI reads a CF-compliant NetCDF file, extracts a specified variable, and
+invokes mhm_tools.common.plotter.plot_map to generate and save a geo-aware
+2D map plot with customizable labels, colormap, and spatial or data limits.
+
+Authors
+-------
+- Jeisson Leal
+"""
+
+import argparse
+from pathlib import Path
+
+import xarray as xr
+
+
+def str2float(value):
+    """Convert a string to float, but let None remain None."""
+    if value is None or (isinstance(value, str) and value.lower() == "none"):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError) as err:
+        msg = f"{value!r} is not a valid float."
+        raise argparse.ArgumentTypeError(msg) from err
+
+
+def add_args(parser: argparse.ArgumentParser):
+    """Add CLI arguments for the 2d_map subcommand."""
+    parser.description = (
+        "Compute and plot a 2D spatial map for a specified variable from a NetCDF file."
+    )
+    parser.epilog = (
+        "Example:\n"
+        "mhm-tools 2d_map \\\n"
+        "--input-file /path/to/data.nc \\\n"
+        "--var temperature \\\n"
+        "--colorbar-label 'Temp (°C)' \\\n"
+        "--title 'Surface Temperature' \\\n"
+        "--x-min -10 --x-max 30 --y-min 40 --y-max 70 \\\n"
+        "--cmap viridis --vmin -5 --vmax 5 \\\n"
+        "-o /out/dir --output-file_png map.png"
+    )
+
+    # required arguments
+    req = parser.add_argument_group("required arguments")
+    req.add_argument(
+        "--input-file", required=True, help="Path to the input NetCDF file"
+    )
+    req.add_argument(
+        "--var", required=True, help="Variable name in the NetCDF dataset to plot"
+    )
+    req.add_argument(
+        "-o",
+        "--output-dir",
+        required=True,
+        help="Directory where the output PNG will be saved",
+    )
+    req.add_argument(
+        "--output-file-png", required=True, help="Filename for the output PNG"
+    )
+
+    # optional arguments
+    optional = parser.add_argument_group("optional arguments")
+    optional.add_argument("--colorbar-label", default="", help="Label for the colorbar")
+    optional.add_argument("--title", default="", help="Title for the plot")
+    optional.add_argument(
+        "--x-min", type=str2float, default=None, help="Minimum longitude to display"
+    )
+    optional.add_argument(
+        "--x-max", type=str2float, default=None, help="Maximum longitude to display"
+    )
+    optional.add_argument(
+        "--y-min", type=str2float, default=None, help="Minimum latitude to display"
+    )
+    optional.add_argument(
+        "--y-max", type=str2float, default=None, help="Maximum latitude to display"
+    )
+    optional.add_argument(
+        "--cmap", default="RdBu_r", help="Matplotlib colormap name to use"
+    )
+    optional.add_argument(
+        "--vmin", type=str2float, default=None, help="Minimum data value for colormap"
+    )
+    optional.add_argument(
+        "--vmax", type=str2float, default=None, help="Maximum data value for colormap"
+    )
+
+
+def run(args: argparse.Namespace):
+    """Entry point: read NetCDF, extract data array, and call plot_map."""
+    # Load dataset and variable
+    ds = xr.open_dataset(args.input_file)
+    data = ds[args.var]
+
+    # Build output path
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    out_path = output_dir / args.output_file_png
+
+    # Call the plotting utility
+    from mhm_tools.common.plotter import plot_map
+
+    plot_map(
+        data=data,
+        cb_label=args.colorbar_label,
+        title=args.title,
+        out_path=out_path,
+        cmap=args.cmap,
+        x_min=args.x_min,
+        x_max=args.x_max,
+        y_min=args.y_min,
+        y_max=args.y_max,
+        vmin=args.vmin,
+        vmax=args.vmax,
+    )

mhm_tools/_cli/__init__.py

@@ -0,0 +1,5 @@
+"""The command line interface."""
+
+from ._main import main
+
+__all__ = ["main"]

mhm_tools/_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m mhm_tools._cli`` execution."""
+
+from . import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mhm_tools/_cli/_bankfull.py

@@ -0,0 +1,84 @@
+"""Calculate the river discharge at bankfull conditions and the bankfull width.
+
+Bankfull discharge is determined as the yearly peak flow with a
+recurrence interval given by "return_period", which is 1.5 years by
+default. The wetted perimeter is estimated from bankfull discharge with
+Lacey's formula.
+
+This routine will simply use the closest flood event in terms of its
+recurrence interval. Also, any input time-stepping is accepted but daily
+or sub-daily data is preferred. Ouput variables in the created NetCDF
+file are called "Q_bkfl" and "P_bkfl".
+
+Authors
+-------
+- Sebastian Müller
+"""
+
+
+def add_args(parser):
+    """Add cli arguments for the bankfull subcommand.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        the main argument parser
+    """
+    optional = parser.add_argument_group("optional arguments")
+    flags = parser.add_argument_group("flags")
+    optional.add_argument(
+        "-r",
+        "--return-period",
+        type=float,
+        default=1.5,
+        help="The return period of the flood in years.",
+    )
+    flags.add_argument(
+        "-w",
+        "--wetted-perimeter",
+        action="store_true",
+        default=False,
+        help="Additionally estimate the wetted perimeter.",
+    )
+    optional.add_argument(
+        "-v",
+        "--var",
+        default="Qrouted",
+        help="Variable name for routed streamflow in the NetCDF file",
+    )
+    required_args = parser.add_argument_group("required arguments")
+    required_args.add_argument(
+        "-i",
+        "--input-file",
+        "--input",
+        dest="in_file",
+        required=True,
+        help="The path of the mRM NetCDF file with the discharge data.",
+    )
+    required_args.add_argument(
+        "-o",
+        "--output-file",
+        "--output",
+        dest="out_file",
+        required=True,
+        help="The path of the output NetCDF file.",
+    )
+
+
+def run(args):
+    """Calculate the bankfull discharge.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        parsed command line arguments
+    """
+    from ..post.bankfull import bankfull_discharge
+
+    bankfull_discharge(
+        in_file=args.in_file,
+        out_file=args.out_file,
+        return_period=args.return_period,
+        wetted_perimeter=args.wetted_perimeter,
+        var=args.var,
+    )

mhm_tools/_cli/_calculate_pet.py

@@ -0,0 +1,94 @@
+"""Calculating pet.
+
+Contains multiple different pet methods mainly temperature based.
+
+Authors
+-------
+- Matthias Kelbling
+- Simon Lüdke
+- Stephan Thober
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def add_args(parser):
+    """Add CLI arguments for calculate_pet subcommand."""
+    # Description and epilog
+    parser.description = (
+        # "Utility functions for mHM processing netCDF precipitation and temperature forcings, "
+        # "including unit conversion, coordinate ordering, setting correct variable name and "
+        # "units as well as missing and fill values, and spatial cropping."
+    )
+    parser.epilog = "See mhm-tools documentation for detailed examples and usage."
+
+    # Required arguments
+    required = parser.add_argument_group("required arguments")
+    required.add_argument(
+        "-o",
+        "--output-file",
+        required=True,
+        help="Output directory for processed files",
+    )
+    optional = parser.add_argument_group("optional arguments")
+    optional.add_argument(
+        "--tavg",
+        required=False,
+        default=None,
+        help="Temperature average file",
+    )
+    optional.add_argument(
+        "--tmax",
+        required=False,
+        default=None,
+        help="Temperature maximum file",
+    )
+    optional.add_argument(
+        "--tmin",
+        required=False,
+        default=None,
+        help="Temperature minimum file",
+    )
+    optional.add_argument(
+        "-f",
+        "--freq",
+        required=False,
+        default=None,
+        help="Frequency of pet output, daily or hourly.",
+    )
+    optional.add_argument(
+        "--method",
+        required=False,
+        default="oudin",
+        help="Method of pet calculation. Currently implemented: hargreaves_samani, oudin, jensen_haise, mcguinness_bordne, hamon, blaney_criddle.",
+    )
+    optional.add_argument(
+        "--ncpus",
+        required=False,
+        default=1,
+        type=int,
+        help=("Number of cores used for parallelisation."),
+    )
+
+
+def run(args):
+    """Calculate PET from temperature inputs and write output.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        parsed command line arguments
+    """
+    from mhm_tools.pre.pet_calc import calculate_pet
+
+    calculate_pet(
+        tavg_file=args.tavg,
+        tmax_file=args.tmax,
+        tmin_file=args.tmin,
+        stat_freq=args.freq,
+        out_file=args.output_file,
+        max_workers=args.ncpus,
+        method=args.method,
+    )