rashdf 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

cli.py

@@ -1,6 +1,6 @@
 """rashdf CLI."""
 
-from rashdf import RasGeomHdf
+from rashdf import RasGeomHdf, RasPlanHdf
 from rashdf.utils import df_datetimes_to_str
 
 import fiona
@@ -10,6 +10,7 @@ import argparse
 from ast import literal_eval
 from pathlib import Path
 import sys
+import re
 from typing import List, Optional
 import warnings
 
@@ -108,17 +109,22 @@ def export(args: argparse.Namespace) -> Optional[str]:
         for driver in fiona_supported_drivers():
             print(driver)
         return
-    if "://" in args.hdf_file:
-        geom_hdf = RasGeomHdf.open_uri(args.hdf_file)
+    if re.match(r"^.*\.p\d\d\.hdf$", args.hdf_file):
+        ras_hdf_class = RasPlanHdf
     else:
-        geom_hdf = RasGeomHdf(args.hdf_file)
+        ras_hdf_class = RasGeomHdf
+    if re.match(r"^\w+://", args.hdf_file):
+        geom_hdf = ras_hdf_class.open_uri(args.hdf_file)
+    else:
+        geom_hdf = ras_hdf_class(args.hdf_file)
     func = getattr(geom_hdf, args.func)
     gdf: GeoDataFrame = func()
     kwargs = literal_eval(args.kwargs) if args.kwargs else {}
     if args.to_crs:
         gdf = gdf.to_crs(args.to_crs)
     if not args.output_file:
-        # convert any datetime columns to strings
+        # If an output file path isn't provided, write the GeoDataFrame to stdout
+        # as GeoJSON. Convert any datetime columns to strings.
         gdf = df_datetimes_to_str(gdf)
         with warnings.catch_warnings():
             # Squash warnings about converting the CRS to OGC URN format.
@@ -143,9 +149,9 @@ def export(args: argparse.Namespace) -> Optional[str]:
     output_file_path = Path(args.output_file)
     output_file_ext = output_file_path.suffix
     if output_file_ext not in [".gpkg"]:
-        # unless the user specifies a format that supports datetime,
-        # convert any datetime columns to string
-        # TODO: besides Geopackage, which of the standard Fiona formats allow datetime?
+        # Unless the user specifies a format that supports datetime,
+        # convert any datetime columns to string.
+        # TODO: besides Geopackage, which of the standard Fiona drivers allow datetime?
         gdf = df_datetimes_to_str(gdf)
     gdf.to_file(args.output_file, **kwargs)
 

rashdf/geom.py

