Merge pull request #24 from HSE-LAMBDA/prep6

docs update

README.md

@@ -35,13 +35,15 @@ The following code snippet generates a noisy synthetic data, performs change poi
 sure that it has a shape `(seq_len, n_dims)`.
 ```python
 import roerich
-from roerich.algorithms import ChangePointDetectionClassifier
+from roerich.change_point import ChangePointDetectionClassifier
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
 # detection
-cpd = ChangePointDetectionClassifier()
+# base_classifier = 'logreg', 'qda', 'dt', 'rf', 'mlp', 'knn', 'nb'
+# metric = 'klsym', 'pesym', 'jsd', 'mmd', 'fd'
+cpd = ChangePointDetectionClassifier(base_classifier='mlp', metric='klsym', window_size=100)
 score, cps_pred = cpd.predict(X)
 
 # visualization
@@ -69,32 +71,3 @@ roerich.display(X, cps_true, score, cps_pred)
   <img src="https://contributors-img.web.app/image?repo=HSE-LAMBDA/roerich" />
 </a>
 
-## License
-
-```
-BSD 2-Clause License
-
-Copyright (c) 2020 Laboratory of methods for Big Data Analysis at HSE
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-```

docs/cpdclassifier.md

@@ -11,17 +11,32 @@
 
 ```python
 import roerich
-from roerich.algorithms import ChangePointDetectionClassifier
-from sklearn.discriminant_analysis import QuadraticDiscriminantAnalysis
+from roerich.change_point import ChangePointDetectionClassifier
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
+# change points detection
+# base_classifier = 'logreg', 'qda', 'dt', 'rf', 'mlp', 'knn', 'nb'
+# metric = 'klsym', 'pesym', 'jsd', 'mmd', 'fd'
+cpd = ChangePointDetectionClassifier(base_classifier='mlp', metric='klsym', periods=1,
+                                     window_size=100, step=1, n_runs=1)
+score, cps_pred = cpd.predict(X)
+
+# visualization
+roerich.display(X, cps_true, score, cps_pred)
+```
+
+## Usage with custom classifier
+
+```python
+from sklearn.discriminant_analysis import QuadraticDiscriminantAnalysis
+
 # sklearn-like binary classifier
 clf = QuadraticDiscriminantAnalysis()
 
 # change points detection
