Skip to content

Commit 150f9e8

Browse files
passalispassalis
committed
Doc update
1 parent b3df9e7 commit 150f9e8

File tree

7 files changed

+175
-46
lines changed

7 files changed

+175
-46
lines changed

‎docs/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,9 +56,9 @@
5656
# built documents.
5757
#
5858
# The short X.Y version.
59-
version = '0.2.3'
59+
version = '0.2.9'
6060
# The full version, including alpha/beta/rc tags.
61-
release = '0.2.3'
61+
release = '0.2.9'
6262

6363
# The language for content autogenerated by Sphinx. Refer to documentation
6464
# for a list of supported languages.

‎docs/examples.rst

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
.. _examples-link:
2+
3+
***********************
4+
Examples and Tutorials
5+
***********************
6+
7+
We provide `examples <https://github.com/passalis/sef/blob/master/examples>`_ using six different datasets (15-Scene, Corel, MNIST, Yale, KTH, and 20NG) to reproduce the results obtained in the original research paper. Note that slight differences from the original `paper <https://arxiv.org/abs/1706.05692>`_ are due to some changes (batch-based optimization, faster estimation of the scaling factor, port to PyTorch). For all the reported results a `Linear SVM <https://github.com/passalis/sef/blob/master/sef_dr/classification.py>`_ is trained, unless otherwise stated.
8+
9+
10+
Prerequisites
11+
=============
12+
To run the examples you have to install PySEF (please also refer to :ref:`installation-link`)::
13+
14+
pip install pysef
15+
16+
Before running any of the following examples, please download the pre-extracted feature vectors from the following `drobpox folder <https://www.dropbox.com/sh/9qlt6b54v5jxial/AABccAu09ngHWPoj7kc9HOaXa?dl=0>`_ into a folder named *data* and execute the script from the same root folder (or simply update the data path in the code). Refer to :ref:`Data loading <data-loading>` for more details.
17+
18+
Please also install *matplotlib*, which is also needed for some of the following examples/tutorials::
19+
20+
pip install matplotlib
21+
22+
23+
Linear approximation of a high-dimensional technique
24+
====================================================
25+
26+
In `unsupervised_approximation_multiple.py <https://github.com/passalis/sef/blob/master/examples/unsupervised_approximation_multiple.py>`_ we demonstrate how to recreate the 50-d PCA using just 10 dimensions. The proposed method (abbreviated as S-PCA) is compared to the 10-d PCA method. To run the example, simply download the aforementioned file and execute it::
27+
28+
python unsupervised_approximation_multiple.py
29+
30+
The following results should be obtained:
31+
32+
=========== ======== ==========
33+
Dataset PCA S-PCA
34+
=========== ======== ==========
35+
15-scene 61.94% **67.20%**
36+
Corel 36.18% **38.55%**
37+
MNIST 82.88% **84.71%**
38+
Yale 56.69% **65.16%**
39+
KTH 76.82% **86.56%**
40+
20NG 39.73% **45.79%**
41+
=========== ======== ==========
42+
43+
44+
45+
Supervised dimensionality reduction
46+
===================================
47+
48+
In `supervised_reduction_multiple.py <https://github.com/passalis/sef/blob/master/examples/supervised_reduction_multiple.py>`_ we demonstrate how to perform supervised dimensionality reduction using the SEF. Two different setups are used: a) *S-LDA-1*, where the same dimensionality as the LDA method is used, and b) *S-LDA-2*, where the number of dimensions is doubled. To run the example, simply download the aforementioned file and execute it::
49+
50+
python supervised_reduction_multiple.py
51+
52+
The following results should be obtained:
53+
54+
=========== ======== ============= ==============
55+
Dataset LDA S-LDA-1 S-LDA-2
56+
=========== ======== ============= ==============
57+
15-scene 66.76% 75.58% **76.98%**
58+
Corel 37.28% **42.58%** 42.33%
59+
MNIST 85.66% 89.03% **89.27%**
60+
Yale 93.95% 92.50% **92.74%**
61+
KTH 90.38% 90.73% **91.66%**
62+
20NG 63.57% **70.35%** 70.25%
63+
=========== ======== ============= ==============
64+
65+
66+
67+
Providing out-of-sample-extensions
68+
===================================
69+
70+
In `linear_outofsample_mutiple.py <https://github.com/passalis/sef/blob/master/examples/linear_outofsample_mutiple.py>`_ we demonstrate how to provide out-of-sample extensions for the ISOMAP technique. Two different setups are used: a) *cS-ISOMAP-1*, where the dimensionality of the projection is set to 10, and b) *cS-ISOMAP-2*, where the dimensionality of the projection is set to 20. The proposed method is compared to performing linear regression (LR). To run the example, simply download the aforementioned file and execute it::
71+
72+
python linear_outofsample_mutiple.py
73+
74+
The following results should be obtained:
75+
76+
=========== ======== ============= ==============
77+
Dataset LR cS-ISOMAP-1 cS-ISOMAP-2
78+
=========== ======== ============= ==============
79+
15-scene 58.29% 67.26% **69.04%**
80+
Corel 34.93% 38.70% **40.45%**
81+
MNIST 85.11% 85.93% **93.37%**
82+
Yale 35.97% 62.09% **82.58%**
83+
KTH 67.20% 86.56% **89.80%**
84+
20NG 33.14% 41.52% **47.97%**
85+
=========== ======== ============= ==============
86+
87+
Kernel extensions can be also used (`kernel_outofsample_mutiple.py <https://github.com/passalis/sef/blob/master/examples/kernel_outofsample_mutiple.py>`_). The following results should be obtained:
88+
89+
90+
=========== ======== ============= ==============
91+
Dataset KR cKS-ISOMAP-1 cKS-ISOMAP-2
92+
=========== ======== ============= ==============
93+
15-scene 60.10% 63.89% **68.14%**
94+
Corel 36.22% 37.85% **42.27%**
95+
MNIST 89.48% 88.30% **91.35%**
96+
Yale 46.94% 29.84% **62.25%**
97+
KTH 72.31% 78.22% **83.31%**
98+
20NG 44.50% 41.57% **48.81%**
99+
=========== ======== ============= ==============
100+
101+
102+
SVM-based analysis
103+
==================
104+
PySEF can be used to mimic the similarity induced by the hyperplanes of the 1-vs-1 SVMs and perform DR (`svm_approximation_multiple.py <https://github.com/passalis/sef/blob/master/examples/svm_approximation_multiple.py>`_). The proposed technique is combined with a lightweight Nearest Centroid Classifier. Two different setups are used: a) *S-SVM-A-1*, where the dimensionality of the projection is set to the number of classes, and b) *S-SVM-A-1*, where the dimensionality of the projection is set to twice the number of classes. To run the example, simply download the aforementioned file and execute it::
105+
106+
python svm_approximation_multiple.py
107+
108+
The following results should be obtained:
109+
110+
=========== ======== ============= ==============
111+
Dataset Original S-SVM-A-1 S-SVM-A-1
112+
=========== ======== ============= ==============
113+
15-scene 59.67% **74.47%** 74.10%
114+
Corel 37.40% **42.15%** 41.77%
115+
MNIST 80.84% 86.71% **86.80%**
116+
Yale 13.95% 84.44% **88.63%**
117+
KTH 79.72% 92.24% **94.09%**
118+
20NG 60.79% 65.37% **65.78%**
119+
=========== ======== ============= ==============
120+
121+
122+
123+
PySEF tutorials
124+
===============
125+
126+
To run the tutorials you have to install the Jupyter Notebook (also refer to `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`_)::
127+
128+
pip install jupyter
129+
130+
Then, download the notebook tutorial you are interested in. Currently two tutorial are available: a) `Supervised dimensionality reduction <https://github.com/passalis/sef/blob/master/tutorials/Supervised%20DR.ipynb>`_, and b) `Defining new dimensionality reduction methods <https://github.com/passalis/sef/blob/master/tutorials/Defining%20new%20methods.ipynb>`_. Then, navigate to the folder that contains the notebook and start the Jupyter Notebook::
131+
132+
jupyter notebook
133+
134+
Finally, navigate to the default URL of Jupyter web app (`http://localhost:8888 <http://localhost:8888>`_) and select the notebook. Please make sure that you appropriately update the folder that contains the MNIST dataset when running the tutorials (refer to :ref:`Data loading <data-loading>` for more details, or just create an empty folder named *data* in the same root folder as the notebook and the dataset will be automatically downloaded).
135+
136+

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ The vast majority of Dimensionality Reduction techniques rely on second-order st
2121

