py-basic-dtw 0.1.5
A dynamic time warping (dtw) library that contains both classical and subsequence dtw techniques in a basic form which is readable.
License: MIT

# py-basic-dtw

A readable, not optimised, dynamic time warping (dtw) library that performs classical and subsequence dynamic time warping.

features:
- Classical DTW
- Subsequence DTW
- Two neighbourhood exclusion types for multiple matching ( Subsequence DTW):
  - Local maximum exclusion
  - Local distance exclusion
- Multidimensionl inputs
- Custom distance metrics via lambda functions
- Custom step weightings
- Custom dimension weightings
- Custom step pattern for cost matrix creation
---

## Installation with PIP
[Click here for the pypi link.](https://pypi.org/project/py-basic-dtw/)

```
  pip install py-basic-dtw
```

## Dependencies
- Numpy
  
## Import

```
  from pybasicDTW import Classical, Subsequence
```
---

## Quick Start

Setup the sequences in the correct format.
   1. If using a 1 dimensional sequence, you can leave it as a 1 dimensional array. For example:
      ``` python
      sequence = np.array([1,2,3,4,5,6,7,8,9])
      ```
   2. If using a multidimensional sequence, you must format the data so that each element in the array represents a list of values, across all dimensions, at that point in time. For example:
      ``` python
        sequence = np.array([ [1,2,3] , [1,2,3], [1,2,3] ])
      ```
      **Note that each element in the array has the same number of dimensions within it, this must be true.**

      **Also note that both inpt sequences, x and y, must have the same number of inner dimensions for all elements, this must be true.**

#### Classical DTW
``` python
  from pybasicDTW import Classical

  # create sequence, this is a 1 dimensional sequence
  x = np.array([0,0,0,1,1,1,2,3,4,5])
  y = np.array([1,1,2,2,2,3,3,3,4,4,5,6])

  # initalise and compute match
  basicdtw = Classical(x, y, metric = lambda x,y: np.square(x-y))

  # retrieve cost matrix
  localCostMatrix = basicdtw.LocalCost
  accumulatedCostMatrix = basicdtw.AccumulatedCost

  # retrieve path
  path = basicdtw.Path
  totalCost = basicdtw.TotalCost
```
#### Subsequence DTW
``` python
  from pybasicDTW import Subsequence

  # create sequence
  x = np.array([[0,0,0,1,1,1,2,3,4,5],[0,0,0,1,1,1,2,3,4,5]])
  y = np.array([[1,1,2,2,2,3,3,3,4,4],[0,0,0,1,1,1,2,3,4,5],[0,0,0,1,1,1,2,3,4,5]])

  # initalise and compute cost matrix
  basicdtw = Subsequence(x, y, metric = lambda x,y: np.square(x-y))

  # compute match, this can be repeated for following matches
  # default
  optimalPath, totalCost = basicdtw.FindMatch()
  # default expanded, invert = False will find the first maximum from the left.
  optimalPath, totalCost = basicdtw.FindMatch(exclusionType="LocalDistance", LocalMaxDist=1, invert=False, overlapMatches=False)
  # default expanded for Local Maximum Exclusion, overlapMatches = False will ensure the matched area will be excluded, hence the next match will not start within the previous match area.
   optimalPath, totalCost = basicdtw.FindMatch(exclusionType="LocalDistance", invert=False, overlapMatches=False)

  # retrieve cost matrix
  localCostMatrix = basicdtw.LocalCost
  accumulatedCostMatrix = basicdtw.AccumulatedCost
```

---

To be filled with more detailed explanations ....