rashdf 0.9.0__tar.gz → 0.11.0__tar.gz

{rashdf-0.9.0 → rashdf-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rashdf
-Version: 0.9.0
+Version: 0.11.0
 Summary: Read data from HEC-RAS HDF files.
 Project-URL: repository, https://github.com/fema-ffrd/rashdf
 Classifier: Development Status :: 4 - Beta
@@ -17,6 +17,7 @@ Requires-Dist: h5py
 Requires-Dist: geopandas<2.0,>=1.0
 Requires-Dist: pyarrow
 Requires-Dist: xarray<=2025.4.0
+Requires-Dist: pandas<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -29,6 +30,7 @@ Requires-Dist: fsspec; extra == "dev"
 Requires-Dist: s3fs; extra == "dev"
 Requires-Dist: fiona==1.9.6; extra == "dev"
 Requires-Dist: numcodecs<0.16; extra == "dev"
+Requires-Dist: rioxarray; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"

{rashdf-0.9.0 → rashdf-0.11.0}/pyproject.toml

@@ -12,8 +12,14 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
-version = "0.9.0"
-dependencies = ["h5py", "geopandas>=1.0,<2.0", "pyarrow", "xarray<=2025.4.0"]
+version = "0.11.0"
+dependencies = [
+    "h5py",
+    "geopandas>=1.0,<2.0",
+    "pyarrow",
+    "xarray<=2025.4.0",
+    "pandas>=2.0,<3.0"
+]
 
 [project.optional-dependencies]
 dev = [
@@ -27,7 +33,8 @@ dev = [
     "fsspec",
     "s3fs",
     "fiona==1.9.6",
-    "numcodecs<0.16"
+    "numcodecs<0.16",
+    "rioxarray",
 ]
 docs = ["sphinx", "numpydoc", "sphinx_rtd_theme"]
 

{rashdf-0.9.0 → rashdf-0.11.0}/src/rashdf/geom.py

@@ -150,13 +150,13 @@ class RasGeomHdf(RasHdf):
             ][()][:, 0]
             face_id_lists = list(
                 np.vectorize(
-                    lambda cell_id,
-                    cell_face_values=cell_face_values,
-                    cell_face_info=cell_face_info: str(
-                        cell_face_values[
-                            cell_face_info[cell_id][0] : cell_face_info[cell_id][0]
-                            + cell_face_info[cell_id][1]
-                        ]
+                    lambda cell_id, cell_face_values=cell_face_values, cell_face_info=cell_face_info: (
+                        str(
+                            cell_face_values[
+                                cell_face_info[cell_id][0] : cell_face_info[cell_id][0]
+                                + cell_face_info[cell_id][1]
+                            ]
+                        )
                     )
                 )(cell_ids)
             )

{rashdf-0.9.0 → rashdf-0.11.0}/src/rashdf/plan.py

@@ -4,6 +4,7 @@ from .geom import RasGeomHdf
 from .utils import (
     df_datetimes_to_str,
     ras_timesteps_to_datetimes,
+    parse_ras_datetime,
     parse_ras_datetime_ms,
     deprecated,
     convert_ras_hdf_value,
@@ -18,7 +19,7 @@ import xarray as xr
 
 from datetime import datetime
 from enum import Enum
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Dict, List, Optional, Tuple, Union, Sequence
 
 # Shared constant
 WATER_SURFACE = "Water Surface"
@@ -1779,3 +1780,213 @@ class RasPlanHdf(RasGeomHdf):
         """
         ds = self.reference_points_timeseries_output()
         return self._zmeta(ds)
+
+    def reference_lines_flow(self, use_names: bool = False) -> DataFrame:
+        """Return wide-format DataFrame for reference lines timeseries flow data.
+
+        Parameters
+        ----------
+        use_names : bool, optional
+            (Default) If False, use reference line IDs as column headers.
+            If True, use reference line names as column headers.
+
+        Returns
+        -------
+        DataFrame
+            Wide-format DataFrame with time as index and reference line IDs (or names) as columns.
+        """
+        ds = self.reference_lines_timeseries_output()
+        return self._timeseries_to_wide_dataframe(
+            ds=ds,
+            var="Flow",
+            id_column="refln_id",
+            name_column="refln_name",
+            mesh_column="mesh_name",
+            use_names_as_col=use_names,
+        )
+
+    def reference_points_stage(self, use_names: bool = False) -> DataFrame:
+        """Return Wide-format DataFrame for reference points timeseries stage data.
+
+        Parameters
+        ----------
+        use_names : bool, optional
+            (Default) If False, use reference point IDs as column headers.
+            If True, use reference point names as column headers.
+
+        Returns
+        -------
+        DataFrame
+            Wide-format DataFrame with time as index and reference point IDs (or names) as columns.
+        """
+        ds = self.reference_points_timeseries_output()
+        return self._timeseries_to_wide_dataframe(
+            ds=ds,
+            var=WATER_SURFACE,
+            id_column="refpt_id",
+            name_column="refpt_name",
+            mesh_column="mesh_name",
+            use_names_as_col=use_names,
+        )
+
+    def bc_lines_flow(self, use_names: bool = False) -> DataFrame:
+        """Return wide-format DataFrame for boundary condition lines timeseries flow data with.
+
+        Parameters
+        ----------
+        use_names : bool, optional
+            (Default) If False, use BC line IDs as column headers.
+            If True, use BC line names as column headers.
+
+        Returns
+        -------
+        DataFrame
+            Wide-format DataFrame with time as index and BC line IDs (or names) as columns.
+        """
+        ds = self.bc_lines_timeseries_output()
+        return self._timeseries_to_wide_dataframe(
+            ds=ds,
+            var="Flow",
+            id_column="bc_line_id",
+            name_column="bc_line_name",
+            mesh_column="mesh_name",
+            use_names_as_col=use_names,
+        )
+
+    def _timeseries_to_wide_dataframe(
+        self,
+        ds: xr.Dataset,
+        var: str,
+        id_column: str,
+        name_column: str,
+        mesh_column: str,
+        use_names_as_col: bool = False,
+    ) -> DataFrame:
+        """Convert xarray timeseries Dataset to wide-format DataFrame with metadata.
+
+        Parameters
+        ----------
+        ds : xr.Dataset
+            xarray Dataset containing timeseries data
+        var : str
+            Variable name to extract (e.g. "Flow", "Water Surface")
+        id_column : str
+            ID column name for pivoting (e.g. "refln_id", "refpt_id", "bc_line_id")
+        name_column : str
+            Name column for creating readable column names (e.g. "refln_name", "refpt_name")
+        mesh_column : str
+            Mesh column name (e.g. "mesh_name")
+        use_names_as_col : bool, optional
+            (Default) If False, use IDs.
+            If True, use names as column headers.
+
+        Returns
+        -------
+        DataFrame
+            Wide-format DataFrame with time as index and IDs or names as columns.
+            Metadata stored in DataFrame.attrs including name and mesh mappings.
+        """
+        if var not in ds:
+            raise ValueError(f"{var} data not found in timeseries output")
+
+        df = ds[var].to_dataframe().dropna().reset_index()
+
+        # check for duplicate names when using names as columns
+        if use_names_as_col:
+            unique_names = df[name_column].nunique()
+            unique_ids = df[id_column].nunique()
+            if unique_names < unique_ids:  # should have one name for every one id
+                name_counts = (
+                    df[[id_column, name_column]]
+                    .drop_duplicates()[name_column]
+                    .value_counts()
+                )
+                duplicates = name_counts[name_counts > 1].index.tolist()
+                raise ValueError(
+                    f"Cannot use names as columns. The following names are not unique: {duplicates}. "
+                )
+
+        pivot_column = name_column if use_names_as_col else id_column
+        wide_df = df.pivot(index="time", columns=pivot_column, values=var)
+
+        lookup = df[[id_column, name_column, mesh_column]].drop_duplicates()
+        if use_names_as_col:
+            # when using names as columns, key=name -> value=id
+            id_mapping = lookup.set_index(name_column)[id_column].to_dict()
+            mesh_mapping = lookup.set_index(name_column)[mesh_column].to_dict()
+        else:
+            # when using IDs as columns, key=id -> value=name
+            id_mapping = lookup.set_index(id_column)[name_column].to_dict()
+            mesh_mapping = lookup.set_index(id_column)[mesh_column].to_dict()
+
+        wide_df.attrs = {
+            "variable": var,
+            "units": ds[var].attrs.get("units", None),
+            "hdf_path": ds[var].attrs.get("hdf_path", None),
+            "id_mapping": id_mapping,
+            "mesh_mapping": mesh_mapping,
+        }
+
+        return wide_df
+
+    def gridded_precip(
+        self,
+        timestamps: Optional[Union[Sequence[datetime], pd.Series]] = None,
+        precip_attrs: Optional[Dict] = None,
+    ) -> xr.DataArray:
+        """Return precipitation timeseries input data from a HEC-RAS HDF plan file.
+
+        Requires the 'rioxarray' package.
+
+        Parameters
+        ----------
+        timestamps : Optional[Union[Sequence[datetime], pd.Series]], optional
+            Optional sequence of timestamps to use for the time coordinate. If None, timestamps will be read from the HDF file.
+        precip_attrs : Optional[Dict], optional
+            Optional dictionary of precipitation attributes. If None, attributes will be read from the HDF file.
+
+        Returns
+        -------
+        xr.DataArray
+            An xarray DataArray with precipitation timeseries input data.
+        """
+        import rioxarray
+
+        precip_group = self[self.PRECIP_PATH]
+        precip_values: h5py.Dataset = precip_group["Values"]
+        if timestamps is None:
+            ds_timestamps: h5py.Dataset = precip_group["Timestamp"]
+            timestamps = pd.Series(ds_timestamps.asstr()[:]).map(parse_ras_datetime)
+        if precip_attrs is None:
+            precip_attrs = self.get_meteorology_precip_attrs()
+        crs = precip_attrs.get("Projection")
+        rows = precip_attrs.get("Raster Rows")
+        cols = precip_attrs.get("Raster Cols")
+        top = precip_attrs.get("Raster Top")
+        left = precip_attrs.get("Raster Left")
+        cell_size = precip_attrs.get("Raster Cellsize")
+        if not all([rows, cols, top, left, cell_size]):
+            raise RasPlanHdfError(
+                "Precipitation raster metadata is missing or incomplete."
+            )
+
+        precip_values: np.ndarray = precip_values[:]
+        precip_values = precip_values.reshape(precip_values.shape[0], rows, cols)
+        x_coords = left + np.arange(cols) * cell_size + cell_size / 2
+        y_coords = top - np.arange(rows) * cell_size - cell_size / 2
+        precip = xr.DataArray(
+            precip_values,
+            name="Precipitation",
+            dims=["time", "y", "x"],
+            coords={
+                "time": timestamps,
+                "y": y_coords,
+                "x": x_coords,
+            },
+            attrs={
+                "units": precip_attrs.get("Units"),
+                "hdf_path": f"{self.PRECIP_PATH}/Values",
+            },
+        )
+        precip = precip.rio.write_crs(crs)
+        return precip

{rashdf-0.9.0 → rashdf-0.11.0}/src/rashdf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rashdf
-Version: 0.9.0
+Version: 0.11.0
 Summary: Read data from HEC-RAS HDF files.
 Project-URL: repository, https://github.com/fema-ffrd/rashdf
 Classifier: Development Status :: 4 - Beta
@@ -17,6 +17,7 @@ Requires-Dist: h5py
 Requires-Dist: geopandas<2.0,>=1.0
 Requires-Dist: pyarrow
 Requires-Dist: xarray<=2025.4.0
+Requires-Dist: pandas<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -29,6 +30,7 @@ Requires-Dist: fsspec; extra == "dev"
 Requires-Dist: s3fs; extra == "dev"
 Requires-Dist: fiona==1.9.6; extra == "dev"
 Requires-Dist: numcodecs<0.16; extra == "dev"
+Requires-Dist: rioxarray; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"

{rashdf-0.9.0 → rashdf-0.11.0}/src/rashdf.egg-info/requires.txt

@@ -2,6 +2,7 @@ h5py
 geopandas<2.0,>=1.0
 pyarrow
 xarray<=2025.4.0
+pandas<3.0,>=2.0
 
 [dev]
 pre-commit
@@ -15,6 +16,7 @@ fsspec
 s3fs
 fiona==1.9.6
 numcodecs<0.16
+rioxarray
 
 [docs]
 sphinx

{rashdf-0.9.0 → rashdf-0.11.0}/tests/test_plan.py

@@ -748,3 +748,109 @@ def test_bc_lines_include_output_true():
             plan_hdf.bc_lines(include_output=True, datetime_to_str=True),
             bc_lines_with_output_json,
         )
+
+
+def test_reference_lines_flow(tmp_path: Path):
+    plan_hdf = RasPlanHdf(BALD_EAGLE_P18_REF)
+    df = plan_hdf.reference_lines_flow()
+
+    assert df.index.name == "time"
+    assert df.shape == (37, 4)
+    assert list(df.columns) == [0, 1, 2, 3]
+
+    # Check metadata
+    assert df.attrs["variable"] == "Flow"
+    assert df.attrs["units"] == "cfs"
+
+    # Check mappings
+    assert "id_mapping" in df.attrs
+    assert len(df.attrs["id_mapping"]) == 4
+    assert "mesh_mapping" in df.attrs
+    assert len(df.attrs["mesh_mapping"]) == 4
+
+    df_refln2 = df[2].to_frame(name="Flow")
+    valid_df = pd.read_csv(
+        TEST_CSV / "BaldEagleDamBrk.reflines.2.csv",
+        index_col="time",
+        parse_dates=True,
+        usecols=["time", "Flow"],
+        dtype={"Flow": np.float32},
+    )
+    assert_frame_equal(df_refln2, valid_df, check_dtype=False)
+
+
+def test_reference_points_stage(tmp_path: Path):
+    plan_hdf = RasPlanHdf(BALD_EAGLE_P18_REF)
+    df = plan_hdf.reference_points_stage()
+
+    assert df.index.name == "time"
+    assert df.shape == (37, 3)
+    assert list(df.columns) == [0, 1, 2]
+
+    # Check metadata
+    assert df.attrs["variable"] == "Water Surface"
+    assert df.attrs["units"] == "ft"
+
+    # Check mappings
+    assert "id_mapping" in df.attrs
+    assert len(df.attrs["id_mapping"]) == 3
+    assert "mesh_mapping" in df.attrs
+    assert len(df.attrs["mesh_mapping"]) == 3
+
+    df_refpt1 = df[1].to_frame(name="Water Surface")
+    valid_df = pd.read_csv(
+        TEST_CSV / "BaldEagleDamBrk.refpoints.1.csv",
+        index_col="time",
+        parse_dates=True,
+        usecols=["time", "Water Surface"],
+        dtype={"Water Surface": np.float32},
+    )
+    assert_frame_equal(df_refpt1, valid_df, check_dtype=False)
+
+
+def test_bc_lines_flow(tmp_path: Path):
+    plan_hdf = RasPlanHdf(LOWER_KANAWHA_P01_BC_LINES)
+    df = plan_hdf.bc_lines_flow()
+
+    assert df.index.name == "time"
+    assert df.shape == (577, 10)
+
+    # Check metadata
+    assert df.attrs["variable"] == "Flow"
+    assert df.attrs["units"] == "cfs"
+
+    # Check mappings
+    assert "id_mapping" in df.attrs
+    assert len(df.attrs["id_mapping"]) == 10
+    assert "mesh_mapping" in df.attrs
+    assert len(df.attrs["mesh_mapping"]) == 10
+
+    df_bcline7 = df[7].to_frame(name="Flow")
+    valid_df = pd.read_csv(
+        TEST_CSV / "LowerKanawha.p01.bclines.7.csv",
+        index_col="time",
+        parse_dates=True,
+        usecols=["time", "Flow"],
+        dtype={"Flow": np.float32},
+    )
+    assert_frame_equal(df_bcline7, valid_df, check_dtype=False)
+
+
+def test_gridded_precip():
+    plan_hdf = RasPlanHdf(TEST_DATA / "ras/ElkMiddle.gridded-precip.p01.hdf")
+    precip = plan_hdf.gridded_precip()
+    assert precip.shape == (24, 160, 110)
+    assert (
+        precip.attrs["units"]
+        == plan_hdf["/Event Conditions/Meteorology/Precipitation"]
+        .attrs["Units"]
+        .decode()
+    )
+
+
+def test_gridded_precip_bad_precip_attrs():
+    plan_hdf = RasPlanHdf(TEST_DATA / "ras/ElkMiddle.gridded-precip.p01.hdf")
+    precip_attrs = plan_hdf.get_meteorology_precip_attrs()
+    precip_attrs.pop("Raster Rows")
+    with pytest.raises(RasPlanHdfError):
+        plan_hdf.gridded_precip(precip_attrs=precip_attrs)