2d PM - gaussian, overlap, disjoint and benchmark

README.md

@@ -29,7 +29,7 @@ ImputeGAP is a comprehensive framework designed for time series imputation algor
 
 The following prerequisites are required to use ImputeGAP:
 
-- Python version 3.12
+- Python version 3.10 / 3.11 / 3.12 (recommended)
 - Unix-compatible environment for execution
 
 To create and set up an environment with Python 3.12, please refer to the [installation guide](https://github.com/eXascaleInfolab/ImputeGAP/tree/main/procedure/installation).
@@ -89,9 +89,8 @@ ts_1.load_timeseries(utils.search_path("eeg-alcohol"), max_series=5, max_values=
 ts_1.normalize(normalizer="z_score")
 
 # [OPTIONAL] you can plot your raw data / print the information
-ts_1.plot(input_data=ts_1.data, title="raw data", max_series=10, max_values=100, save_path="./imputegap/assets")
+ts_1.plot(input_data=ts_1.data, max_series=10, max_values=100, save_path="./imputegap/assets")
 ts_1.print(limit_series=10)
-
 ```
 
 ---
@@ -115,12 +114,12 @@ ts_1 = TimeSeries()
 ts_1.load_timeseries(utils.search_path("eeg-alcohol"))
 ts_1.normalize(normalizer="min_max")
 
-# 3. contamination of the data with MCAR scenario
-infected_data = ts_1.Contamination.mcar(ts_1.data, series_rate=0.4, missing_rate=0.2, use_seed=True)
+# 3. contamination of the data with MCAR pattern
+incomp_data = ts_1.Contamination.mcar(ts_1.data, series_rate=0.2, missing_rate=0.2, seed=True)
 
 # [OPTIONAL] you can plot your raw data / print the contamination
-ts_1.print(limit_series=10)
-ts_1.plot(ts_1.data, infected_data, title="contamination", max_series=1, save_path="./imputegap/assets")
+ts_1.print(limit_timestamps=12, limit_series=7)
+ts_1.plot(ts_1.data, incomp_data, max_series=9, subplot=True, save_path="./imputegap/assets")
 ```
 
 ---
@@ -146,25 +145,29 @@ ts_1.load_timeseries(utils.search_path("eeg-alcohol"))
 ts_1.normalize(normalizer="min_max")
 
 # 3. contamination of the data
-infected_data = ts_1.Contamination.mcar(ts_1.data)
+incomp_data = ts_1.Contamination.mcar(ts_1.data)
+
+# [OPTIONAL] save your results in a new Time Series object
+ts_2 = TimeSeries().import_matrix(incomp_data)
 
 # 4. imputation of the contaminated data
 # choice of the algorithm, and their parameters (default, automl, or defined by the user)
-cdrec = Imputation.MatrixCompletion.CDRec(infected_data)
+cdrec = Imputation.MatrixCompletion.CDRec(ts_2.data)
 
 # imputation with default values
 cdrec.impute()
 # OR imputation with user defined values
-cdrec.impute(params={"rank": 5, "epsilon": 0.01, "iterations": 100})
+# >>> cdrec.impute(params={"rank": 5, "epsilon": 0.01, "iterations": 100})
 
 # [OPTIONAL] save your results in a new Time Series object
-ts_3 = TimeSeries().import_matrix(cdrec.imputed_matrix)
+ts_3 = TimeSeries().import_matrix(cdrec.recov_data)
 
 # 5. score the imputation with the raw_data
 cdrec.score(ts_1.data, ts_3.data)
 
-# [OPTIONAL] print the results
-ts_3.print_results(cdrec.metrics)
+# 6. display the results
+ts_3.print_results(cdrec.metrics, algorithm="cdrec")
+ts_3.plot(input_data=ts_1.data, incomp_data=ts_2.data, recov_data=ts_3.data, max_series=9, subplot=True, save_path="./imputegap/assets")
 ```
 
 ---
@@ -190,24 +193,21 @@ ts_1.load_timeseries(utils.search_path("eeg-alcohol"))
 ts_1.normalize(normalizer="min_max")
 
 # 3. contamination of the data
-infected_data = ts_1.Contamination.mcar(ts_1.data)
+miss_matrix = ts_1.Contamination.mcar(ts_1.data)
 
 # 4. imputation of the contaminated data
 # imputation with AutoML which will discover the optimal hyperparameters for your dataset and your algorithm
-cdrec = Imputation.MatrixCompletion.CDRec(infected_data).impute(user_def=False, params={"ground_truth": ts_1.data,
-                                                                                        "optimizer": "bayesian",
-                                                                                        "options": {"n_calls": 5}})
+cdrec = Imputation.MatrixCompletion.CDRec(miss_matrix).impute(user_def=False, params={"input_data": ts_1.data, "optimizer": "bayesian", "options": {"n_calls": 3}})
 
 # 5. score the imputation with the raw_data
 cdrec.score(ts_1.data, cdrec.recov_data)
 
-# 6. [OPTIONAL] display the results
+# 6. display the results
 ts_1.print_results(cdrec.metrics)
-ts_1.plot(input_data=ts_1.data, incomp_data=infected_data, imputed_data=cdrec.recov_data, title="imputation",
-          max_series=1, save_path="./imputegap/assets", display=True)
+ts_1.plot(input_data=ts_1.data, incomp_data=miss_matrix, recov_data=cdrec.recov_data, max_series=9, subplot=True, save_path="./imputegap/assets", display=True)
 
-# 7. [OPTIONAL] save hyperparameters
-utils.save_optimization(optimal_params=cdrec.parameters, algorithm="cdrec", dataset="eeg", optimizer="b")
+# 7. save hyperparameters
+utils.save_optimization(optimal_params=cdrec.parameters, algorithm="cdrec", dataset="eeg", optimizer="t")
 ```
 
 ---
@@ -234,7 +234,7 @@ ts_1 = TimeSeries()
 ts_1.load_timeseries(utils.search_path("eeg-alcohol"))
 
 # 3. call the explanation of your dataset with a specific algorithm to gain insight on the Imputation results
-shap_values, shap_details = Explainer.shap_explainer(input_data=ts_1.data, file_name="eeg-alcohol", algorithm="cdrec")
+shap_values, shap_details = Explainer.shap_explainer(input_data=ts_1.data, extractor="pycatch22", pattern="mcar", missing_rate=0.25, limit_ratio=1, split_ratio=0.7, file_name="eeg-alcohol", algorithm="cdrec")
 
 # [OPTIONAL] print the results with the impact of each feature.
 Explainer.print(shap_values, shap_details)

build/lib/imputegap/recovery/explainer.py

@@ -35,9 +35,9 @@ class Explainer:
     launch_shap_model(x_dataset, x_information, y_dataset, file, algorithm, splitter=10, display=False, verbose=False)
         Launch the SHAP model to explain the dataset features.
 
-    shap_explainer(raw_data, algorithm="cdrec", params=None, contamination="mcar", missing_rate=0.4,
-                   block_size=10, protection=0.1, use_seed=True, seed=42, limitation=15, splitter=0,
-                   file_name="ts", display=False, verbose=False)
+    shap_explainer(raw_data, algorithm="cdrec", params=None, extractor="pycatch22",
+                   contamination="mcar", missing_rate=0.4, block_size=10, protection=0.1, use_seed=True, seed=42,
+                   limitation=15, splitter=0, file_name="ts", display=False, verbose=False)
         Handle parameters and set variables to launch the SHAP model.
 
     """

build/lib/imputegap/runner_datasets.py

@@ -39,7 +39,7 @@
     data_n.plot(input_data=data_n.data, save_path="./dataset/docs/" + dataset + "", display=False)
 
     categories, features = Explainer.load_configuration()
-    characteristics, descriptions = Explainer.extract_features(data=data_n.data, features_categories=categories, features_list=features, do_catch24=False)
+    characteristics, descriptions = Explainer.extractor_pycatch(data=data_n.data, features_categories=categories, features_list=features, do_catch24=False)
 
     p = "./dataset/docs/"+dataset+"/features_"+dataset+".txt"
     with open(p, 'w') as f:

docs/generation/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e41eca0a3efc7159e0af65e9f919fd5f
+config: 786669019b63ab7790c3ca690c5f3924
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/generation/build/html/autosummary/imputegap.algorithms.cdrec.html

@@ -6,7 +6,7 @@
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>imputegap.algorithms.cdrec &mdash; imputegap 1.0.2 documentation</title>
+  <title>imputegap.algorithms.cdrec &mdash; imputegap 1.0.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../static/pygments.css?v=80d5e7a1" />
       <link rel="stylesheet" type="text/css" href="../static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="../static/custom.css" />
@@ -15,14 +15,14 @@
     <link rel="shortcut icon" href="https://www.naterscreations.com/imputegap/favicon.png"/>
       <script src="../static/jquery.js?v=5d32c60e"></script>
       <script src="../static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../static/documentation_options.js?v=292eb321"></script>
+      <script src="../static/documentation_options.js?v=baaebd52"></script>
       <script src="../static/doctools.js?v=9bcbadda"></script>
       <script src="../static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
     <link rel="next" title="imputegap.algorithms.stmvl" href="imputegap.algorithms.stmvl.html" />
-    <link rel="prev" title="imputegap.recovery.benchmarking" href="imputegap.recovery.benchmarking.html" /> 
+    <link rel="prev" title="imputegap.recovery.benchmark" href="imputegap.recovery.benchmark.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -51,7 +51,7 @@
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.optimization.html">imputegap.recovery.optimization</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.explainer.html">imputegap.recovery.explainer</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.evaluation.html">imputegap.recovery.evaluation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmarking.html">imputegap.recovery.benchmarking</a></li>
+<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmark.html">imputegap.recovery.benchmark</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">imputegap.algorithms.cdrec</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.stmvl.html">imputegap.algorithms.stmvl</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.iim.html">imputegap.algorithms.iim</a></li>
@@ -94,7 +94,7 @@
 <p class="rubric">Functions</p>
 <table class="autosummary longtable docutils align-default">
 <tbody>
-<tr class="row-odd"><td><p><a class="reference internal" href="../imputegap.cdrec.html#imputegap.algorithms.cdrec.cdrec" title="imputegap.algorithms.cdrec.cdrec"><code class="xref py py-obj docutils literal notranslate"><span class="pre">cdrec</span></code></a>(contamination, truncation_rank, ...[, ...])</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="../imputegap.cdrec.html#imputegap.algorithms.cdrec.cdrec" title="imputegap.algorithms.cdrec.cdrec"><code class="xref py py-obj docutils literal notranslate"><span class="pre">cdrec</span></code></a>(incomp_data, truncation_rank, ...[, ...])</p></td>
 <td><p>CDRec algorithm for matrix imputation of missing values using Centroid Decomposition.</p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="../imputegap.cdrec.html#imputegap.algorithms.cdrec.native_cdrec" title="imputegap.algorithms.cdrec.native_cdrec"><code class="xref py py-obj docutils literal notranslate"><span class="pre">native_cdrec</span></code></a>(__py_matrix, __py_rank, ...)</p></td>
@@ -108,14 +108,14 @@
            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
-        <a href="imputegap.recovery.benchmarking.html" class="btn btn-neutral float-left" title="imputegap.recovery.benchmarking" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+        <a href="imputegap.recovery.benchmark.html" class="btn btn-neutral float-left" title="imputegap.recovery.benchmark" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="imputegap.algorithms.stmvl.html" class="btn btn-neutral float-right" title="imputegap.algorithms.stmvl" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2024, Quentin Nater.</p>
+    <p>&#169; Copyright 2025, Quentin Nater.</p>
   </div>
 
   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a

docs/generation/build/html/autosummary/imputegap.algorithms.html

@@ -6,7 +6,7 @@
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>imputegap.algorithms &mdash; imputegap 1.0.2 documentation</title>
+  <title>imputegap.algorithms &mdash; imputegap 1.0.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../static/pygments.css?v=80d5e7a1" />
       <link rel="stylesheet" type="text/css" href="../static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="../static/custom.css" />
@@ -15,7 +15,7 @@
     <link rel="shortcut icon" href="https://www.naterscreations.com/imputegap/favicon.png"/>
       <script src="../static/jquery.js?v=5d32c60e"></script>
       <script src="../static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../static/documentation_options.js?v=292eb321"></script>
+      <script src="../static/documentation_options.js?v=baaebd52"></script>
       <script src="../static/doctools.js?v=9bcbadda"></script>
       <script src="../static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../static/js/theme.js"></script>
@@ -49,7 +49,7 @@
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.optimization.html">imputegap.recovery.optimization</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.explainer.html">imputegap.recovery.explainer</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.evaluation.html">imputegap.recovery.evaluation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmarking.html">imputegap.recovery.benchmarking</a></li>
+<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmark.html">imputegap.recovery.benchmark</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.cdrec.html">imputegap.algorithms.cdrec</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.stmvl.html">imputegap.algorithms.stmvl</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.iim.html">imputegap.algorithms.iim</a></li>
@@ -99,7 +99,7 @@
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2024, Quentin Nater.</p>
+    <p>&#169; Copyright 2025, Quentin Nater.</p>
   </div>
 
   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a

docs/generation/build/html/autosummary/imputegap.algorithms.iim.html

@@ -6,7 +6,7 @@
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>imputegap.algorithms.iim &mdash; imputegap 1.0.2 documentation</title>
+  <title>imputegap.algorithms.iim &mdash; imputegap 1.0.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../static/pygments.css?v=80d5e7a1" />
       <link rel="stylesheet" type="text/css" href="../static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="../static/custom.css" />
@@ -15,7 +15,7 @@
     <link rel="shortcut icon" href="https://www.naterscreations.com/imputegap/favicon.png"/>
       <script src="../static/jquery.js?v=5d32c60e"></script>
       <script src="../static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../static/documentation_options.js?v=292eb321"></script>
+      <script src="../static/documentation_options.js?v=baaebd52"></script>
       <script src="../static/doctools.js?v=9bcbadda"></script>
       <script src="../static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../static/js/theme.js"></script>
@@ -51,7 +51,7 @@
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.optimization.html">imputegap.recovery.optimization</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.explainer.html">imputegap.recovery.explainer</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.evaluation.html">imputegap.recovery.evaluation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmarking.html">imputegap.recovery.benchmarking</a></li>
+<li class="toctree-l1"><a class="reference internal" href="imputegap.recovery.benchmark.html">imputegap.recovery.benchmark</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.cdrec.html">imputegap.algorithms.cdrec</a></li>
 <li class="toctree-l1"><a class="reference internal" href="imputegap.algorithms.stmvl.html">imputegap.algorithms.stmvl</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">imputegap.algorithms.iim</a></li>
@@ -94,7 +94,7 @@
 <p class="rubric">Functions</p>
 <table class="autosummary longtable docutils align-default">
 <tbody>
-<tr class="row-odd"><td><p><a class="reference internal" href="../imputegap.iim.html#imputegap.algorithms.iim.iim" title="imputegap.algorithms.iim.iim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">iim</span></code></a>(contamination, number_neighbor, algo_code)</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="../imputegap.iim.html#imputegap.algorithms.iim.iim" title="imputegap.algorithms.iim.iim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">iim</span></code></a>(incomp_data, number_neighbor, algo_code)</p></td>
 <td><p>Perform imputation using the Iterative Imputation Method (IIM) algorithm.</p></td>
 </tr>
 </tbody>
@@ -112,7 +112,7 @@
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2024, Quentin Nater.</p>
+    <p>&#169; Copyright 2025, Quentin Nater.</p>
   </div>
 
   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a