Update API reference descriptions for plotting

docs/source/examples/cumulative_hydrograph_examples.rst

@@ -2,8 +2,7 @@
 Cumulative Streamflow Hydrographs
 ---------------------------------
 
-The following examples show how to fetch some data, and then calculate values for a cumulative streamflow hydrograph.
-Then an example plotting routine to plot the cumulative hydrograph is shown.
+The following examples show how to fetch data and calculate values for a cumulative streamflow hydrograph before plotting the cumulative hydrograph using the `hyswap` :obj:`hyswap.plots.plot_cumulative_hydrograph` function.
 
 
 Cumulative Streamflow Over The 2020 Water Year
@@ -30,8 +29,7 @@ Now we can calculate the cumulative streamflow values per year using the :obj:`h
     cdf = hyswap.cumulative.calculate_daily_cumulative_values(
         df, '00060_Mean', year_type='water')
 
-Then we can plot the cumulative streamflow hydrograph using the
-:obj:`hyswap.plots.plot_cumulative_hydrograph` function.
+Then we can plot the cumulative streamflow hydrograph. 
 
 .. plot::
     :context:

docs/source/examples/flow_duration_curve_examples.rst

@@ -44,7 +44,7 @@ Now we can calculate the exceedance probabilities for 10,000 evenly spaced value
     exceedance_probabilities = hyswap.exceedance.calculate_exceedance_probability_from_values_multiple(
         values, df['00060_Mean'])
 
-Finally, we can plot the flow duration curve using these exceedance probability values and `matplotlib`.
+Finally, we can plot the flow duration curve using these exceedance probability values and :obj:`hyswap.plots.plot_flow_duration_curve`, which leverages `matplotlib`.
 
 .. plot::
     :context:

docs/source/examples/raster_hydrograph_examples.rst

@@ -29,7 +29,7 @@ raster hydrograph.
     # format the data
     df_formatted = hyswap.rasterhydrograph.format_data(df, '00060_Mean')
 
-Now the data is arranged with years on the index (rows) and days of the year as columns, this makes it easy to plot as a raster hydrograph.
+Now the data is arranged with years on the index (rows) and days of the year as columns, this makes it easy to plot as a raster hydrograph with :obj:`hyswap.plots.plot_raster_hydrograph`.
 
 .. plot::
     :context:

docs/source/examples/streamflow_duration_hydrograph_examples.rst

@@ -2,8 +2,7 @@
 Streamflow Duration Hydrographs
 -------------------------------
 
-These examples show how a streamflow hydrograph can be constructed by fetching historical streamflow data from NWIS using `dataretrieval`, and then calculating daily percentiles of streamflow for each day of the year.
-The resulting hydrographs show the streamflow values for all of 2022 plotted on top of the historical percentiles which are shown as shaded regions.
+These examples show how a streamflow hydrograph can be constructed by fetching historical streamflow data from a single NWIS gage using `dataretrieval`, calculating daily percentiles of streamflow for each day of the year for the year 2022, and plotting these data using the `hyswap` function :obj:`hyswap.plots.plot_duration_hydrograph`. 
 
 
 Calculating Percentiles Using `hyswap`

hyswap/exceedance.py

@@ -84,13 +84,13 @@ def calculate_exceedance_probability_from_values(x, values_to_compare,
     determining the number that are *greater than or equal to* the
     input value (x), which provides the minimum rank in the case of tied
     values. Additional methods other than the 'Weibull' method can be specified
-    and are described in more detail in [1]_.
+    and are described in more detail in Helsel et al 2020.
 
-    .. [1] Helsel, D.R., Hirsch, R.M., Ryberg, K.R., Archfield, S.A., and
-    Gilroy, E.J., 2020, Statistical methods in water resources: U.S. Geological
-    Survey Techniques and Methods, book 4, chap. A3, 458 p.,
-    https://doi.org/10.3133/tm4a3. [Supersedes USGS Techniques of
-    Water-Resources Investigations, book 4, chap. A3, version 1.1.]
+    Helsel, D.R., Hirsch, R.M., Ryberg, K.R., Archfield, S.A.,
+      and Gilroy, E.J., 2020, Statistical methods in water resources:
+      U.S. Geological Survey Techniques and Methods, book 4, chap. A3,
+      458 p., https://doi.org/10.3133/tm4a3. [Supersedes USGS Techniques
+      of Water-Resources Investigations, book 4, chap. A3, version 1.1.]
 
     Parameters
     ----------

hyswap/plots.py

@@ -1,4 +1,4 @@
-"""Functions to make plots."""
+"""Functions for plotting."""
 import calendar
 import numpy as np
 import matplotlib
@@ -14,8 +14,11 @@ def plot_flow_duration_curve(
         '(Percentage of time indicated value was equaled or exceeded)',
         ylab='Discharge, in Cubic Feet per Second', grid=True,
         scatter_kwargs={}, **kwargs):
-    """
-    Make flow duration curve plot.
+    """ Plot a flow duration curve.
+
+    Flow duration curves are cumulative frequency curves that show the
+    percentage of time measured discharge values are equaled or exceeded
+    by all other discharge values in the dataset.
 
     Parameters
     ----------
@@ -125,7 +128,31 @@ def plot_raster_hydrograph(df_formatted, ax=None,
                            xlab='Month', ylab='Year',
                            cbarlab='Discharge, in Cubic Feet per Second',
                            **kwargs):
-    """Make raster hydrograph plot.
+    """Plot a raster hydrograph.
+
+    Raster hydrographs are pixel-based plots for visualizing and identifying
+    variations and changes in large multidimensional data sets. Originally
+    developed by Keim (2000), they were first applied in hydrology by
+    Koehler (2004) as a means of highlighting inter-annual and intra-annual
+    changes in streamflow. The raster hydrographs in hyswap, like those
+    developed by Koehler, depict years on the y-axis and days along the
+    x-axis. Users can choose to plot streamflow (actual values or log values),
+    streamflow percentile, or streamflow class (from 1, for low flow, to 7
+    for high flow), for Daily, 7-Day, 14-Day, and 28-Day streamflow. For a
+    more comprehensive description of raster hydrographs, see Strandhagen
+    et al. (2006).
+
+    References:
+    Keim, D.A. 2000. Designing pixel-oriented visualization techniques:
+    theory and applications. IEEE Transactions on Visualization and
+    Computer Graphics, 6(1), 59-78.
+
+    Koehler, R. 2004. Raster Based Analysis and Visualization of Hydrologic
+    Time Series. Ph.D  dissertation, University of Arizona. Tucson, AZ, 189 p.
+
+    Strandhagen, E., Marcus, W.A., and Meacham, J.E. 2006. Views of the
+    rivers: representing streamflow of the greater Yellowstone ecosystem.
+    Cartographic Perspectives, no. 55, Fall.
 
     Parameters
     ----------
@@ -238,7 +265,18 @@ def plot_duration_hydrograph(percentiles_by_day, df, data_col, doy_col,
                              title="Duration Hydrograph",
                              ylab="Discharge, in Cubic Feet per Second",
                              xlab="Month", colors=None, **kwargs):
-    """Make duration hydrograph plot.
+    """Plot a duration hydrograph.
+
+    The duration hydrograph is a graphical presentation of recent daily
+    streamflow (discharge) observed at an individual USGS streamgage,
+    plotted over the long-term statistics of streamflow for each day of
+    the year at that station. Typically, the statistics (based on quality
+    assured and approved data) include the maximum discharge recorded during
+    the period of record for each day of the year; the 90th percentile flow
+    for each day; the interquartile range (75th percentile on top and 25th
+    percentile on the bottom); the 10th percentile flow for each day; and the
+    minimum discharge recorded for each day. This function, however, allows
+    the user to plot a custom list of percentiles.
 
     Parameters
     ----------
@@ -372,7 +410,16 @@ def plot_cumulative_hydrograph(cumulative_percentiles, target_years,
                                title="Cumulative Streamflow Hydrograph",
                                ylab="Cumulative Streamflow, in Cubic Feet",
                                xlab="Month", **kwargs):
-    """Make cumulative hydrograph plot.
+    """Plot a cumulative hydrograph.
+
+    The cumulative-streamflow hydrograph is a graphical presentation of
+    recent cumulative daily streamflow (discharge) observed at an
+    individual USGS streamgage, plotted over the long-term statistics
+    of streamflow for each day of the year at that station. Typically,
+    the statistics, based on quality assured and approved data, include
+    the maximum annual cumulative discharge recorded during the period
+    of record; the mean-daily cumulative flow for each day; the minimum
+    cumulative discharge during recorded for each day.
 
     Parameters
     ----------
@@ -521,7 +568,9 @@ def plot_hydrograph(df, data_col,
                     xlab='Date',
                     yscale='log',
                     **kwargs):
-    """Plot a hydrograph.
+    """Plot a simple hydrograph.
+
+    Hydrographs show the streamflow discharge over time at a single station.
 
     Parameters
     ----------
@@ -620,7 +669,12 @@ def plot_hydrograph(df, data_col,
 def plot_similarity_heatmap(sim_matrix, n_obs=None, cmap='inferno',
                             show_values=False, ax=None,
                             title='Similarity Matrix'):
-    """Plot a similarity matrix as a heatmap.
+    """Plot a similarity matrix heatmap.
+
+    The heatmap shows the results of a correlation matrix between
+    measurements at two or more sites. Lighter, warmer colors denote
+    higher similarity (correlation), while darker colors denote less
+    similarity between two sites.
 
     Parameters
     ----------