Fixed #1123 Add missing Returns section in docstrings (#1124)

* Fixed #1123 Add missing Returns section in docstrings

* Fixed bad formatting, refactored

* Fixed bad function params

* Fixed "out1"

* Minor change

* Update docstring.py

---------

Co-authored-by: Nima Sarajpoor <Nima_sarajpoor@manulife.com>

Author: seanlaw

docstring.py

@@ -10,25 +10,24 @@ def get_docstring_args(fd, file_name, func_name, class_name=None):
     Extract docstring parameters from function definition
     """
     docstring = ast.get_docstring(fd)
-    if len(re.findall(r"Parameters", docstring)) != 1:
+    if docstring is None or len(re.findall(r"Parameters", docstring)) != 1:
         msg = "Missing required 'Parameters' section in docstring in \n"
         msg += f"file: {file_name}\n"
         if class_name is not None:
             msg += f"class: {class_name}\n"
         msg += f"function/method: {func_name}\n"
         raise RuntimeError(msg)
-    if class_name is None and len(re.findall(r"Returns", docstring)) != 1:
+    if len(re.findall(r"Returns", docstring)) != 1:
         msg = "Missing required 'Returns' section in docstring in \n"
         msg += f"file: {file_name}\n"
+        if class_name is not None:
+            msg += f"class: {class_name}\n"
         msg += f"function/method: {func_name}\n"
         raise RuntimeError(msg)
 
-    if class_name is None:
-        params_section = re.findall(
-            r"(?<=Parameters)(.*)(?=Returns)", docstring, re.DOTALL
-        )[0]
-    else:
-        params_section = re.findall(r"(?<=Parameters)(.*)", docstring, re.DOTALL)[0]
+    params_section = re.findall(
+        r"(?<=Parameters)(.*)(?=Returns)", docstring, re.DOTALL
+    )[0]
 
     args = re.findall(r"(\w+)\s+\:", params_section)
     args = set([a for a in args if a != "i"])  # `i` should never be a parameter
@@ -47,7 +46,7 @@ def check_args(doc_args, sig_args, file_name, func_name, class_name=None):
     """
     Compare docstring arguments and signature argments
     """
-    diff_args = signature_args.difference(docstring_args)
+    diff_args = sig_args.difference(doc_args)
     if len(diff_args) > 0:
         msg = "Found one or more arguments/parameters with missing docstring in \n"
         msg += f"file: {file_name}\n"
@@ -57,7 +56,7 @@ def check_args(doc_args, sig_args, file_name, func_name, class_name=None):
         msg += f"parameter(s): {diff_args}\n"
         raise RuntimeError(msg)
 
-    diff_args = docstring_args.difference(signature_args)
+    diff_args = doc_args.difference(sig_args)
     if len(diff_args) > 0:
         msg = "Found one or more unsupported arguments/parameters with docstring in \n"
         msg += f"file: {file_name}\n"

stumpy/aamp_stimp.py

@@ -189,6 +189,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         self._T = T.copy()
         self._T_min = np.min(self._T[np.isfinite(self._T)])
@@ -228,6 +232,10 @@ def update(self):
         ----------
         None
 
+        Returns
+        -------
+        None
+
         Notes
         -----
         `DOI: 10.1109/ICBK.2019.00031 \
@@ -290,7 +298,9 @@ def pan(self, threshold=0.2, normalize=True, contrast=True, binary=True, clip=Tr
 
         Returns
         -------
-        None
+        PAN : numpy.ndarray
+            The transformed (i.e., normalized, contrasted, binarized, and repeated)
+            pan matrix profile
         """
         PAN = self._PAN.copy()
         # Retrieve the row indices where the matrix profile was actually computed
@@ -334,6 +344,12 @@ def PAN_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The transformed (i.e., normalized, contrasted, binarized, and repeated) pan
+            matrix profile
         """
         return self.pan().astype(np.float64)
 
@@ -345,6 +361,12 @@ def M_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The full list of (breadth first search (level) ordered) subsequence window
+            sizes
         """
         return self._M.astype(np.int64)
 
@@ -360,7 +382,9 @@ def P_(self):
 
         Returns
         -------
