diff --git a/docs/modules/step_pattern.rst b/docs/modules/step_pattern.rst index fc8e698..197333d 100644 --- a/docs/modules/step_pattern.rst +++ b/docs/modules/step_pattern.rst @@ -1,3 +1,5 @@ +.. module:: dtwalign.step_pattern + ============= Step patterns ============= diff --git a/docs/tutorial.rst b/docs/tutorial.rst index e824312..c792723 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -39,7 +39,7 @@ Then run :func:`~dtwalign.dtw` method which returns :class:`~dtwalign.result.Dtw DTW distance ------------ -DTW distance can be refered via ``DtwResult`` object. +DTW distance can be refered via :class:`~dtwalign.result.DtwResult` object. .. code-block:: python @@ -55,7 +55,7 @@ DTW distance can be refered via ``DtwResult`` object. Alignment path -------------- -``DtwResult`` object offers a method which visualize alignment path with cumsum cost matrix. +:class:`~dtwalign.result.DtwResult` object offers a method which visualize alignment path with cumsum cost matrix. .. code-block:: python @@ -103,7 +103,7 @@ Advanced Usage Global constraint ----------------- -``dtw`` method can take ``window_type`` parameter to constrain +:func:`~dtwalign.dtw` method can take ``window_type`` parameter to constrain the warping path globally which is also known as 'windowing'. .. code-block:: python @@ -168,7 +168,7 @@ Following step patterns are supported: Partial alignment ----------------- -``dtw`` method also be able to perform partial matching algorithm +:func:`~dtwalign.dtw` method also be able to perform partial matching algorithm by setting ``open_begin`` and ``open_end``. Before see example code, let's make toy data via following: diff --git a/dtwalign/dtw.py b/dtwalign/dtw.py index 7d50201..e1eebf1 100644 --- a/dtwalign/dtw.py +++ b/dtwalign/dtw.py @@ -45,16 +45,16 @@ def dtw(x, y, dist="euclidean", window_type="none", window_size=None, y : 1D or 2D array (sample * feature) Reference time series. - dist : string or function - Define how to calclulate pair-wise distance between x and y. - string - metric argument of scipy.spatial.distance - function - user function that defines metric between two samples. - ex) euclidean distance: user_func = lambda x,y : np.sqrt((x-y)**2) + dist : string or callable + Define how to calclulate pair-wise distance between x and y. + * string: metric argument of ``scipy.spatial.distance`` + * callable: user function that defines metric between two samples. + ex) lambda x, y : np.sqrt((x - y)**2) window_type : string - Window type to use. - "sakoechiba" - Sakoechiba window - "itakura" - Itakura window + Window type to use. + * "sakoechiba": Sakoechiba window + * "itakura": Itakura window window_size : int Window size to use for Sakoechiba window. @@ -63,15 +63,15 @@ def dtw(x, y, dist="euclidean", window_type="none", window_size=None, Step pattern to use. dist_only : bool - Whether or not to obtain warping path. If true, + Whether or not to obtain warping path. If true, only alignment distance will be calculated. open_begin : bool - Whether or not perform open-ended alignment at the starting point of + Whether or not perform open-ended alignment at the starting point of query time series. If true, partial alignment will be performed. open_end : bool - Whether or not perform open-ended alignment at the end point of + Whether or not perform open-ended alignment at the end point of query time series. If true, partial alignment will be performed. Returns @@ -109,7 +109,8 @@ def dtw_from_distance_matrix(X, window_type="none", window_size=None, X : 2D array Pre-computed pair-wise distance matrix. - others : see `dtw` function. + others : + see :func:`~dtwalign.dtw` function. Returns ------- @@ -138,7 +139,8 @@ def dtw_low(X, window, pattern, dist_only=False, pattern : dtwalign.step_pattern.BasePattern object step pattern object. - others : see `dtw` function. + others : + see :func:`~dtwalign.dtw` function. Returns ------- diff --git a/dtwalign/result.py b/dtwalign/result.py index e6a7eeb..529a331 100644 --- a/dtwalign/result.py +++ b/dtwalign/result.py @@ -5,7 +5,20 @@ from scipy.interpolate import interp1d class DtwResult(): - """Result of DTW.""" + """Result of DTW. + + Attributes + ---------- + path : 2d array + Alignment path. + * First column: query path array + * Second column: reference path array + distance : float + Alignment distance. + normalized_distance : float + Normalized alignment distance. + + """ def __init__(self, cumsum_matrix, path, window, pattern): self.cumsum_matrix = cumsum_matrix @@ -23,7 +36,7 @@ def get_warping_path(self, target="query"): Parameters ---------- - target : "query" or "reference" + target : string, "query" or "reference" Specify the target to be warped. Returns @@ -74,7 +87,7 @@ def plot_path(self, with_="cum"): Parameters ---------- - with_ : "win", "cum" or None + with_ : string, "win" or "cum" or None If given, following will be plotted with alignment path: * "win" : window matrix * "cum" : cumsum matrix diff --git a/dtwalign/step_pattern.py b/dtwalign/step_pattern.py index eea524f..fd0597c 100644 --- a/dtwalign/step_pattern.py +++ b/dtwalign/step_pattern.py @@ -782,8 +782,9 @@ def __init__(self, pattern_info, normalize_guide): Parameters ---------- pattern_info : list - list contains pattern information. - ex) the case of symmetric2 pattern: + list contains pattern information. + ex) the case of symmetric2 pattern: + ``` pattern_info = [ dict( indices=[(-1,0),(0,0)], @@ -798,9 +799,10 @@ def __init__(self, pattern_info, normalize_guide): weights=[1] ) ] + ``` normalize_guide : string ('N','M','N+M','none') - guide to compute normalized distance. + Guide to compute normalized distance. """ # validation diff --git a/dtwalign/window.py b/dtwalign/window.py index c066faf..3e143b8 100644 --- a/dtwalign/window.py +++ b/dtwalign/window.py @@ -13,6 +13,8 @@ def __init__(self): pass def plot(self): + """Show window. + """ _, ax = plt.subplots(1) sns.heatmap(self.matrix.T, vmin=0, vmax=1, xticklabels=self.matrix.shape[0]//10, @@ -28,6 +30,13 @@ def plot(self): class NoWindow(BaseWindow): label = "no window" def __init__(self, len_x, len_y): + """No window class which will be used for no constraint. + len_x : int + Length of query. + len_y : int + Length of reference. + + """ self._gen_window(len_x, len_y) def _gen_window(self, len_x, len_y): @@ -38,6 +47,15 @@ def _gen_window(self, len_x, len_y): class SakoechibaWindow(BaseWindow): label = "sakoechiba window" def __init__(self, len_x, len_y, size): + """Sakoechiba window. + len_x : int + Length of query. + len_y : int + Length of reference. + size : int + Size of window width. + + """ self._gen_window(len_x, len_y, size) def _gen_window(self, len_x, len_y, size): @@ -50,6 +68,13 @@ def _gen_window(self, len_x, len_y, size): class ItakuraWindow(BaseWindow): label = "itakura window" def __init__(self, len_x, len_y): + """Itakura window. + len_x : int + Length of query. + len_y : int + Length of reference. + + """ self._gen_window(len_x, len_y) def _gen_window(self, len_x, len_y): @@ -77,13 +102,13 @@ def __init__(self, len_x, len_y, win_func, *args, **kwargs): Parameters ---------- len_x : int - length of query. + Length of query. len_y : int - length of reference. + Length of reference. win_func : callable - any function which returns bool. + Any function which returns bool. *args, **kwargs : - arguments for win_func + Arguments for win_func """ self._gen_window(len_x, len_y, win_func, *args, **kwargs)