SDG-265: implement calc-netcd command for Net Channel Depletion calculation

Author: dwr-psandhu

environment.yml

@@ -20,6 +20,7 @@ dependencies:
   - numba
   - diskcache
   - tabulate
+  - decorator
   # --- viz extras (pyproject.toml [project.optional-dependencies.viz]) ---
   - geopandas
   - shapely
@@ -29,5 +30,5 @@ dependencies:
   # --- conda-only / custom-channel packages ---
   - pyhecdss
   - vtools3
-  - pip:
-      - -e .        # installs pydsm itself in editable mode
+#  - pip:
+#      - -e .        # installs pydsm itself in editable mode

pydsm/cli.py

@@ -6,7 +6,8 @@
 from pydsm.functions import tsmath
 from pydsm.analysis import dssutils
 from pydsm.input import repeating_timeseries
-from pydsm.input import create_cd_inp
+from pydsm.input import dcd_calcs
+from pydsm.input.dcd_calcs import calc_netcd_cmd
 from pydsm.input import extend_dss_ts
 from pydsm.output.create_gtm_restart import write_gtm_restart
 from pydsm.input import channel_orient
@@ -348,7 +349,6 @@ def create_gtm_restart_cmd(tidefile, target_time, outfile, constituent):
 
 
 # Add the commands to the group repeating
-repeating.add_command(create_repeating)
 repeating.add_command(extend_repeating)
 # adding sub commands to main
 main.add_command(repeating)
@@ -365,5 +365,6 @@ def create_gtm_restart_cmd(tidefile, target_time, outfile, constituent):
 #
 main.add_command(extend_dss_ts.extend_dss_ts)
 main.add_command(channel_orient.generate_channel_orientation, "chan-orient")
+main.add_command(calc_netcd_cmd)
 if __name__ == "__main__":
     sys.exit(main())

pydsm/input/dcd_calcs.py

@@ -1,3 +1,4 @@
+import click
 import pandas as pd
 import pyhecdss as dss
 
@@ -6,6 +7,25 @@ def get_bpart_pattern():
     return '[0-9]+|BBID'
 
 
+def bparts_to_pattern(bparts):
+    """
+    Convert a list of B-part strings to a regex alternation pattern for DSS path matching.
+    Each B-part is wrapped in ^ and $ anchors so that e.g. '1' does not match '11' or '100'.
+    (pyhecdss uses pandas str.match which anchors the start but not the end.)
+
+    Parameters
+    ----------
+    bparts : list of str
+        List of B-part identifiers, e.g. ['BBID', '12345', '67890']
+
+    Returns
+    -------
+    str
+        Regex alternation string with full anchors, e.g. '^1$|^100$|^200$'
+    """
+    return '|'.join('^' + b + '$' for b in bparts)
+
+
 def get_dss_data(file, path_pattern):
     """
     returns a data frame of all the time series that match the path_pattern
@@ -71,3 +91,79 @@ def calculate_netcd(div_flows, drain_flows, seep_flows=None):
         return sum(div_flows) - sum(drain_flows)
     else:
         return sum(div_flows) + sum(seep_flows) - sum(drain_flows)
+
+
+@click.command(name="calc-netcd")
+@click.argument("dssfile", type=click.Path(exists=True))
+@click.option(
+    "--bpart",
+    multiple=True,
+    help="B-part to include (repeatable, e.g. --bpart BBID --bpart 12345)",
+)
+@click.option(
+    "--bpart-file",
+    type=click.Path(exists=True),
+    default=None,
+    help="Text file with one B-part per line",
+)
+@click.option(
+    "--no-seepage",
+    is_flag=True,
+    default=False,
+    help="Exclude seepage flows (NetCD = DIV - DRAIN only)",
+)
+@click.option(
+    "--epart",
+    default="1DAY",
+    show_default=True,
+    help="Time interval E-part (e.g. 1DAY, 1MON)",
+)
+@click.option(
+    "-o",
+    "--output",
+    default="netcd.csv",
+    show_default=True,
+    help="Output CSV file path",
+)
+def calc_netcd_cmd(dssfile, bpart, bpart_file, no_seepage, epart, output):
+    """Calculate aggregated Net Channel Depletion (NetCD) from a DSS file.
+
+    NetCD = DIV-FLOW - DRAIN-FLOW + SEEP-FLOW, summed over all matching B-parts.
+
+    B-parts can be supplied via --bpart (repeatable) and/or --bpart-file (one per line).
+    If neither is given, the default pattern matches all numeric node IDs and BBID.
+    """
+    bparts = list(bpart)
+    if bpart_file:
+        with open(bpart_file) as f:
+            bparts.extend(line.strip() for line in f if line.strip())
+
+    if bparts:
+        bpart_pattern = bparts_to_pattern(bparts)
+    else:
+        bpart_pattern = get_bpart_pattern()
+
+    try:
+        div_flows = get_dss_data(dssfile, f"//({bpart_pattern})/DIV-FLOW//{epart}//")
+    except Exception as e:
+        raise click.ClickException(f"No DIV-FLOW data found for the specified B-parts: {e}")
+
+    try:
+        drain_flows = get_dss_data(dssfile, f"//({bpart_pattern})/DRAIN-FLOW//{epart}//")
+    except Exception as e:
+        raise click.ClickException(f"No DRAIN-FLOW data found for the specified B-parts: {e}")
+
+    seep_flows = None
+    if not no_seepage:
+        try:
+            seep_flows = get_dss_data(dssfile, f"//({bpart_pattern})/SEEP-FLOW//{epart}//")
+        except Exception:
+            click.echo(
+                "Warning: No SEEP-FLOW data found for the specified B-parts. "
+                "Proceeding without seepage (NetCD = DIV - DRAIN).",
+                err=True,
+            )
+
+    netcd = calculate_netcd(div_flows, drain_flows, seep_flows)
+    netcd.to_csv(output, header=["NETCD"])
+    click.echo(f"NetCD written to {output}")

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
     "numba",
     "diskcache",
     "tabulate",
+    "decorator",
 ]
 dynamic = ["version"]