-cpd = ChangePointDetectionClassifier(base_classifier=clf, metric='KL_sym', periods=1,
+cpd = ChangePointDetectionClassifier(base_classifier=clf, metric='klsym', periods=1,
                                      window_size=100, step=1, n_runs=1)
 score, cps_pred = cpd.predict(X)
 

docs/cpdclassifier_cv.md

@@ -11,16 +11,31 @@
 ```python
 import roerich
 from roerich.change_point import ChangePointDetectionClassifierCV
-from sklearn.discriminant_analysis import QuadraticDiscriminantAnalysis
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
+# change points detection
+# base_classifier = 'logreg', 'qda', 'dt', 'rf', 'mlp', 'knn', 'nb'
+# metric = 'klsym', 'pesym', 'jsd', 'mmd', 'fd'
+cpd = ChangePointDetectionClassifierCV(base_classifier='nb', metric='klsym', periods=1,
+                                       window_size=100, step=1, n_splits=5)
+score, cps_pred = cpd.predict(X)
+
+# visualization
+roerich.display(X, cps_true, score, cps_pred)
+```
+
+## Usage with custom classifier
+
+```python
+from sklearn.discriminant_analysis import QuadraticDiscriminantAnalysis
+
 # sklearn-like binary classifier
 clf = QuadraticDiscriminantAnalysis()
 
 # change points detection
-cpd = ChangePointDetectionClassifierCV(base_classifier=clf, metric='KL_sym', periods=1,
+cpd = ChangePointDetectionClassifierCV(base_classifier=clf, metric='klsym', periods=1,
                                        window_size=100, step=1, n_splits=5)
 score, cps_pred = cpd.predict(X)
 

docs/cpdrulsif.md

@@ -14,18 +14,13 @@
 
 ```python
 import roerich
-from roerich.algorithms import ChangePointDetectionRuLSIF
-from roerich.algorithms import GBDTRuLSIFRegressor
+from roerich.change_point import ChangePointDetectionRuLSIF
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
-# RuLSIF regressor
-reg = GBDTRuLSIFRegressor(n_estimators=10)
-
 # change points detection
-cpd = ChangePointDetectionRuLSIF(base_regressor=reg, metric='PE', periods=1,
-                                 window_size=100, step=5, n_runs=1)
+cpd = ChangePointDetectionRuLSIF(periods=1, window_size=100, step=5, n_runs=1)
 score, cps_pred = cpd.predict(X)
 
 # visualization

docs/gbdtrulsif.md

@@ -11,7 +11,7 @@
 ## Usage
 
 ```python
-from roerich.algorithms import GBDTRuLSIFRegressor
+from roerich.density_ratio import GBDTRuLSIFRegressor
 from scipy.stats import norm, uniform
 import matplotlib.pyplot as plt
 import numpy as np

docs/nnclassifier.md

@@ -16,7 +16,7 @@ The density ratios help to calculate of different dissimilarity scores between t
 ## Usage
 
 ```python
-from roerich.algorithms import NNClassifier
+from roerich.density_ratio import NNClassifier
 from scipy.stats import norm, uniform
 import matplotlib.pyplot as plt
 import numpy as np

docs/nnrulsif.md

@@ -11,7 +11,7 @@
 ## Usage
 
 ```python
-from roerich.algorithms import NNRuLSIFRegressor
+from roerich.density_ratio import NNRuLSIFRegressor
 from scipy.stats import norm, uniform
 import matplotlib.pyplot as plt
 import numpy as np

docs/onnc.md

@@ -11,15 +11,44 @@
 
 ```python
 import roerich
-from roerich.algorithms import OnlineNNClassifier
+from roerich.change_point import OnlineNNClassifier
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
 # change points detection
-cpd = OnlineNNClassifier(net='default', scaler="default", metric="KL_sym",
-                        periods=1, window_size=10, lag_size=100, step=5,
-                        n_epochs=10, lr=0.01, lam=0.0001, optimizer="Adam")
+cpd = OnlineNNClassifier(periods=1, window_size=1, lag_size=100, step=1,
+                         n_epochs=1, lr=0.01, lam=0.0001, optimizer="Adam")
+
+score, cps_pred = cpd.predict(X)
+
+# visualization
+roerich.display(X, cps_true, score, cps_pred)
+```
+
+## Usage with custom network
+
+```python
+import torch.nn as nn
+
+# custom network
+class MyNN(nn.Module):
+    def __init__(self, n_inputs=1):
+        super(MyNN, self).__init__()
+        self.net = nn.Sequential(nn.Linear(n_inputs, 100), 
+                                 nn.ReLU(), 
+                                 nn.Linear(100, 100), 
+                                 nn.ReLU(), 
+                                 nn.Linear(100, 1), 
+                                 nn.Sigmoid())
+
+    def forward(self, x):
+        return self.net(x)
+
+
+# change points detection
+cpd = OnlineNNClassifier(net=MyNN, periods=1, window_size=1, lag_size=100, step=1,
+                         n_epochs=1, lr=0.001, lam=0.0001, optimizer="Adam")
 
 score, cps_pred = cpd.predict(X)
 

docs/onnr.md

@@ -14,15 +14,42 @@
 
 ```python
 import roerich
-from roerich.algorithms import OnlineNNRuLSIF
+from roerich.change_point import OnlineNNRuLSIF
 
 # generate time series
 X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
 
 # change points detection
-cpd = OnlineNNRuLSIF(alpha=0.2, net='default', scaler="default",
-                     periods=1, window_size=10, lag_size=100, step=5,
-                     n_epochs=10, lr=0.01, lam=0.001, optimizer="Adam")
+cpd = OnlineNNRuLSIF(alpha=0.1, window_size=1, lag_size=100, step=1,
+                     n_epochs=1, lr=0.01, lam=0.001, optimizer="Adam")
+
+score, cps_pred = cpd.predict(X)
+
+# visualization
+roerich.display(X, cps_true, score, cps_pred)
+```
+
+## Usage with custom network
+
+```python
+import torch.nn as nn
+
+# custom network
+class MyNN(nn.Module):
+    def __init__(self, n_inputs=1):
+        super(MyNN, self).__init__()
+        self.net = nn.Sequential(nn.Linear(n_inputs, 100), 
+                                 nn.ReLU(), 
+                                 nn.Linear(100, 100), 
+                                 nn.ReLU(), 
+                                 nn.Linear(100, 1))
+
+    def forward(self, x):
+        return self.net(x)
+
+# change points detection
+cpd = OnlineNNRuLSIF(net=MyNN, alpha=0.1, window_size=1, lag_size=100, step=1,
+                     n_epochs=1, lr=0.001, lam=0.001, optimizer="Adam")
 
 score, cps_pred = cpd.predict(X)
 

docs/window.md

@@ -0,0 +1,32 @@
+# SlidingWindows
+
+## Description
+
+`SlidingWindows` is an offline change point detection algorithm based on discrepancy measures [1]. It scans a signal with a two consecutive windows with some width. The method calculates discrepancies between observations inside these windows, and considers it as a change point detection score for the windows pair.
+
+Implemented discrepancy measures:
+
+- Energy distance ('energy')
+- Frechet distance ('fd')
+- Maximum Mean Discrepancy ('mmd')
+
+
+[1] C. Truong, L. Oudre, N. Vayatis. Selective review of offline change point detection methods. Signal Processing, 167:107299, 2020.
+
+## Usage
+
+```python
+import roerich
+from roerich.change_point import SlidingWindows
+
+# generate time series
+X, cps_true = roerich.generate_dataset(period=200, N_tot=2000)
+
+# change points detection
+# metric = 'fd', 'mmd', 'energy'
+cpd = SlidingWindows(metric='mmd', window_size=100)
+score, cps_pred = cpd.predict(X)
+
+# visualization
+roerich.display(X, cps_true, score, cps_pred)
+```

mkdocs.yml

@@ -27,11 +27,12 @@ nav:
     - Home: 'index.md'
     - Change point: about.md
     - Detection algorithms:
-        - EnergyDistanceCalculator: energy.md
         - ChangePointDetectionClassifier: cpdclassifier.md
         - ChangePointDetectionClassifierCV: cpdclassifier_cv.md
-        - ChangePointDetectionRuLSIF: cpdrulsif.md
         - OnlineNNClassifier: onnc.md
+        - SlidingWindows: window.md
+        - EnergyDistanceCalculator: energy.md
+        - ChangePointDetectionRuLSIF: cpdrulsif.md
         - OnlineNNRuLSIF: onnr.md
     - Explanation:
         - MatrixImportance: matrix.md

setup.cfg

@@ -1,9 +1,9 @@
 [metadata]
 name = roerich
-version = 0.5.0
+version = 0.6.0
 author = Mikhail Hushchyn, Kenenbek Arzymatov
 author_email = [email protected], [email protected]
-description = Roerich is a python library for online and offline change point detection in time series data based on machine learning.
+description = Change point detection.
 long_description = file: README.md
 long_description_content_type = text/markdown
 url = https://github.com/HSE-LAMBDA/roerich