@@ -66,12 +66,12 @@ class RasGeomHdf(RasHdf):
         List[str]
             A list of the 2D mesh area names (str) within the RAS geometry if 2D areas exist.
         """
-        if "/Geometry/2D Flow Areas" not in self:
+        if self.FLOW_AREA_2D_PATH not in self:
             return list()
         return list(
             [
                 convert_ras_hdf_string(n)
-                for n in self["/Geometry/2D Flow Areas/Attributes"][()]["Name"]
+                for n in self[f"{self.FLOW_AREA_2D_PATH}/Attributes"][()]["Name"]
             ]
         )
 
@@ -87,7 +87,7 @@ class RasGeomHdf(RasHdf):
         if not mesh_area_names:
             return GeoDataFrame()
         mesh_area_polygons = [
-            Polygon(self[f"/Geometry/2D Flow Areas/{n}/Perimeter"][()])
+            Polygon(self[f"{self.FLOW_AREA_2D_PATH}/{n}/Perimeter"][()])
             for n in mesh_area_names
         ]
         return GeoDataFrame(
@@ -112,13 +112,13 @@ class RasGeomHdf(RasHdf):
 
         cell_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
         for i, mesh_name in enumerate(mesh_area_names):
-            cell_cnt = self["/Geometry/2D Flow Areas/Cell Info"][()][i][1]
+            cell_cnt = self[f"{self.FLOW_AREA_2D_PATH}/Cell Info"][()][i][1]
             cell_ids = list(range(cell_cnt))
             cell_face_info = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Info"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Cells Face and Orientation Info"
             ][()]
             cell_face_values = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Values"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Cells Face and Orientation Values"
             ][()][:, 0]
             face_id_lists = list(
                 np.vectorize(
@@ -169,8 +169,8 @@ class RasGeomHdf(RasHdf):
             return GeoDataFrame()
         pnt_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
         for i, mesh_name in enumerate(mesh_area_names):
-            starting_row, count = self["/Geometry/2D Flow Areas/Cell Info"][()][i]
-            cell_pnt_coords = self["/Geometry/2D Flow Areas/Cell Points"][()][
+            starting_row, count = self[f"{self.FLOW_AREA_2D_PATH}/Cell Info"][()][i]
+            cell_pnt_coords = self[f"{self.FLOW_AREA_2D_PATH}/Cell Points"][()][
                 starting_row : starting_row + count
             ]
             pnt_dict["mesh_name"] += [mesh_name] * cell_pnt_coords.shape[0]
@@ -196,16 +196,16 @@ class RasGeomHdf(RasHdf):
         face_dict = {"mesh_name": [], "face_id": [], "geometry": []}
         for mesh_name in mesh_area_names:
             facepoints_index = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces FacePoint Indexes"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces FacePoint Indexes"
             ][()]
             facepoints_coordinates = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/FacePoints Coordinate"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/FacePoints Coordinate"
             ][()]
             faces_perimeter_info = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Info"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces Perimeter Info"
             ][()]
             faces_perimeter_values = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Values"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces Perimeter Values"
             ][()]
             face_id = -1
             for pnt_a_index, pnt_b_index in facepoints_index:

rashdf/plan.py

@@ -1,8 +1,132 @@
 """HEC-RAS Plan HDF class."""
 
 from .geom import RasGeomHdf
-from typing import Dict
+from .utils import (
+    df_datetimes_to_str,
+    ras_timesteps_to_datetimes,
+    parse_ras_datetime_ms,
+)
+
 from geopandas import GeoDataFrame
+import h5py
+import numpy as np
+from pandas import DataFrame
+import pandas as pd
+import xarray as xr
+
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Tuple, Union
+
+
+class RasPlanHdfError(Exception):
+    """HEC-RAS Plan HDF error class."""
+
+    pass
+
+
+class SummaryOutputVar(Enum):
+    """Summary output variables."""
+
+    MAXIMUM_WATER_SURFACE = "Maximum Water Surface"
+    MINIMUM_WATER_SURFACE = "Minimum Water Surface"
+    MAXIMUM_FACE_VELOCITY = "Maximum Face Velocity"
+    MINIMUM_FACE_VELOCITY = "Minimum Face Velocity"
+    CELL_MAXIMUM_WATER_SURFACE_ERROR = "Cell Maximum Water Surface Error"
+    CELL_CUMULATIVE_ITERATION = "Cell Cumulative Iteration"
+    CELL_LAST_ITERATION = "Cell Last Iteration"
+
+
+SUMMARY_OUTPUT_VARS_CELLS = [
+    SummaryOutputVar.MAXIMUM_WATER_SURFACE,
+    SummaryOutputVar.MINIMUM_WATER_SURFACE,
+    SummaryOutputVar.CELL_MAXIMUM_WATER_SURFACE_ERROR,
+    SummaryOutputVar.CELL_CUMULATIVE_ITERATION,
+    SummaryOutputVar.CELL_LAST_ITERATION,
+]
+
+SUMMARY_OUTPUT_VARS_FACES = [
+    SummaryOutputVar.MAXIMUM_FACE_VELOCITY,
+    SummaryOutputVar.MINIMUM_FACE_VELOCITY,
+]
+
+
+class TimeSeriesOutputVar(Enum):
+    """Time series output variables."""
+
+    # Default Outputs
+    WATER_SURFACE = "Water Surface"
+    FACE_VELOCITY = "Face Velocity"
+
+    # Optional Outputs
+    CELL_COURANT = "Cell Courant"
+    CELL_CUMULATIVE_PRECIPITATION_DEPTH = "Cell Cumulative Precipitation Depth"
+    CELL_DIVERGENCE_TERM = "Cell Divergence Term"
+    CELL_EDDY_VISCOSITY_X = "Cell Eddy Viscosity - Eddy Viscosity X"
+    CELL_EDDY_VISCOSITY_Y = "Cell Eddy Viscosity - Eddy Viscosity Y"
+    CELL_FLOW_BALANCE = "Cell Flow Balance"
+    CELL_HYDRAULIC_DEPTH = "Cell Hydraulic Depth"
+    CELL_INVERT_DEPTH = "Cell Invert Depth"
+    CELL_STORAGE_TERM = "Cell Storage Term"
+    CELL_VELOCITY_X = "Cell Velocity - Velocity X"
+    CELL_VELOCITY_Y = "Cell Velocity - Velocity Y"
+    CELL_VOLUME = "Cell Volume"
+    CELL_VOLUME_ERROR = "Cell Volume Error"
+    CELL_WATER_SOURCE_TERM = "Cell Water Source Term"
+    CELL_WATER_SURFACE_ERROR = "Cell Water Surface Error"
+
+    FACE_COURANT = "Face Courant"
+    FACE_CUMULATIVE_VOLUME = "Face Cumulative Volume"
+    FACE_EDDY_VISCOSITY = "Face Eddy Viscosity"
+    FACE_FLOW = "Face Flow"
+    FACE_FLOW_PERIOD_AVERAGE = "Face Flow Period Average"
+    FACE_FRICTION_TERM = "Face Friction Term"
+    FACE_PRESSURE_GRADIENT_TERM = "Face Pressure Gradient Term"
+    FACE_SHEAR_STRESS = "Face Shear Stress"
+    FACE_TANGENTIAL_VELOCITY = "Face Tangential Velocity"
+    FACE_WATER_SURFACE = "Face Water Surface"
+    FACE_WIND_TERM = "Face Wind Term"
+
+
+TIME_SERIES_OUTPUT_VARS_CELLS = [
+    TimeSeriesOutputVar.WATER_SURFACE,
+    TimeSeriesOutputVar.CELL_COURANT,
+    TimeSeriesOutputVar.CELL_CUMULATIVE_PRECIPITATION_DEPTH,
+    TimeSeriesOutputVar.CELL_DIVERGENCE_TERM,
+    TimeSeriesOutputVar.CELL_EDDY_VISCOSITY_X,
+    TimeSeriesOutputVar.CELL_EDDY_VISCOSITY_Y,
+    TimeSeriesOutputVar.CELL_FLOW_BALANCE,
+    TimeSeriesOutputVar.CELL_HYDRAULIC_DEPTH,
+    TimeSeriesOutputVar.CELL_INVERT_DEPTH,
+    TimeSeriesOutputVar.CELL_STORAGE_TERM,
+    TimeSeriesOutputVar.CELL_VELOCITY_X,
+    TimeSeriesOutputVar.CELL_VELOCITY_Y,
+    TimeSeriesOutputVar.CELL_VOLUME,
+    TimeSeriesOutputVar.CELL_VOLUME_ERROR,
+    TimeSeriesOutputVar.CELL_WATER_SOURCE_TERM,
+    TimeSeriesOutputVar.CELL_WATER_SURFACE_ERROR,
+]
+
+TIME_SERIES_OUTPUT_VARS_FACES = [
+    TimeSeriesOutputVar.FACE_COURANT,
+    TimeSeriesOutputVar.FACE_CUMULATIVE_VOLUME,
+    TimeSeriesOutputVar.FACE_EDDY_VISCOSITY,
+    TimeSeriesOutputVar.FACE_FLOW,
+    TimeSeriesOutputVar.FACE_FLOW_PERIOD_AVERAGE,
+    TimeSeriesOutputVar.FACE_FRICTION_TERM,
+    TimeSeriesOutputVar.FACE_PRESSURE_GRADIENT_TERM,
+    TimeSeriesOutputVar.FACE_SHEAR_STRESS,
+    TimeSeriesOutputVar.FACE_TANGENTIAL_VELOCITY,
+    TimeSeriesOutputVar.FACE_VELOCITY,
+    TimeSeriesOutputVar.FACE_WATER_SURFACE,
+    # TODO: investigate why "Face Wind Term" data gets written as a 1D array
+    # TimeSeriesOutputVar.FACE_WIND_TERM,
+]
+
+TIME_SERIES_OUTPUT_VARS_DEFAULT = [
+    TimeSeriesOutputVar.WATER_SURFACE,
+    TimeSeriesOutputVar.FACE_VELOCITY,
+]
 
 
 class RasPlanHdf(RasGeomHdf):
@@ -14,6 +138,11 @@ class RasPlanHdf(RasGeomHdf):
     RESULTS_UNSTEADY_PATH = "Results/Unsteady"
     RESULTS_UNSTEADY_SUMMARY_PATH = f"{RESULTS_UNSTEADY_PATH}/Summary"
     VOLUME_ACCOUNTING_PATH = f"{RESULTS_UNSTEADY_PATH}/Volume Accounting"
+    BASE_OUTPUT_PATH = f"{RESULTS_UNSTEADY_PATH}/Output/Output Blocks/Base Output"
+    SUMMARY_OUTPUT_2D_FLOW_AREAS_PATH = (
+        f"{BASE_OUTPUT_PATH}/Summary Output/2D Flow Areas"
+    )
+    UNSTEADY_TIME_SERIES_PATH = f"{BASE_OUTPUT_PATH}/Unsteady Time Series"
 
     def __init__(self, name: str, **kwargs):
         """Open a HEC-RAS Plan HDF file.
