Fix warnings in the documentation build

examples/SWAN_example.ipynb

@@ -6,7 +6,7 @@
       "source": [
         "# MHKiT SWAN Example\n",
         "\n",
-        "This example notebook demonstrates the input and plotting of output data from the software [Simulating WAves Nearshore (SWAN)](http://swanmodel.sourceforge.net/) using MHKiT. In this example the [SNL-SWAN](https://github.com/SNL-WaterPower/SNL-SWAN) tutorial was run for a wave energy converter. The output was written in ASCII and binary (*.mat) files. This MHKiT example notebook demonstrates how to import these different files into MHKiT and plot the output data. First, we will import the MHKiT SWAN package and the other Python packages needed for this example. Secondly, we will create an operating system independent path to the folder housing the SWAN data used in this example `swan_data_folder` using the `join` funtion. "
+        "This example notebook demonstrates the input and plotting of output data from the software [Simulating WAves Nearshore (SWAN)](http://swanmodel.sourceforge.net/) using MHKiT. In this example the [SNL-SWAN](https://github.com/SNL-WaterPower/SNL-SWAN) tutorial was run for a wave energy converter. The output was written in ASCII and binary (`*.mat`) files. This MHKiT example notebook demonstrates how to import these different files into MHKiT and plot the output data. First, we will import the MHKiT SWAN package and the other Python packages needed for this example. Secondly, we will create an operating system independent path to the folder housing the SWAN data used in this example `swan_data_folder` using the `join` function. "
       ]
     },
     {
@@ -29,7 +29,7 @@
       "source": [
         "## Supported SWAN Output Files\n",
         "\n",
-        "MHKiT currenlty supports block and table SWAN output files in ASCII or binary (*.mat) files. Detailed descriptions of these file types may be found in the [SWAN User Manual](http://swanmodel.sourceforge.net/download/zip/swanuse.pdf). In the following cells, SWAN table and block data will be imported, discussed, and plotted. Three SWAN output files will be imported:\n",
+        "MHKiT currenlty supports block and table SWAN output files in ASCII or binary (`*.mat`) files. Detailed descriptions of these file types may be found in the [SWAN User Manual](http://swanmodel.sourceforge.net/download/zip/swanuse.pdf). In the following cells, SWAN table and block data will be imported, discussed, and plotted. Three SWAN output files will be imported:\n",
         " 1. An ASCII table file ('SWANOUT.DAT'), \n",
         " 2. An ASCII block file ('SWANOUTBlock.DAT') \n",
         " 3. A binary block file ('SWANOUT.mat')  "

mhkit/acoustics/__init__.py

@@ -1,8 +1,18 @@
 """
-The `acoustics` package of the MHKiT (Marine and Hydrokinetic Toolkit) library
-provides tools and functionalities for analyzing and visualizing passive
-acoustic monitoring data deployed in water bodies. This package reads in raw
-wav files and conducts basic acoustics analysis and visualization.
+The passive acoustics module provides a set of functions
+for analyzing and visualizing passive acoustic monitoring 
+data deployed in water bodies. This package reads in raw
+*.wav* files and conducts basic acoustics analysis and 
+visualization.
+
+To start using the module, import it directly from MHKiT:
+``from mhkit import acoustics``. The analysis functions
+are available directly from the main import, while the 
+I/O and graphics submodules are available from 
+``acoustics.io`` and  ``acoustics.graphics``, respectively.
+The base functions are intended to be used on top of the I/O submodule, and 
+include functionality to calibrate data, create spectral densities, sound 
+pressure levels, and time or band aggregate spectral data.
 """
 
 from mhkit.acoustics import io, graphics

mhkit/acoustics/analysis.py

@@ -8,37 +8,45 @@
 The following functionality is provided:
 
 1. **Frequency Validation and Warning**:
+
    - `_fmax_warning`: Ensures specified maximum frequency does not exceed the Nyquist frequency,
      adjusting if necessary to avoid aliasing.
 
 2. **Shallow Water Cutoff Frequency**:
+
    - `minimum_frequency`: Calculates the minimum frequency cutoff based on water depth and the
      speed of sound in water and seabed materials.
 
 3. **Spectral Density Calculations**:
+
    - `sound_pressure_spectral_density`: Computes the mean square sound pressure spectral density
      using FFT binning with Hanning windowing and 50% overlap.
 
 4. **Calibration**:
+
    - `apply_calibration`: Applies calibration adjustments to the spectral density data using
      a sensitivity curve, filling missing values as specified.
 
 5. **Spectral Density Level Calculation**:
+
    - `sound_pressure_spectral_density_level`: Converts mean square spectral density values to
      sound pressure spectral density levels in dB.
 
 6. **Spectral Density Aggregation**:
+
    - `band_aggregate`: Aggregates spectral density data into fractional octave bands using
      specified statistical methods (e.g., median, mean).
 
    - `time_aggregate`: Aggregates spectral density data into specified time windows using
      similar statistical methods.
 
 7. **Sound Pressure Level Calculation**:
+
    - `sound_pressure_level`: Computes the overall sound pressure level within a frequency band
      from mean square spectral density.
 
 8. **Frequency-Banded Sound Pressure Level**:
+
    - `_band_sound_pressure_level`: Helper function for calculating sound pressure levels
      over specified frequency bandwidths.
 

mhkit/acoustics/graphics.py

@@ -4,16 +4,18 @@
 levels across time and frequency dimensions.
 
 Each plotting function leverages the flexibility of Matplotlib, allowing for passthrough
-of Matplotlib keyword arguments via **kwargs, making it easy to modify plot aspects such as
+of Matplotlib keyword arguments via ``**kwargs``, making it easy to modify plot aspects such as
 color, scale, and label formatting.
 
 Key Functions
 -------------
 1. **plot_spectrogram**:
+
    - Generates a spectrogram plot from sound pressure spectral density level data, 
      with a logarithmic frequency scale by default for improved readability of acoustic data.
 
 2. **plot_spectra**:
+
    - Produces a spectral density plot with a log-transformed x-axis, allowing for clear 
      visualization of spectral density across frequency bands.
 """

mhkit/acoustics/io.py

@@ -13,6 +13,7 @@
 ------------------
 
 1. **Data Reading**:
+
    - `read_hydrophone`: Main function to read a WAV file from a hydrophone and 
      convert it to either a voltage or pressure time series, depending on the 
      availability of sensitivity data.
@@ -25,10 +26,12 @@
      sound pressure calculation.
 
 2. **Audio Export**:
+
    - `export_audio`: Converts processed sound pressure data back into a WAV file 
      format, with optional gain adjustment to improve playback quality.
 
 3. **Data Extraction**:
+
    - `_read_wav_metadata`: Extracts metadata from a WAV file, including bit depth 
      and other header information.
 

mhkit/mooring/graphics.py

@@ -1,6 +1,4 @@
 """
-graphics.py
-
 This module provides a function for creating animated visualizations of a 
 MoorDyn node position dataset using the matplotlib animation API. 
 

mhkit/power/quality.py

@@ -1,10 +1,10 @@
 """
 This module contains functions for calculating various aspects of power quality, 
-particularly focusing on the analysis of harmonics and interharmonics in electrical 
-power systems. These functions are designed to assist in power quality assessments 
-by providing tools to analyze voltage and current signals for their harmonic 
-and interharmonic components based on the guidelines and methodologies 
-outlined in IEC 61000-4-7.
+particularly focusing on the analysis of harmonics, interharmonics and distortion 
+in electrical power systems. These functions are designed to assist in power 
+quality assessments by providing tools to analyze voltage and current signals 
+for their harmonic and interharmonic components based on the guidelines and methodologies 
+outlined in IEC 61000-4-7:2008 ED2 and in IEC 62600-30:2018 ED1.
 
 Functions in this module include:
 

mhkit/tests/wave/io/test_swan.py

@@ -35,7 +35,7 @@ def setUpClass(self):
         self.swan_block_txt_file = join(swan_datadir, "SWANOUTBlock.DAT")
         self.expected_table = pd.read_csv(
             self.table_file,
-            sep="\s+",
+            sep="\\s+",
             comment="%",
             names=["Xp", "Yp", "Hsig", "Dir", "RTpeak", "TDir"],
         )

mhkit/tidal/graphics.py

@@ -39,8 +39,8 @@ def _initialize_polar(ax=None, metadata=None, flood=None, ebb=None):
         plt.title(metadata["name"])
         # List of strings for metadata box
         bouy_str = [
-            f'Lat = {float(metadata["lat"]):0.2f}$\degree$',
-            f'Lon = {float(metadata["lon"]):0.2f}$\degree$',
+            f'Lat = {float(metadata["lat"]):0.2f}$\\degree$',
+            f'Lon = {float(metadata["lon"]):0.2f}$\\degree$',
         ]
         # Create string for text box
         bouy_data = "\n".join(bouy_str)

mhkit/wave/graphics.py

@@ -64,7 +64,7 @@ def plot_elevation_timeseries(eta, ax=None):
     t = eta[time_dimension]
 
     for var in eta.data_vars:
-        ax = _xy_plot(t, eta[var], fmt="-", xlabel="Time", ylabel="$\eta$ [m]", ax=ax)
+        ax = _xy_plot(t, eta[var], fmt="-", xlabel="Time", ylabel="$\\eta$ [m]", ax=ax)
 
     return ax
 
@@ -242,7 +242,7 @@ def plot_chakrabarti(H, lambda_w, D, ax=None):
 
         KC = H / D
         Diffraction = np.pi * D / lambda_w
-        label = f"$H$ = {H:g}, $\lambda_w$ = {lambda_w:g}, $D$ = {D:g}"
+        label = f"$H$ = {H:g}, $\\lambda_w$ = {lambda_w:g}, $D$ = {D:g}"
         ax.plot(Diffraction, KC, "o", label=label)
 
     if (
@@ -268,7 +268,7 @@ def plot_chakrabarti(H, lambda_w, D, ax=None):
     ax.text(
         1,
         7,
-        "wave\nbreaking\n$H/\lambda_w > 0.14$",
+        "wave\nbreaking\n$H/\\lambda_w > 0.14$",
         ha="center",
         va="center",
         fontstyle="italic",

mhkit/wave/io/ndbc.py

@@ -98,7 +98,7 @@ def read_file(file_name, missing_values=["MM", 9999, 999, 99], to_pandas=True):
     if header_commented:
         data = pd.read_csv(
             file_name,
-            sep="\s+",
+            sep="\\s+",
             header=None,
             names=header,
             comment="#",
@@ -107,7 +107,7 @@ def read_file(file_name, missing_values=["MM", 9999, 999, 99], to_pandas=True):
     # If first line is not commented, then the first row can be used as header
     else:
         data = pd.read_csv(
-            file_name, sep="\s+", header=0, comment="#", parse_dates=[parse_vals]
+            file_name, sep="\\s+", header=0, comment="#", parse_dates=[parse_vals]
         )
 
     # Convert index to datetime
@@ -403,13 +403,13 @@ def request_data(parameter, filenames, proxy=None, clear_cache=False, to_pandas=
                 response = requests.get(file_url, proxies=proxy)
             try:
                 data = zlib.decompress(response.content, 16 + zlib.MAX_WBITS)
-                df = pd.read_csv(BytesIO(data), sep="\s+", low_memory=False)
+                df = pd.read_csv(BytesIO(data), sep="\\s+", low_memory=False)
 
                 # catch when units are included below the header
                 firstYear = df["MM"][0]
                 if isinstance(firstYear, str) and firstYear == "mo":
                     df = pd.read_csv(
-                        BytesIO(data), sep="\s+", low_memory=False, skiprows=[1]
+                        BytesIO(data), sep="\\s+", low_memory=False, skiprows=[1]
                     )
             except zlib.error:
                 msg = (

mhkit/wave/io/swan.py

@@ -41,16 +41,18 @@ def read_table(swan_file, to_pandas=True):
             if metaDict["Table"].endswith("SWAN"):
                 metaDict["Table"] = metaDict["Table"].split(" SWAN")[:-1]
         if i == header_line_number:
-            header = re.split("\s+", line.rstrip().strip("%").lstrip())
+            header = re.split("\\s+", line.rstrip().strip("%").lstrip())
             metaDict["header"] = header
         if i == header_line_number + 1:
             units = re.split(
-                "\s+", line.strip(" %\n").replace("[", "").replace("]", "")
+                "\\s+", line.strip(" %\n").replace("[", "").replace("]", "")
             )
             metaDict["units"] = units
     f.close()
 
-    swan_data = pd.read_csv(swan_file, sep="\s+", comment="%", names=metaDict["header"])
+    swan_data = pd.read_csv(
+        swan_file, sep="\\s+", comment="%", names=metaDict["header"]
+    )
 
     if not to_pandas:
         swan_data = convert_to_dataset(swan_data)
@@ -144,7 +146,7 @@ def _read_block_txt(swan_file):
             columns_position = None
 
         if not line.startswith("%"):
-            raw_data = " ".join(re.split(" |\.", line.strip(" \n"))).split()
+            raw_data = " ".join(re.split(" |\\.", line.strip(" \n"))).split()
             index_number = int(raw_data[0])
             columns_data = raw_data[1:]
             data = []
@@ -230,7 +232,7 @@ def _parse_line_metadata(line):
 
     metaDict = {}
     meta = re.sub(
-        "\s+", " ", line.replace(",", " ").strip("% \n").replace("**", "vars:")
+        "\\s+", " ", line.replace(",", " ").strip("% \n").replace("**", "vars:")
     )
     mList = meta.split(":")
     elms = [elm.split(" ") for elm in mList]