Lint river module (#389)

This PR adds pylint enforcement to the MHKiT river module. 
Additionally this PR adds type hints to the river module functions.
Part of #275

Author: ssolson

.github/workflows/pylint.yml

@@ -37,6 +37,10 @@ jobs:
         run: |
           pylint mhkit/acoustics/
 
-      - name: Run Pylint on mhkit/tidal
+      - name: Run Pylint on mhkit/tidal/
         run: |
           pylint mhkit/tidal/
+
+      - name: Run Pylint on mhkit/river/
+        run: |
+          pylint --extension-pkg-allow-list=netCDF4 mhkit/river/

examples/ADCP_Delft3D_TRTS_example.ipynb

@@ -1,3 +1,8 @@
+"""
+The river module provides tools and utilities for analyzing river energy resources.
+
+"""
+
 from mhkit.river import performance
 from mhkit.river import graphics
 from mhkit.river import resource

examples/river_example.ipynb

@@ -1,10 +1,29 @@
+"""
+The graphics module provides plotting utilities for river energy resource data.
+
+"""
+
+from typing import Union, Optional
 import numpy as np
 import xarray as xr
 import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from numpy.typing import ArrayLike
 from mhkit.utils import convert_to_dataarray
 
 
-def _xy_plot(x, y, fmt=".", label=None, xlabel=None, ylabel=None, title=None, ax=None):
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+def _xy_plot(
+    x: ArrayLike,
+    y: ArrayLike,
+    fmt: str = ".",
+    label: Optional[str] = None,
+    xlabel: Optional[str] = None,
+    ylabel: Optional[str] = None,
+    title: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Base function to plot any x vs y data
 
@@ -50,16 +69,21 @@ def _xy_plot(x, y, fmt=".", label=None, xlabel=None, ylabel=None, title=None, ax
     return ax
 
 
-def plot_flow_duration_curve(D, F, label=None, ax=None):
+def plot_flow_duration_curve(
+    discharge: Union[ArrayLike, xr.DataArray],
+    exceedance_prob: Union[ArrayLike, xr.DataArray],
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots discharge vs exceedance probability as a Flow Duration Curve (FDC)
 
     Parameters
     ------------
-    D: array-like
-        Discharge [m/s] indexed by time
+    discharge: array-like
+        Discharge [m3/s] indexed by time
 
-    F: array-like
+    exceedance_prob: array-like
          Exceedance probability [unitless] indexed by time
 
     label: string
@@ -74,13 +98,15 @@ def plot_flow_duration_curve(D, F, label=None, ax=None):
     ax : matplotlib pyplot axes
 
     """
-    # Sort by F
-    temp = xr.Dataset(data_vars={"D": D, "F": F})
-    temp = temp.sortby("F", ascending=False)
+    # Sort by exceedance_prob
+    temp = xr.Dataset(
+        data_vars={"discharge": discharge, "exceedance_prob": exceedance_prob}
+    )
+    temp = temp.sortby("exceedance_prob", ascending=False)
 
     ax = _xy_plot(
-        temp["D"],
-        temp["F"],
+        temp["discharge"],
+        temp["exceedance_prob"],
         fmt="-",
         label=label,
         xlabel="Discharge [$m^3/s$]",
@@ -92,16 +118,21 @@ def plot_flow_duration_curve(D, F, label=None, ax=None):
     return ax
 
 
-def plot_velocity_duration_curve(V, F, label=None, ax=None):
+def plot_velocity_duration_curve(
+    velocity: Union[ArrayLike, xr.DataArray],
+    exceedance_prob: Union[ArrayLike, xr.DataArray],
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)
 
     Parameters
     ------------
-    V: array-like
+    velocity: array-like
         Velocity [m/s] indexed by time
 
-    F: array-like
+    exceedance_prob: array-like
         Exceedance probability [unitless] indexed by time
 
     label: string
@@ -116,13 +147,15 @@ def plot_velocity_duration_curve(V, F, label=None, ax=None):
     ax : matplotlib pyplot axes
 
     """
-    # Sort by F
-    temp = xr.Dataset(data_vars={"V": V, "F": F})
-    temp = temp.sortby("F", ascending=False)
+    # Sort by exceedance_prob
+    temp = xr.Dataset(
+        data_vars={"velocity": velocity, "exceedance_prob": exceedance_prob}
+    )
+    temp = temp.sortby("exceedance_prob", ascending=False)
 
     ax = _xy_plot(
-        temp["V"],
-        temp["F"],
+        temp["velocity"],
+        temp["exceedance_prob"],
         fmt="-",
         label=label,
         xlabel="Velocity [$m/s$]",
@@ -133,16 +166,21 @@ def plot_velocity_duration_curve(V, F, label=None, ax=None):
     return ax
 
 
-def plot_power_duration_curve(P, F, label=None, ax=None):
+def plot_power_duration_curve(
+    power: Union[ArrayLike, xr.DataArray],
+    exceedance_prob: Union[ArrayLike, xr.DataArray],
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots power vs exceedance probability as a Power Duration Curve (PDC)
 
     Parameters
     ------------
-    P: array-like
+    power: array-like
         Power [W] indexed by time
 
-    F: array-like
+    exceedance_prob: array-like
         Exceedance probability [unitless] indexed by time
 
     label: string
@@ -157,13 +195,13 @@ def plot_power_duration_curve(P, F, label=None, ax=None):
     ax : matplotlib pyplot axes
 
     """
-    # Sort by F
-    temp = xr.Dataset(data_vars={"P": P, "F": F})
-    temp.sortby("F", ascending=False)
+    # Sort by exceedance_prob
+    temp = xr.Dataset(data_vars={"power": power, "exceedance_prob": exceedance_prob})
+    temp.sortby("exceedance_prob", ascending=False)
 
     ax = _xy_plot(
-        temp["P"],
-        temp["F"],
+        temp["power"],
+        temp["exceedance_prob"],
         fmt="-",
         label=label,
         xlabel="Power [W]",
@@ -174,13 +212,18 @@ def plot_power_duration_curve(P, F, label=None, ax=None):
     return ax
 
 
-def plot_discharge_timeseries(Q, time_dimension="", label=None, ax=None):
+def plot_discharge_timeseries(
+    discharge: Union[ArrayLike, xr.DataArray],
+    time_dimension: str = "",
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots discharge time-series
 
     Parameters
     ------------
-    Q: array-like
+    discharge: array-like
         Discharge [m3/s] indexed by time
 
     time_dimension: string (optional)
@@ -199,14 +242,14 @@ def plot_discharge_timeseries(Q, time_dimension="", label=None, ax=None):
     ax : matplotlib pyplot axes
 
     """
-    Q = convert_to_dataarray(Q)
+    discharge = convert_to_dataarray(discharge)
 
     if time_dimension == "":
-        time_dimension = list(Q.coords)[0]
+        time_dimension = list(discharge.coords)[0]
 
     ax = _xy_plot(
-        Q.coords[time_dimension].values,
-        Q,
+        discharge.coords[time_dimension].values,
+        discharge,
         fmt="-",
         label=label,
         xlabel="Time",
@@ -217,16 +260,22 @@ def plot_discharge_timeseries(Q, time_dimension="", label=None, ax=None):
     return ax
 
 
-def plot_discharge_vs_velocity(D, V, polynomial_coeff=None, label=None, ax=None):
+def plot_discharge_vs_velocity(
+    discharge: Union[ArrayLike, xr.DataArray],
+    velocity: Union[ArrayLike, xr.DataArray],
+    polynomial_coeff: Optional[np.poly1d] = None,
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots discharge vs velocity data along with the polynomial fit
 
     Parameters
     ------------
-    D : array-like
-        Discharge [m/s] indexed by time
+    discharge : array-like
+        Discharge [m3/s] indexed by time
 
-    V : array-like
+    velocity : array-like
         Velocity [m/s] indexed by time
 
     polynomial_coeff: numpy polynomial
@@ -244,16 +293,16 @@ def plot_discharge_vs_velocity(D, V, polynomial_coeff=None, label=None, ax=None)
 
     """
     ax = _xy_plot(
-        D,
-        V,
+        discharge,
+        velocity,
         fmt=".",
         label=label,
         xlabel="Discharge [$m^3/s$]",
         ylabel="Velocity [$m/s$]",
         ax=ax,
     )
     if polynomial_coeff:
-        x = np.linspace(D.min(), D.max())
+        x = np.linspace(discharge.min(), discharge.max())
         ax = _xy_plot(
             x,
             polynomial_coeff(x),
@@ -267,16 +316,22 @@ def plot_discharge_vs_velocity(D, V, polynomial_coeff=None, label=None, ax=None)
     return ax
 
 
-def plot_velocity_vs_power(V, P, polynomial_coeff=None, label=None, ax=None):
+def plot_velocity_vs_power(
+    velocity: Union[ArrayLike, xr.DataArray],
+    power: Union[ArrayLike, xr.DataArray],
+    polynomial_coeff: Optional[np.poly1d] = None,
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+) -> Axes:
     """
     Plots velocity vs power data along with the polynomial fit
 
     Parameters
     ------------
-    V : array-like
+    velocity : array-like
         Velocity [m/s] indexed by time
 
-    P: array-like
+    power: array-like
         Power [W] indexed by time
 
     polynomial_coeff: numpy polynomial
@@ -294,16 +349,16 @@ def plot_velocity_vs_power(V, P, polynomial_coeff=None, label=None, ax=None):
 
     """
     ax = _xy_plot(
-        V,
-        P,
+        velocity,
+        power,
         fmt=".",
         label=label,
         xlabel="Velocity [$m/s$]",
         ylabel="Power [$W$]",
         ax=ax,
     )
     if polynomial_coeff:
-        x = np.linspace(V.min(), V.max())
+        x = np.linspace(velocity.min(), velocity.max())
         ax = _xy_plot(
             x,
             polynomial_coeff(x),

mhkit/river/__init__.py

@@ -1,2 +1,7 @@
+"""
+This module provides input/output functionality for river energy related data in MHKiT.
+
+"""
+
 from mhkit.river.io import usgs
 from mhkit.river.io import d3d