@@ -27,6 +156,745 @@ class RasPlanHdf(RasGeomHdf):
         """
         super().__init__(name, **kwargs)
 
+    def _simulation_start_time(self) -> datetime:
+        """Return the simulation start time from the plan file.
+
+        Returns
+        -------
+        datetime
+            The simulation start time.
+        """
+        plan_info = self.get_plan_info_attrs()
+        return plan_info["Simulation Start Time"]
+
+    def _2d_flow_area_names_and_counts(self) -> List[Tuple[str, int]]:
+        """
+        Return a list of 2D flow area names and cell counts.
+
+        Returns
+        -------
+        List[Tuple[str, int]]
+            A list of tuples, where each tuple contains a 2D flow area name
+            and the number of cells in that area.
+        """
+        d2_flow_areas = self[f"{self.FLOW_AREA_2D_PATH}/Attributes"][:]
+        return [
+            (d2_flow_area[0].decode("utf-8"), d2_flow_area[-1])
+            for d2_flow_area in d2_flow_areas
+        ]
+
+    def _mesh_summary_output_group(
+        self, mesh_name: str, output_var: SummaryOutputVar
+    ) -> h5py.Group:
+        """Return the HDF group for a 2D flow area summary output variable.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+        output_var : str
+            The name of the output variable.
+
+        Returns
+        -------
+        h5py.Group
+            The HDF group for the output variable.
+        """
+        output_path = (
+            f"{self.SUMMARY_OUTPUT_2D_FLOW_AREAS_PATH}/{mesh_name}/{output_var.value}"
+        )
+        output_group = self.get(output_path)
+        if output_group is None:
+            raise RasPlanHdfError(
+                f"Could not find HDF group at path '{output_path}'."
+                " Does the Plan HDF file contain 2D output data?"
+            )
+        return output_group
+
+    def _mesh_summary_output_min_max_values(
+        self, mesh_name: str, var: SummaryOutputVar
+    ) -> np.ndarray:
+        """Return values for a "Maximum"/"Minimum" summary output variable.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+        var : SummaryOutputVar
+            The summary output variable to retrieve.
+
+        Returns
+        -------
+        np.ndarray
+            An array of maximum water surface elevation values.
+        """
+        max_ws_group = self._mesh_summary_output_group(mesh_name, var)
+        max_ws_raw = max_ws_group[:]
+        max_ws_values = max_ws_raw[0]
+        return max_ws_values
+
+    def _summary_output_min_max_time_unit(self, dataset: h5py.Dataset) -> str:
+        """Return the time unit for "Maximum"/"Minimum" summary output datasets.
+
+        I.e., for summary output such as "Maximum Water Surface", "Minimum Water Surface", etc.
+
+        Should normally return the string: "days".
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+
+        Returns
+        -------
+        str
+            The time unit for the maximum water surface elevation data.
+        """
+        if "Units per row" in dataset.attrs:
+            units = dataset.attrs["Units per row"]
+        else:
+            units = dataset.attrs["Units"]
+        # expect an array of size 2, with the first element being length or velocity units
+        # and the second element being time units (e.g., ["ft", "days"])
+        time_unit = units[1]
+        return time_unit.decode("utf-8")
+
+    def _mesh_summary_output_min_max_times(
+        self,
+        mesh_name: str,
+        var: SummaryOutputVar,
+        time_unit: str = "days",
+        round_to: str = "0.1 s",
+    ) -> np.ndarray[np.datetime64]:
+        """Return an array of times for min/max summary output data.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+        var : SummaryOutputVar
+            The summary output variable to retrieve.
+        time_unit : str, optional
+            The time unit for the maximum water surface elevation data.
+            Default: "days".
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+
+        Returns
+        -------
+        np.ndarray[np.datetime64]
+            An array of times for the maximum water surface elevation data.
+        """
+        start_time = self._simulation_start_time()
+        max_ws_group = self._mesh_summary_output_group(mesh_name, var)
+        time_unit = self._summary_output_min_max_time_unit(max_ws_group)
+        max_ws_raw = max_ws_group[:]
+        max_ws_times_raw = max_ws_raw[1]
+        # we get weirdly specific datetime values if we don't round to e.g., 0.1 seconds;
+        # otherwise datetimes don't align with the actual timestep values in the plan file
+        max_ws_times = ras_timesteps_to_datetimes(
+            max_ws_times_raw, start_time, time_unit=time_unit, round_to=round_to
+        )
+        return max_ws_times
+
+    def _mesh_summary_output_min_max(
+        self,
+        var: SummaryOutputVar,
+        value_col: str = "value",
+        time_col: str = "time",
+        round_to: str = "0.1 s",
+    ) -> DataFrame:
+        """Return the min/max values and times for a summary output variable.
+
+        Valid for:
+        - Maximum Water Surface
+        - Minimum Water Surface
+        - Maximum Face Velocity
+        - Minimum Face Velocity
+        - Cell Maximum Water Surface Error
+
+        Parameters
+        ----------
+        var : SummaryOutputVar
+            The summary output variable to retrieve.
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id' or 'face_id', 'value', and 'time'.
+        """
+        dfs = []
+        for mesh_name, cell_count in self._2d_flow_area_names_and_counts():
+            values = self._mesh_summary_output_min_max_values(mesh_name, var)
+            times = self._mesh_summary_output_min_max_times(
+                mesh_name, var, round_to=round_to
+            )
+            if var in [
+                SummaryOutputVar.MAXIMUM_FACE_VELOCITY,
+                SummaryOutputVar.MINIMUM_FACE_VELOCITY,
+            ]:
+                geom_id_col = "face_id"
+            else:
+                geom_id_col = "cell_id"
+                # The 2D mesh output data contains values for more cells than are actually
+                # in the mesh. The the true number of cells for a mesh is found in the table:
+                # "/Geometry/2D Flow Areas/Attributes". The number of cells in the 2D output
+                # data instead matches the number of cells in the "Cells Center Coordinate"
+                # array, which contains extra points along the perimeter of the mesh. These
+                # extra points are appended to the end of the mesh data and contain bogus
+                # output values (e.g., 0.0, NaN). We need to filter out these bogus values.
+                values = values[:cell_count]
+                times = times[:cell_count]
+            df = DataFrame(
+                {
+                    "mesh_name": [mesh_name] * len(values),
+                    geom_id_col: range(len(values)),
+                    value_col: values,
+                    time_col: times,
+                }
+            )
+            dfs.append(df)
+        df = pd.concat(dfs, ignore_index=True)
+        return df
+
+    def _mesh_summary_output_basic(
+        self, var: SummaryOutputVar, value_col: str = "value"
+    ) -> DataFrame:
+        """Return values and times for a summary output variable.
+
+        Valid for:
+        - Cell Cumulative Iteration (i.e. Cumulative Max Iterations)
+        - Cell Last Iteration
+
+        Parameters
+        ----------
+        var : SummaryOutputVar
+            The summary output variable to retrieve.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id' or 'face_id', 'value', and 'time'.
+        """
+        dfs = []
+        for mesh_name, cell_count in self._2d_flow_area_names_and_counts():
+            group = self._mesh_summary_output_group(mesh_name, var)
+            values = group[:][:cell_count]
+            df = DataFrame(
+                {
+                    "mesh_name": [mesh_name] * len(values),
+                    "cell_id": range(len(values)),
+                    value_col: values,
+                }
+            )
+            dfs.append(df)
+        df = pd.concat(dfs, ignore_index=True)
+        return df
+
+    def mesh_max_iter(self) -> DataFrame:
+        """Return the number of times each cell in the mesh reached the max number of iterations.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id', and 'max_iterations'.
+        """
+        df = self._mesh_summary_output_basic(
+            SummaryOutputVar.CELL_CUMULATIVE_ITERATION, value_col="max_iter"
+        )
+        return df
+
+    def mesh_last_iter(self) -> DataFrame:
+        """Return the number of times each cell in the mesh was the last cell to converge.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id', and 'last_iter'.
+        """
+        df = self._mesh_summary_output_basic(
+            SummaryOutputVar.CELL_LAST_ITERATION, value_col="last_iter"
+        )
+        return df
+
+    def mesh_max_ws(self, round_to: str = "0.1 s") -> DataFrame:
+        """Return the max water surface elevation for each cell in the mesh.
+
+        Includes the corresponding time of max water surface elevation.
+
+        Parameters
+        ----------
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+            See Pandas documentation for valid time units:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id', 'max_ws', and 'max_ws_time'.
+        """
+        df = self._mesh_summary_output_min_max(
+            SummaryOutputVar.MAXIMUM_WATER_SURFACE,
+            value_col="max_ws",
+            time_col="max_ws_time",
+            round_to=round_to,
+        )
+        return df
+
+    def mesh_min_ws(self, round_to: str = "0.1 s") -> DataFrame:
+        """Return the min water surface elevation for each cell in the mesh.
+
+        Includes the corresponding time of min water surface elevation.
+
+        Parameters
+        ----------
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+            See Pandas documentation for valid time units:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id', 'min_ws', and 'min_ws_time'.
+        """
+        df = self._mesh_summary_output_min_max(
+            SummaryOutputVar.MINIMUM_WATER_SURFACE,
+            value_col="min_ws",
+            time_col="min_ws_time",
+            round_to=round_to,
+        )
+        return df
+
+    def mesh_max_face_v(self, round_to: str = "0.1 s") -> DataFrame:
+        """Return the max face velocity for each face in the mesh.
+
+        Includes the corresponding time of max face velocity.
+
+        Parameters
+        ----------
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+            See Pandas documentation for valid time units:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'face_id', 'max_v', and 'max_v_time'.
+        """
+        df = self._mesh_summary_output_min_max(
+            SummaryOutputVar.MAXIMUM_FACE_VELOCITY,
+            value_col="max_v",
+            time_col="max_v_time",
+            round_to=round_to,
+        )
+        return df
+
+    def mesh_min_face_v(self, round_to: str = "0.1 s") -> DataFrame:
+        """Return the min face velocity for each face in the mesh.
+
+        Includes the corresponding time of min face velocity.
+
+        Parameters
+        ----------
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+            See Pandas documentation for valid time units:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'face_id', 'min_v', and 'min_v_time'.
+        """
+        df = self._mesh_summary_output_min_max(
+            SummaryOutputVar.MINIMUM_FACE_VELOCITY,
+            value_col="min_v",
+            time_col="min_v_time",
+            round_to=round_to,
+        )
+        return df
+
+    def mesh_max_ws_err(self, round_to: str = "0.1 s") -> DataFrame:
+        """Return the max water surface error for each cell in the mesh.
+
+        Includes the corresponding time of max water surface error.
+
+        Parameters
+        ----------
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+            See Pandas documentation for valid time units:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id', 'max_ws_err', and 'max_ws_err_time'.
+        """
+        df = self._mesh_summary_output_min_max(
+            SummaryOutputVar.CELL_MAXIMUM_WATER_SURFACE_ERROR,
+            value_col="max_ws_err",
+            time_col="max_ws_err_time",
+            round_to=round_to,
+        )
+        return df
+
+    def mesh_summary_output(
+        self, var: SummaryOutputVar, round_to: str = "0.1 s"
+    ) -> DataFrame:
+        """Return the summary output data for a given variable.
+
+        Parameters
+        ----------
+        var : SummaryOutputVar
+            The summary output variable to retrieve.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with columns 'mesh_name', 'cell_id' or 'face_id', a value column, and a time column.
+        """
+        methods_with_times = {
+            SummaryOutputVar.MAXIMUM_WATER_SURFACE: self.mesh_max_ws,
+            SummaryOutputVar.MINIMUM_WATER_SURFACE: self.mesh_min_ws,
+            SummaryOutputVar.MAXIMUM_FACE_VELOCITY: self.mesh_max_face_v,
+            SummaryOutputVar.MINIMUM_FACE_VELOCITY: self.mesh_min_face_v,
+            SummaryOutputVar.CELL_MAXIMUM_WATER_SURFACE_ERROR: self.mesh_max_ws_err,
+        }
+        other_methods = {
+            SummaryOutputVar.CELL_CUMULATIVE_ITERATION: self.mesh_max_iter,
+            SummaryOutputVar.CELL_LAST_ITERATION: self.mesh_last_iter,
+        }
+        if var in methods_with_times:
+            df = methods_with_times[var](round_to=round_to)
+        else:
+            df = other_methods[var]()
+        return df
+
+    def _summary_output_vars(
+        self, cells_or_faces: Optional[str] = None
+    ) -> List[SummaryOutputVar]:
+        """Return a list of available summary output variables from the Plan HDF file.
+
+        Returns
+        -------
+        List[SummaryOutputVar]
+            A list of summary output variables.
+        """
+        mesh_names_counts = self._2d_flow_area_names_and_counts()
+        mesh_names = [mesh_name for mesh_name, _ in mesh_names_counts]
+        vars = set()
+        for mesh_name in mesh_names:
+            path = f"{self.SUMMARY_OUTPUT_2D_FLOW_AREAS_PATH}/{mesh_name}"
+            datasets = self[path].keys()
+            for dataset in datasets:
+                try:
+                    var = SummaryOutputVar(dataset)
+                except ValueError:
+                    continue
+                vars.add(var)
+        if cells_or_faces == "cells":
+            vars = vars.intersection(SUMMARY_OUTPUT_VARS_CELLS)
+        elif cells_or_faces == "faces":
+            vars = vars.intersection(SUMMARY_OUTPUT_VARS_FACES)
+        return sorted(list(vars), key=lambda x: x.value)
+
+    def _mesh_summary_outputs_gdf(
+        self,
+        geom_func: str,
+        cells_or_faces: str = "cells",
+        include_output: Union[bool, List[SummaryOutputVar]] = True,
+        round_to: str = "0.1 s",
+        datetime_to_str: bool = False,
+    ) -> GeoDataFrame:
+        """Return a GeoDataFrame with mesh geometry and summary output data.
+
+        Parameters
+        ----------
+        geom_func : str
+            The method name to call to get the mesh geometry.
+        cells_or_faces : str, optional
+            The type of geometry to include in the GeoDataFrame.
+            Must be either "cells" or "faces". (default: "cells")
+        include_output : Union[bool, List[SummaryOutputVar]], optional
+            If True, include all available summary output data in the GeoDataFrame.
+            If a list of SummaryOutputVar values, include only the specified summary output data.
+            If False, do not include any summary output data.
+            (default: True)
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+        datetime_to_str : bool, optional
+            If True, convert datetime columns to strings. (default: False)
+        """
+        gdf = getattr(super(), geom_func)()
+        if include_output is False:
+            return gdf
+        if include_output is True:
+            summary_output_vars = self._summary_output_vars(
+                cells_or_faces=cells_or_faces
+            )
+        elif isinstance(include_output, list):
+            summary_output_vars = []
+            for var in include_output:
+                if not isinstance(var, SummaryOutputVar):
+                    var = SummaryOutputVar(var)
+                summary_output_vars.append(var)
+        else:
+            raise ValueError(
+                "include_output must be a boolean or a list of SummaryOutputVar values."
+            )
+        if cells_or_faces == "cells":
+            geom_id_col = "cell_id"
+        elif cells_or_faces == "faces":
+            geom_id_col = "face_id"
+        else:
+            raise ValueError('cells_or_faces must be either "cells" or "faces".')
+        for var in summary_output_vars:
+            df = self.mesh_summary_output(var, round_to=round_to)
+            gdf = gdf.merge(df, on=["mesh_name", geom_id_col], how="left")
+        if datetime_to_str:
+            gdf = df_datetimes_to_str(gdf)
+        return gdf
+
+    def mesh_cell_points(
+        self,
+        include_output: Union[bool, List[SummaryOutputVar], List[str]] = True,
+        round_to: str = "0.1 s",
+        datetime_to_str: bool = False,
+    ) -> GeoDataFrame:
+        """Return the cell points for each cell in the mesh, including summary output.
+
+        Parameters
+        ----------
+        include_output : Union[bool, List[SummaryOutputVar], List[str]], optional
+            If True, include all available summary output data in the GeoDataFrame.
+            If a list of SummaryOutputVar values, include only the specified summary output data.
+            If a list of strings, include only the specified summary output data by name.
+            If False, do not include any summary output data.
+            (default: True)
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+        datetime_to_str : bool, optional
+            If True, convert datetime columns to strings. (default: False)
+
+        Returns
+        -------
+        GeoDataFrame
+            A GeoDataFrame with columns 'mesh_name', 'cell_id', 'geometry', and columns for each
+            summary output variable.
+        """
+        return self._mesh_summary_outputs_gdf(
+            "mesh_cell_points",
+            "cells",
+            include_output=include_output,
+            round_to=round_to,
+            datetime_to_str=datetime_to_str,
+        )
+
+    def mesh_cell_polygons(
+        self,
+        include_output: Union[bool, List[SummaryOutputVar], List[str]] = True,
+        round_to: str = "0.1 s",
+        datetime_to_str: bool = False,
+    ) -> GeoDataFrame:
+        """Return the cell polygons for each cell in the mesh, including output.
+
+        Parameters
+        ----------
+        include_output : Union[bool, List[SummaryOutputVar], List[str]], optional
+            If True, include all available summary output data in the GeoDataFrame.
+            If a list of SummaryOutputVar values, include only the specified summary output data.
+            If a list of strings, include only the specified summary output data by name.
+            If False, do not include any summary output data.
+            (default: True)
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+        datetime_to_str : bool, optional
+            If True, convert datetime columns to strings. (default: False)
+
+        Returns
+        -------
+        GeoDataFrame
+            A GeoDataFrame with columns 'mesh_name', 'cell_id', 'geometry', and columns for each
+            summary output variable.
+        """
+        return self._mesh_summary_outputs_gdf(
+            "mesh_cell_polygons",
+            "cells",
+            include_output=include_output,
+            round_to=round_to,
+            datetime_to_str=datetime_to_str,
+        )
+
+    def mesh_cell_faces(
+        self,
+        include_output: Union[bool, List[SummaryOutputVar], List[str]] = True,
+        round_to: str = "0.1 s",
+        datetime_to_str: bool = False,
+    ) -> GeoDataFrame:
+        """Return the cell faces for each cell in the mesh, including output.
+
+        Parameters
+        ----------
+        include_output : Union[bool, List[SummaryOutputVar], List[str]], optional
+            If True, include all available summary output data in the GeoDataFrame.
+            If a list of SummaryOutputVar values, include only the specified summary output data.
+            If a list of strings, include only the specified summary output data by name.
+            If False, do not include any summary output data.
+            (default: True)
+        round_to : str, optional
+            The time unit to round the datetimes to. Default: "0.1 s" (seconds).
+        datetime_to_str : bool, optional
+            If True, convert datetime columns to strings. (default: False)
+
+        Returns
+        -------
+        GeoDataFrame
+            A GeoDataFrame with columns 'mesh_name', 'cell_id', 'geometry', and columns for each
+            summary output variable.
+        """
+        return self._mesh_summary_outputs_gdf(
+            "mesh_cell_faces",
+            "faces",
+            include_output=include_output,
+            round_to=round_to,
+            datetime_to_str=datetime_to_str,
+        )
+
+    def unsteady_datetimes(self) -> List[datetime]:
+        """Return the unsteady timeseries datetimes from the plan file.
+
+        Returns
+        -------
+        List[datetime]
+            A list of datetimes for the unsteady timeseries data.
+        """
+        group_path = f"{self.UNSTEADY_TIME_SERIES_PATH}/Time Date Stamp (ms)"
+        raw_datetimes = self[group_path][:]
+        dt = [parse_ras_datetime_ms(x.decode("utf-8")) for x in raw_datetimes]
+        return dt
+
+    def _mesh_timeseries_output_values_units(
+        self,
+        mesh_name: str,
+        var: TimeSeriesOutputVar,
+    ) -> Tuple[np.ndarray, str]:
+        path = f"{self.UNSTEADY_TIME_SERIES_PATH}/2D Flow Areas/{mesh_name}/{var.value}"
+        group = self.get(path)
+        try:
+            import dask.array as da
+
+            # TODO: user-specified chunks?
+            values = da.from_array(group, chunks=group.chunks)
+        except ImportError:
+            values = group[:]
+        units = group.attrs.get("Units")
+        if units is not None:
+            units = units.decode("utf-8")
+        return values, units
+
+    def mesh_timeseries_output(
+        self,
+        mesh_name: str,
+        var: Union[str, TimeSeriesOutputVar],
+    ) -> xr.DataArray:
+        """Return the time series output data for a given variable.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+        var : TimeSeriesOutputVar
+            The time series output variable to retrieve.
+
+        Returns
+        -------
+        xr.DataArray
+            An xarray DataArray with dimensions 'time' and 'cell_id'.
+        """
+        times = self.unsteady_datetimes()
+        mesh_names_counts = {
+            name: count for name, count in self._2d_flow_area_names_and_counts()
+        }
+        if mesh_name not in mesh_names_counts:
+            raise ValueError(f"Mesh '{mesh_name}' not found in the Plan HDF file.")
+        if isinstance(var, str):
+            var = TimeSeriesOutputVar(var)
+        values, units = self._mesh_timeseries_output_values_units(mesh_name, var)
+        if var in TIME_SERIES_OUTPUT_VARS_CELLS:
+            cell_count = mesh_names_counts[mesh_name]
+            values = values[:, :cell_count]
+            id_coord = "cell_id"
+        elif var in TIME_SERIES_OUTPUT_VARS_FACES:
+            id_coord = "face_id"
+        else:
+            raise ValueError(f"Invalid time series output variable: {var.value}")
+        da = xr.DataArray(
+            values,
+            name=var.value,
+            dims=["time", id_coord],
+            coords={
+                "time": times,
+                id_coord: range(values.shape[1]),
+            },
+            attrs={
+                "mesh_name": mesh_name,
+                "variable": var.value,
+                "units": units,
+            },
+        )
+        return da
+
+    def _mesh_timeseries_outputs(
+        self, mesh_name: str, vars: List[TimeSeriesOutputVar]
+    ) -> xr.Dataset:
+        datasets = {}
+        for var in vars:
+            var_path = f"{self.UNSTEADY_TIME_SERIES_PATH}/2D Flow Areas/{mesh_name}/{var.value}"
+            if self.get(var_path) is None:
+                continue
+            da = self.mesh_timeseries_output(mesh_name, var)
+            datasets[var.value] = da
+        ds = xr.Dataset(datasets, attrs={"mesh_name": mesh_name})
+        return ds
+
+    def mesh_timeseries_output_cells(self, mesh_name: str) -> xr.Dataset:
+        """Return the time series output data for cells in a 2D flow area mesh.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+
+        Returns
+        -------
+        xr.Dataset
+            An xarray Dataset with DataArrays for each time series output variable.
+        """
+        ds = self._mesh_timeseries_outputs(mesh_name, TIME_SERIES_OUTPUT_VARS_CELLS)
+        return ds
+
+    def mesh_timeseries_output_faces(self, mesh_name: str) -> xr.Dataset:
+        """Return the time series output data for faces in a 2D flow area mesh.
+
+        Parameters
+        ----------
+        mesh_name : str
+            The name of the 2D flow area mesh.
+
+        Returns
+        -------
+        xr.Dataset
+            An xarray Dataset with DataArrays for each time series output variable.
+        """
+        ds = self._mesh_timeseries_outputs(mesh_name, TIME_SERIES_OUTPUT_VARS_FACES)
+        return ds
+
     def get_plan_info_attrs(self) -> Dict:
         """Return plan information attributes from a HEC-RAS HDF plan file.
 

