(add) tutorial

docs/index.rst

@@ -24,6 +24,13 @@ Installation
    tutorial
    api
 
+.. _references::
+=========
+Reference
+=========
+* Sakoe, H.; Chiba, S., Dynamic programming algorithm optimization for spoken word recognition, Acoustics, Speech, and Signal Processing
+* Paolo Tormene, Toni Giorgino, Silvana Quaglini, Mario Stefanelli (2008). Matching Incomplete Time Series with Dynamic Time Warping: An Algorithm and an Application to Post-Stroke Rehabilitation. Artificial Intelligence in Medicine, 45(1), 11-34.
+* Toni Giorgino (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: The dtw Package. Journal of Statistical Software, 31(7), 1-24.
 
 ==================
 Indices and tables

docs/tutorial.rst

@@ -14,15 +14,15 @@ Firstly, let's generate toy data for this tutorial.
 
     np.random.seed(1234)
     # generate toy data
-    x = np.sin(2*np.pi*3.1*np.linspace(0,1,101))
+    x = np.sin(2 * np.pi * 3.1 * np.linspace(0, 1, 101))
     x += np.random.rand(x.size)
-    y = np.sin(2*np.pi*3*np.linspace(0,1,120))
+    y = np.sin(2 * np.pi * 3 * np.linspace(0, 1, 120))
     y += np.random.rand(y.size)
 
-    plt.plot(x,label="query")
-    plt.plot(y,label="reference")
+    plt.plot(x, label="query")
+    plt.plot(y, label="reference")
     plt.legend()
-    plt.ylim(-1,3)
+    plt.ylim(-1, 3)
 
 .. image:: img/tutorial/toy_data.png
 
@@ -31,15 +31,15 @@ Then run dtw method which returns DtwResult object.
 .. code-block:: python
 
     from dtwalign import dtw
-    res = dtw(x,y)
+    res = dtw(x, y)
 
 .. note::
     The first run takes a few seconds for jit compilation.
 
-dtw distance
+DTW distance
 ------------
 
-dtw distance can be refered via DtwResult object.
+DTW distance can be refered via DtwResult object.
 
 .. code-block:: python
 
@@ -52,7 +52,7 @@ dtw distance can be refered via DtwResult object.
     If you want to calculate only dtw distance (i.e. no need to gain alignment path),
     give 'distance_only' argument as True when runs `dtw` method (it makes faster).
 
-alignment path
+Alignment path
 --------------
 
 DtwResult object offers a method which visualize alignment path with cumsum cost matrix.
@@ -67,10 +67,10 @@ Alignment path array also provided:
 
 .. code-block:: python
 
-    x_path = res.path[:,0]
-    y_path = res.path[:,1]
+    x_path = res.path[:, 0]
+    y_path = res.path[:, 1]
 
-warp one to the other
+Warp one to the other
 ---------------------
 
 `get_warping_path` method provides an alignment path of X with fixed Y and vice versa.
@@ -79,54 +79,226 @@ warp one to the other
 
     # warp x to y
     x_warping_path = res.get_warping_path(target="query")
-    plt.plot(x[x_warping_path],label="aligned query to reference")
-    plt.plot(y,label="reference")
+    plt.plot(x[x_warping_path], label="aligned query to reference")
+    plt.plot(y, label="reference")
     plt.legend()
-    plt.ylim(-1,3)
+    plt.ylim(-1, 3)
 
 .. image:: img/tutorial/x_to_y.png
 
 .. code-block:: python
 
     # warp y to x
     y_warping_path = res.get_warping_path(target="reference")
-    plt.plot(x,label="query")
-    plt.plot(y[y_warping_path],label="aligned reference to query")
+    plt.plot(x, label="query")
+    plt.plot(y[y_warping_path], label="aligned reference to query")
     plt.legend()
-    plt.ylim(-1,3)
+    plt.ylim(-1, 3)
 
 .. image:: img/tutorial/y_to_x.png
 
 Advanced Usage
 ==============
-global constraint
+
+Global constraint
 -----------------
-regarding how to run dtw with global constrained which is also called windowing.
 
-local constraint
+`dtw` method can take `window_type` parameter to constrain
+the warping path globally which is also known as 'windowing'.
+
+.. code-block:: python
+
+    # run DTW with Itakura constraint
+    res = dtw(x, y, window_type="itakura")
+    res.plot_path()
+
+.. image:: img/tutorial/itakura.png
+
+.. code-block:: python
+
+    # run DTW with Sakoechiba constraint
+    res = dtw(x, y, window_type="sakoechiba", window_size=20)
+    # visualize alignment path with cumsum cost matrix
+    res.plot_path()
+
+.. image:: img/tutorial/sakoechiba.png
+
+Local constraint
 ----------------
 
-regarding how to run dtw with local constrained which is also called step pattern.
+`dtwalign` package also supports local constrained optimization
+which is also known as 'step pattern'.
+Following step patterns are supported:
+
+* symmetric1
+* symmetric2
+* symmetricP05
+* symmetricP0
+* symmetricP1
+* symmetricP2
+* Asymmetric
+* AsymmetricP0
+* AsymmetricP05
+* AsymmetricP1
+* AsymmetricP2
+* TypeIa
+* TypeIb
+* TypeIc
+* TypeId
+* TypeIas
+* TypeIbs
+* TypeIcs
+* TypeIds
+* TypeIIa
+* TypeIIb
+* TypeIIc
+* TypeIId
+* TypeIIIc
+* TypeIVc
+* Mori2006
+
+.. code-block:: python
+
+    # run DTW with symmetricP2 pattern
+    res = dtw(x, y, step_pattern="symmetricP2")
+    res.plot_path()
+
+.. image:: img/tutorial/local-constrained.png
 
-partial alignment
+Partial alignment
 -----------------
 
-regarding how to perform partial matching algorithm.
+`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:
 
-use other metric
+.. code-block:: python
+    
+    x_partial = np.sin(2 * np.pi * 3 * np.linspace(0.3, 0.8, 100))
+    x_partial += np.random.rand(x_partial.size)
+    y_partial = np.sin(2 * np.pi * 3.1 * np.linspace(0, 1, 120))
+    y_partial += np.random.rand(y_partial.size)
+
+    plt.plot(x_partial, label="query")
+    plt.plot(y_partial, label="reference")
+    plt.legend()
+    plt.ylim(-1, 3)
+
+.. image:: img/tutorial/toy_data_partial.png
+
+Open-end alignment can be performed by letting `open_end` True.
+
+.. code-block:: python
+
+    res = dtw(x_partial, y_partial, open_end=True)
+    res.plot_path()
+
+.. image:: img/tutorial/open_end.png
+
+As above, let `open_begin` True to run open-begin alignment.
+
+.. note::
+    Open-begin requires "N" normalizable pattern.  
+    If you want to know more detail, see `references <index.html#references>`_.
+
+.. code-block:: python
+
+    res = dtw(x_partial, y_partial, step_pattern="asymmetric", open_begin=True)
+    res.plot_path()
+
+.. image:: img/tutorial/open_begin.png
+
+.. code-block:: python
+
+    res = dtw(x_partial,y_partial,step_pattern="asymmetric",open_begin=True,open_end=True)
+    res.plot_path()
+
+.. image:: img/tutorial/open_begin_end.png
+
+Use other metric
 ----------------
 
-how to use other pair-wise distance metric (default is euclidean).
+You can use other pair-wise distance metric (default is euclidean).
+Metrics in `scipy.spatial.distance.cdist` are supported:
+
+.. code-block:: python
+
+    res = dtw(x, y, dist="minkowski")
+
+
+Arbitrary function which returns distance value between x and y is also available.
 
-use pre-computed distance matrix
+.. code-block:: python
+
+    res = dtw(x, y, dist=lambda x, y: np.abs(x - y))
+
+Use pre-computed distance matrix
 --------------------------------
 
-how to run dtw with given pre-computed distance matrix, not with X and Y.
+You can also calculate DTW with given pre-computed distance matrix like:
+
+.. code-block:: python
+
+    # calculate pair-wise distance matrix in advance
+    from scipy.spatial.distance import cdist
+    X = cdist(x[:,np.newaxis], y[:,np.newaxis], metric="euclidean")
 
-use user-defined constraints
+    # use `dtw_from_distance_matrix` method for computation.
+    from dtwalign import dtw_from_distance_matrix
+    res = dtw_from_distance_matrix(X, window_type="itakura", step_pattern="typeIVc")
+
+Use user-defined constraints
 ----------------------------
 
-how to define user constraint and to use.
+Local constraint (step pattern)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # define local constraint (step pattern)
+    from dtwalign.step_pattern import UserStepPattern
+    pattern_info = [
+                        dict(
+                            indices=[(-1,0),(0,0)],
+                            weights=[1]
+                        ),
+                        dict(
+                            indices=[(-1,-1),(0,0)],
+                            weights=[2]
+                        ),
+                        dict(
+                            indices=[(0,-1),(0,0)],
+                            weights=[1]
+                        )
+                    ]
+    user_step_pattern = UserStepPattern(pattern_info=pattern_info,normalize_guide="N+M")
+
+    # plot
+    user_step_pattern.plot()
+
+.. image:: img/tutorial/user_step.png
+
+Global constraint (windowing)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # define global constraint (windowing)
+    from dtwalign.window import UserWindow
+    user_window = UserWindow(X.shape[0], X.shape[1], win_func=lambda i, j: np.abs(i ** 2 - j ** 2) < 5000)
+
+    # plot
+    user_window.plot()
+
+.. image:: img/tutorial/user_window.png
+
+To compute DTW with user-specified constraints, use `dtw_low` method like:
+
+.. code-block:: python
+
+    # import lower dtw interface
+    from dtwalign import dtw_low
+    res = dtw_low(X,window=user_window,pattern=user_step_pattern)
+    res.plot_path()
 
-Utilities
-=========
+.. image:: img/tutorial/user_path.png