-        None
+        P : list of numpy.ndarray
+            A list of all of the raw (i.e., non-transformed) matrix profiles matrix
+            profile in (breadth first searched (level) ordered)
         """
         P = []
         for i, idx in enumerate(self._bfs_indices):
@@ -491,6 +515,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,
@@ -597,6 +625,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,

stumpy/aampi.py

@@ -109,6 +109,10 @@ def __init__(self, T, m, egress=True, p=2.0, k=1, mp=None):
             corresponding indices. The last two columns correspond to the top-1 left
             and top-1 right matrix profile indices. When None (default), this array is
             computed internally using `stumpy.aamp`.
+
+        Returns
+        -------
+        None
         """
         self._T = core._preprocess(T)
         core.check_window_size(m, max_size=self._T.shape[0])
@@ -180,6 +184,10 @@ def update(self, t):
         t : float
             A single new data point to be appended to `T`
 
+        Returns
+        -------
+        None
+
         Notes
         -----
         `arXiv:1901.05708 \
@@ -203,6 +211,10 @@ def _update_egress(self, t):
         ----------
         t : float
             A single new data point to be appended to `T`
+
+        Returns
+        -------
+        None
         """
         self._n = self._T.shape[0]
         l = self._n - self._m + 1 - 1  # Subtract 1 due to egress
@@ -268,6 +280,10 @@ def _update(self, t):
         ----------
         t : float
             A single new data point to be appended to `T`
+
+        Returns
+        -------
+        None
         """
         self._n = self._T.shape[0]
         l = self._n - self._m + 1
@@ -331,6 +347,11 @@ def P_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The (top-k) matrix profile
         """
         if self._k == 1:
             return self._P.flatten().astype(np.float64)
@@ -348,6 +369,11 @@ def I_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The (top-k) matrix profile indices
         """
         if self._k == 1:
             return self._I.flatten().astype(np.int64)
@@ -362,6 +388,11 @@ def left_P_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The (top-1) left matrix profile
         """
         return self._left_P.astype(np.float64)
 
@@ -373,6 +404,11 @@ def left_I_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The (top-1) left matrix profile indices
         """
         return self._left_I.astype(np.int64)
 
@@ -384,5 +420,10 @@ def T_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The time series
         """
         return self._T

stumpy/floss.py

@@ -499,6 +499,10 @@ def __init__(
             `functools.partial`. Any subsequence with at least one np.nan/np.inf will
             automatically have its corresponding value set to False in this boolean
             array.
+
+        Returns
+        -------
+        None
         """
         self._mp = copy.deepcopy(np.asarray(mp))
         self._T = copy.deepcopy(np.asarray(T))
@@ -608,6 +612,10 @@ def update(self, t):
         t : float
             A single new data point to be appended to `T`
 
+        Returns
+        -------
+        None
+
         Notes
         -----
         DOI: 10.1109/ICDM.2017.21 \
@@ -702,7 +710,8 @@ def cac_1d_(self):
 
         Returns
         -------
-        None
+        out : numpy.ndarray
+            The 1-dimensional corrected arc curve (CAC_1D)
         """
         return self._cac.astype(np.float64)
 
@@ -717,7 +726,8 @@ def P_(self):
 
         Returns
         -------
-        None
+        out : numpy.ndarray
+            The matrix profile
         """
         return self._mp[:, 0].astype(np.float64)
 
@@ -736,7 +746,8 @@ def I_(self):
 
         Returns
         -------
-        None
+        out : numpy.ndarray
+            The (right) matrix profile indices
         """
         # Comparing the right matrix profile index value with the self index
         # position (i.e., self._mp[:, 3] == np.arange(len(self._mp)) is avoided
@@ -759,6 +770,7 @@ def T_(self):
 
         Returns
         -------
-        None
+        out : numpy.ndarray
+            The time series
         """
         return self._T.astype(np.float64)

stumpy/gpu_aamp_stimp.py

@@ -102,6 +102,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,

stumpy/gpu_stimp.py

@@ -164,6 +164,10 @@ def __init__(
             function using  `functools.partial``. Any subsequence with at least one
             ``np.nan``/``np.inf`` will automatically have its corresponding value set
             to ``False`` in this boolean array.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,