Merge pull request #13 from edahelsinki/slipmap

Slipmap

.github/workflows/python-pytest.yml

@@ -11,27 +11,44 @@ on:
     paths: ["slisemap/*.py", "tests/*.py"]
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
-
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+          cache: "pip"
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install pytest build
-          if [ -f requirements.txt ]; then python -m pip install -r requirements.txt; fi
+          python -m pip install --upgrade pip pytest pytest-cov
+          python -m pip install -e ".[tuning]"
+      - name: Test with pytest
+        run: |
+          pytest --cov-report term --cov=slisemap/ --cov-fail-under=8
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+      - run: python -m pip install --upgrade pip build
       - name: Build package
         run: |
           python -m build
           python -c "import os, glob; assert os.path.getsize(sorted(glob.glob('dist/slisemap-*.whl'))[-1]) > 10_000"
-      - name: Test with pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+      - run: python -m pip install --upgrade pip ruff
+      - name: Lint with Ruff
         run: |
-          pytest
+          ruff check --output-format=github
+          ruff format --check

CITATIONS.bib

@@ -1,4 +1,4 @@
-@article{bjorklund2022slisemap,
+@article{bjorklund2024slisemap,
   title      = {{SLISEMAP}: Supervised dimensionality reduction through local explanations},
   shorttitle = {{SLISEMAP}},
   author     = {Bj{\"o}rklund, Anton and M{\"a}kel{\"a}, Jarmo and Puolam{\"a}ki, Kai},
@@ -11,17 +11,3 @@ @article{bjorklund2022slisemap
   month      = {Jan},
   pages      = {1--43}
 }
-
-@article{bjorklund2022slisemaparxiv,
-  title        = {{SLISEMAP}: Supervised dimensionality reduction through local explanations},
-  shorttitle   = {{SLISEMAP}},
-  author       = {Bj{\"o}rklund, Anton and M{\"a}kel{\"a}, Jarmo and Puolam{\"a}ki, Kai},
-  year         = {2022},
-  journal      = {arXiv:2201.04455 [cs]},
-  eprint       = {2201.04455},
-  eprinttype   = {arxiv},
-  primaryclass = {cs},
-  url          = {http://arxiv.org/abs/2201.04455},
-  doi          = {10.48550/ARXIV.2201.04455},
-  publisher    = {arXiv}
-}

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Anton Björklund, Jarmo Mäkelä, and Kai Puolamäki
+Copyright (c) 2024 Anton Björklund, Jarmo Mäkelä, and Kai Puolamäki
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -7,16 +7,32 @@
 [![DOI](https://img.shields.io/badge/DOI-10.1007%2Fs10994--022--06261--1-%23fcb426)](https://doi.org/10.1007/s10994-022-06261-1)
 # SLISEMAP: Combine supervised dimensionality reduction with local explanations
 
-SLISEMAP is a supervised dimensionality reduction method, that takes data, in the form of vectors, and predictions from a *black box* regression or classification model as input. SLISEMAP then simultaneously finds local explanations for all data items and builds a (typically) two-dimensional global visualisation of the black box model such that data items with similar local explanations are projected nearby. The explanations consist of *white box* models that locally approximate the *black box* model.
+SLISEMAP is a supervised dimensionality reduction method, that takes data, in the form of vectors, and predictions from a "black box" regression or classification model as input. SLISEMAP then simultaneously finds local explanations for all data items and builds a (typically) two-dimensional global visualisation of the black box model such that data items with similar local explanations are projected nearby. The explanations consists of interpretable models that locally approximate the "black box" model.
 
-SLISEMAP is implemented in *Python* using *PyTorch* for efficient optimisation, and optional GPU-acceleration. For more information see the [full paper](https://doi.org/10.1007/s10994-022-06261-1) ([arXiv](https://arxiv.org/abs/2201.04455)), the [demo paper](https://github.com/edahelsinki/slisemap/blob/main/examples/demo_paper.pdf), the [demo video](https://youtu.be/zvcFYItwRlQ) ([slides](https://github.com/edahelsinki/slisemap/blob/main/examples/demo_presentation.pdf)), the [examples](https://github.com/edahelsinki/slisemap/tree/main/examples), or the [documentation](https://edahelsinki.github.io/slisemap/slisemap).
+SLISEMAP is implemented in *Python* using *PyTorch* for efficient optimisation, and optional GPU-acceleration. For more information see the [papers](#citations), the [examples](https://github.com/edahelsinki/slisemap/tree/main/examples), or the [documentation](https://edahelsinki.github.io/slisemap/slisemap).
 
+*This library also includes the faster SLIPMAP variant, that uses "prototypes" to speed up
+the calculations (linear time and memory complexity instead of quadratic).
+SLIPMAP is largely compatible with SLISEMAP, just change the class name (`Slisemap` to `Slipmap`, see example below).*
 
-## Citation
 
-> *Björklund, A., Mäkelä, J. & Puolamäki, K. (2023).*  
+## Citations
+
+The full SLISEMAP paper ([arXiv](https://arxiv.org/abs/2201.04455) and [supplements](https://github.com/edahelsinki/slisemap/tree/slisemap_experiments)):
+> *Björklund, A., Mäkelä, J., & Puolamäki, K. (2023).*  
 > **SLISEMAP: Supervised dimensionality reduction through local explanations.**  
-> Machine Learning 112, 1-43. [DOI: 10.1007/s10994-022-06261-1](https://doi.org/10.1007/s10994-022-06261-1)  
+> Machine Learning 112, 1-43. DOI: [10.1007/s10994-022-06261-1](https://doi.org/10.1007/s10994-022-06261-1)  
+
+The short demo paper ([video](https://youtu.be/zvcFYItwRlQ) and [slides](https://github.com/edahelsinki/slisemap/blob/main/examples/demo_presentation.pdf)):
+> *Björklund, A., Mäkelä, J., & Puolamäki, K. (2023).*  
+> **SLISEMAP: Combining Supervised Dimensionality Reduction with Local Explanations.**  
+> Machine Learning and Knowledge Discovery in Databases. ECML PKDD 2022. Lecture Notes in Computer Science, vol 13718. DOI: [10.1007/978-3-031-26422-1_41](https://doi.org/10.1007/978-3-031-26422-1_41).
+
+The new SLIPMAP paper ([supplements](https://github.com/edahelsinki/slisemap/tree/slipmap_experiments)):
+> *Björklund, A., Seppäläinen, L., & Puolamäki, K. (2024).*  
+> **SLIPMAP: Fast and Robust Manifold Visualisation for Explainable AI**  
+> To appear in: Advances in Intelligent Data Analysis XXII. IDA 2024. Lecture Notes in Computer Science.  
+
 
 ## Installation
 
@@ -32,6 +48,12 @@ Or install the latest version directly from [GitHub](https://github.com/edahelsi
 pip install git+https://github.com/edahelsinki/slisemap
 ```
 
+To use the built-in hyperparameter tuning you also need `scikit-optimize`, which is automatically installed if you do:
+
+```sh
+pip install slisemap[tuning]
+```
+
 ### PyTorch
 
 Since SLISEMAP utilises PyTorch for efficient calculations, you might want to install a version that is optimised for your hardware. See [https://pytorch.org/get-started/locally](https://pytorch.org/get-started/locally/) for details.
@@ -51,4 +73,11 @@ sm.plot(clusters=5, bars=5)
 ```
 ![Example plot of the results from using SLISEMAP on the *Auto MPG* dataset](docs/autompg.webp)
 
+To use the faster SLIPMAP variant just replace the relevant lines:
+
+```python
+from slisemap import Slipmap
+sm = Slipmap(X, y, radius=2.0, lasso=0.01)
+```
+
 See the [examples](https://github.com/edahelsinki/slisemap/tree/main/examples) for more detailed examples, and the [documentation](https://edahelsinki.github.io/slisemap/slisemap.html) for more detailed instructions.

docs/slisemap.plot.md

@@ -0,0 +1 @@
+# ::: slisemap.plot

docs/slisemap.slipmap.md

@@ -0,0 +1 @@
+# ::: slisemap.slipmap