rashdf/utils.py

@@ -10,6 +10,25 @@ from typing import Any, List, Tuple, Union, Optional
 from shapely import LineString, Polygon, polygonize_full
 
 
+def parse_ras_datetime_ms(datetime_str: str) -> datetime:
+    """Parse a datetime string with milliseconds from a RAS file into a datetime object.
+
+    If the datetime has a time of 2400, then it is converted to midnight of the next day.
+
+    Parameters
+    ----------
+        datetime_str (str): The datetime string to be parsed. The string should be in the format "ddMMMyyyy HH:mm:ss:fff".
+
+    Returns
+    -------
+        datetime: A datetime object representing the parsed datetime.
+    """
+    milliseconds = int(datetime_str[-3:])
+    microseconds = milliseconds * 1000
+    parsed_dt = parse_ras_datetime(datetime_str[:-4]).replace(microsecond=microseconds)
+    return parsed_dt
+
+
 def parse_ras_datetime(datetime_str: str) -> datetime:
     """Parse a datetime string from a RAS file into a datetime object.
 
@@ -266,3 +285,26 @@ def df_datetimes_to_str(df: pd.DataFrame) -> pd.DataFrame:
             lambda x: pd.Timestamp(x).isoformat() if pd.notnull(x) else None
         )
     return df_result
+
+
+def ras_timesteps_to_datetimes(
+    timesteps: np.ndarray, start_time: datetime, time_unit: str, round_to="0.1 s"
+) -> List[datetime]:
+    """
+    Convert an array of RAS timesteps into an array of datetime objects.
+
+    Parameters
+    ----------
+        timesteps (np.ndarray): An array of RAS timesteps.
+        start_time (datetime): The start time of the simulation.
+        time_unit (str): The time unit of the timesteps.
+        round_to (str): The time unit to round the datetimes to. (Default: "0.1 s")
+
+    Returns
+    -------
+        List[datetime]: A list of datetime objects corresponding to the timesteps.
+    """
+    return [
+        start_time + pd.Timedelta(timestep, unit=time_unit).round(round_to)
+        for timestep in timesteps.astype(np.float64)
+    ]

{rashdf-0.2.2.dist-info → rashdf-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rashdf
-Version: 0.2.2
+Version: 0.3.0
 Summary: Read data from HEC-RAS HDF files.
 Project-URL: repository, https://github.com/fema-ffrd/rashdf
 Classifier: Development Status :: 4 - Beta
@@ -16,6 +16,7 @@ License-File: LICENSE
 Requires-Dist: h5py
 Requires-Dist: geopandas
 Requires-Dist: pyarrow
+Requires-Dist: xarray
 Provides-Extra: dev
 Requires-Dist: pre-commit ; extra == 'dev'
 Requires-Dist: ruff ; extra == 'dev'

rashdf-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cli.py,sha256=dnTMEBid99xqorBFKZnUwOTDyTmIg08D83bSCkJ6104,5389
+rashdf/__init__.py,sha256=XXFtJDgLPCimqAhfsFz_pTWYECJiRT0i-Kb1uflXmVU,156
+rashdf/base.py,sha256=lHYVDwFTA1qFI34QYZ55QKcp7b8CeZsmDfESdkYISbg,2432
+rashdf/geom.py,sha256=Kf8e9u0U-dRi6lVcSPxPMeAYKwgZDIpNZ2o0Qu4WEJA,17609
+rashdf/plan.py,sha256=W4Q4yjneDEJSeubnMDUgQ7T12fcWDYPL0RDZrsmFZ0A,34556
+rashdf/utils.py,sha256=93arHtIT-iL9dIpbYr7esjrxv1uJabTRJSruyjvr8mw,10168
+rashdf-0.3.0.dist-info/LICENSE,sha256=L_0QaLpQVHPcglVjiaJPnOocwzP8uXevDRjUPr9DL1Y,1065
+rashdf-0.3.0.dist-info/METADATA,sha256=-5zzZFS6V4Uiv8pjpwznAXnPj1KpZPwuJpE6aOOXBtk,5658
+rashdf-0.3.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+rashdf-0.3.0.dist-info/entry_points.txt,sha256=LHHMR1lLy4wRyscMuW1RlYDXemtPgqQhNcILz0DtStY,36
+rashdf-0.3.0.dist-info/top_level.txt,sha256=SrmLb6FFTJtM_t6O1v0M0JePshiQJMHr0yYVkHL7ztk,11
+rashdf-0.3.0.dist-info/RECORD,,

rashdf-0.2.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-cli.py,sha256=QMTNosimfe95bQn2_ovLB98GeaQ0gwMTMA1rboMEknw,5119
-rashdf/__init__.py,sha256=XXFtJDgLPCimqAhfsFz_pTWYECJiRT0i-Kb1uflXmVU,156
-rashdf/base.py,sha256=lHYVDwFTA1qFI34QYZ55QKcp7b8CeZsmDfESdkYISbg,2432
-rashdf/geom.py,sha256=8bdATVPc_HxECA9evnwyL3nXC5YHEY78I3JpUUP4_xM,17597
-rashdf/plan.py,sha256=8xdDkAvk9sTrBlCcXepuNvGRbp0JjlyHdRMFN5PRiHE,2734
-rashdf/utils.py,sha256=yEZCm06KjpL8pebbW4MIDIcX2vHp-IzVXsKJGKznWBc,8703
-rashdf-0.2.2.dist-info/LICENSE,sha256=L_0QaLpQVHPcglVjiaJPnOocwzP8uXevDRjUPr9DL1Y,1065
-rashdf-0.2.2.dist-info/METADATA,sha256=4MuaGRrWegMZ4RVGtuYl6KjWpksteMTTj36gwAvGjCo,5636
-rashdf-0.2.2.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-rashdf-0.2.2.dist-info/entry_points.txt,sha256=LHHMR1lLy4wRyscMuW1RlYDXemtPgqQhNcILz0DtStY,36
-rashdf-0.2.2.dist-info/top_level.txt,sha256=SrmLb6FFTJtM_t6O1v0M0JePshiQJMHr0yYVkHL7ztk,11
-rashdf-0.2.2.dist-info/RECORD,,