diff --git a/docstring.py b/docstring.py index e16a92d81..49560cdd2 100755 --- a/docstring.py +++ b/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" diff --git a/stumpy/aamp_stimp.py b/stumpy/aamp_stimp.py index 99ffd2718..fcc5636c7 100644 --- a/stumpy/aamp_stimp.py +++ b/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, diff --git a/stumpy/aampi.py b/stumpy/aampi.py index 7674243e5..36e4f930d 100644 --- a/stumpy/aampi.py +++ b/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 diff --git a/stumpy/floss.py b/stumpy/floss.py index dc89401cd..b5f1057ad 100644 --- a/stumpy/floss.py +++ b/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) diff --git a/stumpy/gpu_aamp_stimp.py b/stumpy/gpu_aamp_stimp.py index b2254b567..89d8ff7f5 100644 --- a/stumpy/gpu_aamp_stimp.py +++ b/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, diff --git a/stumpy/gpu_stimp.py b/stumpy/gpu_stimp.py index 7824f53f1..71ea64db0 100644 --- a/stumpy/gpu_stimp.py +++ b/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, diff --git a/stumpy/mparray.py b/stumpy/mparray.py index 6b8d89794..706260d19 100644 --- a/stumpy/mparray.py +++ b/stumpy/mparray.py @@ -68,6 +68,11 @@ def __new__(cls, input_array, m, k, excl_zone_denom): excl_zone_denom : int The denominator used in computing the exclusion zone + + Returns + ------- + obj : mparray + The `mparray` instance """ obj = np.asarray(input_array).view(cls) obj._m = m @@ -86,6 +91,10 @@ def __array_finalize__(self, obj): ---------- obj : object This is the class object + + Returns + ------- + None """ if obj is None: # pragma: no cover return @@ -102,6 +111,11 @@ def _P(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The (top-k) matrix profile for `T` """ if self._k == 1: return self[:, : self._k].flatten().astype(np.float64) @@ -115,6 +129,11 @@ def _I(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The (top-k) matrix profile indices for `T` """ if self._k == 1: return self[:, self._k : 2 * self._k].flatten().astype(np.int64) @@ -128,6 +147,11 @@ def _left_I(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The left (top-1) matrix profile indices for `T` """ if self._k == 1: return self[:, 2 * self._k].flatten().astype(np.int64) @@ -141,6 +165,11 @@ def _right_I(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The right (top-1) matrix profile indices for `T` """ if self._k == 1: return self[:, 2 * self._k + 1].flatten().astype(np.int64) @@ -155,6 +184,11 @@ def P_(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The (top-k) matrix profile for `T` """ return self._P() @@ -166,6 +200,11 @@ def I_(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The (top-k) matrix profile indices for `T` """ return self._I() @@ -177,6 +216,11 @@ def left_I_(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The left (top-k) matrix profile indices for `T` """ return self._left_I() @@ -188,5 +232,10 @@ def right_I_(self): Parameters ---------- None + + Returns + ------- + out : numpy.ndarray + The right (top-k) matrix profile indices for `T` """ return self._right_I() diff --git a/stumpy/scraamp.py b/stumpy/scraamp.py index e4f9417c4..dc17726cc 100644 --- a/stumpy/scraamp.py +++ b/stumpy/scraamp.py @@ -346,7 +346,7 @@ def _prescraamp( Returns ------- - out1 : numpy.ndarray + out : numpy.ndarray The (top-k) matrix profile. When k=1 (default), the first (and only) column in this 2D array consists of the matrix profile. When k > 1, the output has exactly `k` columns consisting of the top-k matrix profile. @@ -615,6 +615,10 @@ def __init__( The number of top `k` smallest distances used to construct the matrix profile. Note that this will increase the total computational time and memory usage when k > 1. + + Returns + ------- + None """ self._ignore_trivial = ignore_trivial self._p = p @@ -798,7 +802,11 @@ def P_(self): Returns ------- - None + out : numpy.ndarray + The updated (top-k) matrix profile. When `k=1` (default), this output is + a 1D array consisting of the updated matrix profile. When `k > 1`, the + output is a 2D array that has exactly `k` columns consisting of the updated + top-k matrix profile. """ if self._k == 1: return self._P.flatten().astype(np.float64) @@ -819,7 +827,11 @@ def I_(self): Returns ------- - None + out : numpy.ndarray + The updated (top-k) matrix profile indices. When `k=1` (default), this + output is a 1D array consisting of the updated matrix profile indices. + When `k > 1`, the output is a 2D array that has exactly `k` columns + consisting of the updated top-k matrix profile indices. """ if self._k == 1: return self._I.flatten().astype(np.int64) @@ -837,7 +849,8 @@ def left_I_(self): Returns ------- - None + out : numpy.ndarray + The updated left (top-1) matrix profile indices """ return self._IL.astype(np.int64) @@ -852,6 +865,7 @@ def right_I_(self): Returns ------- - None + out : numpy.ndarray + The updated right (top-1) matrix profile indices """ return self._IR.astype(np.int64) diff --git a/stumpy/scrump.py b/stumpy/scrump.py index e837a7268..4315d3364 100644 --- a/stumpy/scrump.py +++ b/stumpy/scrump.py @@ -865,6 +865,10 @@ def __init__( by currying the user-defined 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 """ self._ignore_trivial = ignore_trivial @@ -1084,7 +1088,8 @@ def P_(self): Returns ------- - None + out : numpy.ndarray + The updated (top-k) matrix profile """ if self._k == 1: return self._P.flatten().astype(np.float64) @@ -1105,7 +1110,8 @@ def I_(self): Returns ------- - None + out : numpy.ndarray + The updated (top-k) matrix profile indices """ if self._k == 1: return self._I.flatten().astype(np.int64) @@ -1123,7 +1129,8 @@ def left_I_(self): Returns ------- - None + out : numpy.ndarray + The updated left (top-1) matrix profile indices """ return self._IL.astype(np.int64) @@ -1138,6 +1145,7 @@ def right_I_(self): Returns ------- - None + out : numpy.ndarray + The updated right (top-1) matrix profile indices """ return self._IR.astype(np.int64) diff --git a/stumpy/stimp.py b/stumpy/stimp.py index 442353b2b..c68ddb193 100644 --- a/stumpy/stimp.py +++ b/stumpy/stimp.py @@ -186,6 +186,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._T = T.copy() if max_m is None: @@ -303,7 +307,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 @@ -342,7 +348,9 @@ def PAN_(self): Returns ------- - None + out : numpy.ndarray + The transformed (i.e., normalized, contrasted, binarized, and repeated) + pan matrix profile """ return self.pan().astype(np.float64) @@ -357,7 +365,8 @@ def M_(self): Returns ------- - None + out : numpy.ndarray + The (breadth first searched (level) ordered) subsequence window sizes """ return self._M.astype(np.int64) @@ -373,7 +382,8 @@ def P_(self): Returns ------- - None + out : numpy.ndarray + The raw (i.e., non-transformed) matrix profiles matrix profile """ P = [] for i, idx in enumerate(self._bfs_indices): @@ -556,6 +566,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, @@ -733,6 +747,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, diff --git a/stumpy/stumpi.py b/stumpy/stumpi.py index da5cf7938..a6109ea59 100644 --- a/stumpy/stumpi.py +++ b/stumpy/stumpi.py @@ -178,6 +178,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._T = core._preprocess(T) core.check_window_size(m, max_size=self._T.shape[0]) @@ -274,6 +278,10 @@ def update(self, t): t : float A single new data point to be appended to `T` + Returns + ------- + None + Notes ----- `DOI: 10.1007/s10618-017-0519-9 \ @@ -297,6 +305,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 @@ -376,6 +388,10 @@ def _update(self, t): ---------- t : float A single new data point to be appended to `T` + + Returns + ------- + None """ n = self._T.shape[0] l = n - self._m + 1 @@ -457,7 +473,8 @@ def P_(self): Returns ------- - None + out : numpy.ndarray + The (top-k) matrix profile """ if self._k == 1: return self._P.flatten().astype(np.float64) @@ -478,7 +495,8 @@ def I_(self): Returns ------- - None + out : numpy.ndarray + The (top-k) matrix profile indices """ if self._k == 1: return self._I.flatten().astype(np.int64) @@ -496,7 +514,8 @@ def left_P_(self): Returns ------- - None + out : numpy.ndarray + The (top-1) left matrix profile """ return self._left_P.astype(np.float64) @@ -511,7 +530,8 @@ def left_I_(self): Returns ------- - None + out : numpy.ndarray + The (top-1) left matrix profile indices """ return self._left_I.astype(np.int64) @@ -526,6 +546,8 @@ def T_(self): Returns ------- - None + out : numpy.ndarray + The time series or sequence for which the matrix profile and matrix + profile indices are computed """ return self._T