2222
installation
2323
usage
24+
examples
2425
extending
2526

2627

‎docs/installation.rst

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,4 @@ To install the latest version availabe at github, clone our repository and manua
2828
python setup.py install --user
2929

3030

31-
Running the examples/tutorials
32-
==============================
3331

34-
*Keras* and *matplotlib* are also needed to run the examples and the tutorials provided in our github repository (keras provide an easy way to load the *MNIST* dataset and *matplotlib* to plot the loss function during the optimization). Therefore, before running the supplied examples/tutorials you have to install keras (along with an appropriate backend, e.g., the *Tensorflow* library) and matplotlib::
35-
36-
pip install keras
37-
pip install tensorflow
38-
pip install matplotlib
39-
40-
Note that these are only needed for the specific examples and they are not mandatory for using the *PySEF* library.

‎docs/usage.rst

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,25 @@ To move the model back to cpu, the *.cpu()* method should be called::
2626
proj.cpu()
2727

2828

29+
.. _data-loading:
30+
31+
Data loading
32+
==========================
33+
34+
To allow for easily evaluating and comparing different dimensionality reduction techniques we have included data loading capabilities in PySEF. Before running any of the following examples, please download the pre-extracted feature vectors from the following `drobpox folder <https://www.dropbox.com/sh/9qlt6b54v5jxial/AABccAu09ngHWPoj7kc9HOaXa?dl=0>`_. After downloading them into a folder, e.g., let's say that we download them into the */home/nick/my_data* folder, you can easily load any of the six supported datasets as follows::
35+
36+
from sef_dr.datasets import dataset_loader
37+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='mnist', dataset_path='/home/nick/my_data')
38+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='20ng', dataset_path='/home/nick/my_data')
39+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='15scene', dataset_path='/home/nick/my_data')
40+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='corel', dataset_path='/home/nick/my_data')
41+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='yale', dataset_path='da/home/nick/my_datata')
42+
train_data, train_labels, test_data, test_labels = dataset_loader(dataset='kth', dataset_path='da/home/nick/my_datata')
43+
44+
The *MNIST dataset* and the *20NG dataset* will be automatically downloaded into the specified folder the first time that the *dataset_loader()* function will be called. Please refer to `this paper <http://ieeexplore.ieee.org/document/8004500/>`_ for a detailed description of the evaluation setup and feature extraction process.
45+
46+
47+
2948
Recreating the geometry of a high dimensional space into a space with less dimensions
3049
=====================================================================================
3150
In `unsupervised_approximation.py <https://github.com/passalis/sef/blob/master/examples/unsupervised_approximation.py>`_ we demonstrate how to recreate the 50-d PCA using just 10 dimensions::
@@ -147,13 +166,4 @@ NCC - Linear SEF 10d 86.50%
147166
====================== ============== ==========
148167

149168

150-
More examples
151-
=============
152-
More examples using six different datasets (15-Scene, Corel, MNIST, Yale, KTH, 20NG) are provided on `Github <https://github.com/passalis/sef/blob/master/examples>`_. To run these examples you have to download the extracted descriptors from `datasets <https://www.dropbox.com/sh/9qlt6b54v5jxial/AABccAu09ngHWPoj7kc9HOaXa?dl=0>`_ into the *data* folder. Note that slight differences from the original research `paper <https://arxiv.org/abs/1706.05692>`_ are due to some changes (batch-based optimization, faster estimation of the scaling factor, port to PyTorch).
153-
154-
PySEF tutorials
155-
===============
156-
157-
The capabilities of PySEF are thoroughly demonstrated in two ipython tutorials that can be found in `tutorials <https://github.com/passalis/sef/blob/master/tutorials>`_.
158-
159169

0 commit comments

Comments
 (0)