Merge branch 'feature/pip'

Author: tiskw

.gitignore

@@ -3,5 +3,9 @@
 *.npz
 *.swp
 *.pickle
-.notifier
+
+# Ignore python cache.
 __pycache__
+
+# Ignore virtual environment.
+venv

Makefile

@@ -0,0 +1,108 @@
+################################################################################
+# Makefile
+################################################################################
+
+.PHONY: build testpypi pypi install-test check count coverage clean help
+
+#-------------------------------------------------------------------------------
+# Define package names and target source files
+#-------------------------------------------------------------------------------
+
+SOFTWARE = rfflearn
+PY_FILES = $(shell find rfflearn | grep \.py$$ | sort)
+
+help:
+	@echo "Usage:"
+	@echo "    make <command>"
+	@echo ""
+	@echo "Build commands:"
+	@echo "    build         Build package"
+	@echo "    testpypi      Upload package to TestPyPi"
+	@echo "    pypi          Upload package to PyPi"
+	@echo "    install-test  Install from TestPyPi"
+	@echo ""
+	@echo "Test and code check commands:"
+	@echo "    check         Check the code quality"
+	@echo "    count         Count the lines of code"
+	@echo "    coverage      Measure code coverage"
+	@echo ""
+	@echo "Other commands:"
+	@echo "    clean         Cleanup cache files"
+	@echo "    help          Show this message"
+
+#-------------------------------------------------------------------------------
+# Build commands
+#-------------------------------------------------------------------------------
+
+build:             
+	python3 -m build
+
+testpypi:          
+	twine upload --repository pypitest dist/*
+
+pypi:
+	twine upload --repository pypi dist/*
+
+install-test:
+	python3 -m pip install --index-url https://test.pypi.org/simple/ $(SOFTWARE)
+
+#-------------------------------------------------------------------------------
+# Test commands
+#-------------------------------------------------------------------------------
+
+check:
+	pyflakes $(PY_FILES)
+	pylint $(PY_FILES) --disable C0103,R0913,R0917,R0801
+
+count:
+	cloc --by-file $(PY_FILES)
+
+coverage:
+	rm -rf .coverage
+	coverage erase
+	@echo "Run tests on CPU..."
+	coverage run --source rfflearn -a tests/cca_for_artificial_data.py
+	coverage run --source rfflearn -a tests/feature_importances_for_california_housing.py
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py cpu --rtype rff
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py cpu --rtype orf
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py cpu --rtype qrf
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py cpu --rtype rff
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py cpu --rtype orf
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py cpu --rtype qrf
+	coverage run --source rfflearn -a tests/least_square_regression.py --rtype rff
+	coverage run --source rfflearn -a tests/least_square_regression.py --rtype orf
+	coverage run --source rfflearn -a tests/least_square_regression.py --rtype qrf
+	coverage run --source rfflearn -a tests/optuna_for_california_housing.py
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py cpu --rtype rff
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py cpu --rtype orf
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py cpu --rtype qrf
+	coverage run --source rfflearn -a tests/svc_for_mnist.py cpu --rtype rff --skip_tune
+	coverage run --source rfflearn -a tests/svc_for_mnist.py cpu --rtype orf --skip_tune
+	coverage run --source rfflearn -a tests/svc_for_mnist.py cpu --rtype qrf --skip_tune
+	coverage run --source rfflearn -a tests/svr_sparse_data.py cpu --rtype rff
+	coverage run --source rfflearn -a tests/svr_sparse_data.py cpu --rtype orf
+	coverage run --source rfflearn -a tests/svr_sparse_data.py cpu --rtype qrf
+	@echo "Run tests on GPU..."
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py gpu --rtype rff
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py gpu --rtype orf
+	coverage run --source rfflearn -a tests/gpc_for_mnist.py gpu --rtype qrf
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py gpu --rtype rff
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py gpu --rtype orf
+	coverage run --source rfflearn -a tests/gpr_sparse_data.py gpu --rtype qrf
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py gpu --rtype rff
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py gpu --rtype orf
+	coverage run --source rfflearn -a tests/pca_for_swissroll.py gpu --rtype qrf
+	coverage run --source rfflearn -a tests/svc_for_mnist.py gpu --rtype rff --skip_tune
+	coverage run --source rfflearn -a tests/svc_for_mnist.py gpu --rtype orf --skip_tune
+	coverage run --source rfflearn -a tests/svc_for_mnist.py gpu --rtype qrf --skip_tune
+	coverage run --source rfflearn -a tests/svc_train_cpu_predict_gpu.py
+	coverage html
+
+#-------------------------------------------------------------------------------
+# Other commands
+#-------------------------------------------------------------------------------
+
+clean:
+	rm -rf dist .coverage htmlcov scikit_learn_data `find -type d | grep __pycache__`
+
+# vim: noexpandtab tabstop=4 shiftwidth=4

README.md

@@ -1,10 +1,21 @@
-Random Fourier Features
-====================================================================================================
-
 <div align="center">
   <img src="./figures/logo_long.svg" width="480" alt="rfflearn logo" />
 </div>
 
+<div align="center">
+  <img src="https://img.shields.io/badge/PYTHON-%3E%3D3.9-blue.svg?logo=python&logoColor=white">
+  &nbsp;
+  <img src="https://img.shields.io/badge/LICENSE-MIT-orange.svg">
+  &nbsp;
+  <img src="https://img.shields.io/badge/COVERAGE-97%25-green.svg">
+  &nbsp;
+  <img src="https://img.shields.io/badge/QUALITY-9.96/10.0-yellow.svg">
+</div>
+
+
+Random Fourier Features
+====================================================================================================
+
 This repository provides the Python module `rfflearn` which is a Python library of random Fourier
 features (hereinafter abbreviated as RFF) [1, 2] for kernel methods, like support vector
 machine [3, 4] and Gaussian process model [5]. Features of this module are:
@@ -36,6 +47,34 @@ The author will provide implementations of the other algorithms soon.
 
 **NOTE**: The author confirmed that the `rfflearn` module works on PyTorch 2.0! :tada:
 
+
+Installation
+----------------------------------------------------------------------------------------------------
+
+Please install from PyPI.
+
+```shell
+pip install rfflearn
+```
+
+If you need GPU support, Optuna support or SHAP support,
+you need to install the following packages.
+
+```shell
+# For GPU support.
+pip install torch
+
+# For Optuna support.
+pip install optuna
+
+# For SHAP support.
+pip install matplotlib shap
+```
+
+The author recommends using [venv](https://docs.python.org/3/library/venv.html) or
+[Docker](https://www.docker.com/) to avoid polluting your environment.
+
+
 Minimal example
 ----------------------------------------------------------------------------------------------------
 
@@ -109,24 +148,55 @@ the California housing dataset, and the followings are the visualization results
 `rfflearn.shap_feature_importance` and `rfflearn.permutation_feature_importance`.
 
 <div align="center">
-  <img src="./examples/feature_importances_for_california_housing/figure_california_housing_shap_importance.png" width="400" alt="Permutation importances of Boston housing dataset" />
-  <img src="./examples/feature_importances_for_california_housing/figure_california_housing_permutation_importance.png" width="400" alt="SHAP importances of Boston housing dataset" />
+  <img src="./examples/feature_importances_for_california_housing/figures/figure_california_housing_shap_importance.png" width="450" alt="Permutation importances of Boston housing dataset" />
+  <img src="./examples/feature_importances_for_california_housing/figures/figure_california_housing_permutation_importance.png" width="450" alt="SHAP importances of Boston housing dataset" />
 </div>
 
 
-Requirements and installation
+Quick Tutorial
 ----------------------------------------------------------------------------------------------------
 
-The author recommends using a docker image for building the environment for the `rfflearn`,
-however, of course, you can install the necessary packages on your environment directly.
-See [SETUP.md](./SETUP.md) for more details.
+At first, please clone the `random-fourier-features` repository from GitHub:
+
+```console
+git clone https://github.com/tiskw/random-fourier-features.git
+cd random-fourier-features
+```
+
+If you are using the docker image, enter into the docker container by the following command
+(not necessary to run thw following if you don't use docker):
+
+```console
+docker run --rm -it --gpus all -v `pwd`:/work -w /work -u `id -u`:`id -g` tiskw/pytorch:latest bash
+```
+
+Then, launch python3 and try the following minimal code that runs support vector classification
+with random Fourier features on an artificial tiny dataset.
+
+```python
+>>> import numpy as np                                  # Import Numpy
+>>> import rfflearn.cpu as rfflearn                     # Import our module
+>>> X = np.array([[-1, -1], [-2, -1], [1, 1], [2, 1]])  # Define input data
+>>> y = np.array([1, 1, 2, 2])                          # Defile label data
+>>> svc = rfflearn.RFFSVC().fit(X, y)                   # Training
+>>> svc.score(X, y)                                     # Inference (on CPU)
+1.0
+>>> svc.predict(np.array([[-0.8, -1]]))
+array([1])
+```
+
+### Next Step
+
+Now you succeeded in installing the `rfflearn` module.
+The author's recommendation for the next step is to see the [examples directory](/examples)
+and try a code you are interested in.
 
 
 Notes
 ----------------------------------------------------------------------------------------------------
 
-- The name of this module is changed from `pyrff` to `rfflearn` on Oct 2020, because the package name
-  `pyrff` already exists in PyPI.
+- The name of this module is changed from `pyrff` to `rfflearn` on Oct 2020, because the package
+  name `pyrff` already exists in PyPI.
 - If the number of training data is huge, an error message like `RuntimeError: The task could not be
   sent to the workers as it is too large for 'send_bytes'` will be raised from the joblib library.
   The reason for this error is that the `sklearn.svm.LinearSVC` uses `joblib` as a multiprocessing
@@ -142,7 +212,8 @@ Notes
 License
 ----------------------------------------------------------------------------------------------------
 
-[MIT Licence](https://opensource.org/licenses/mit-license.php)
+This software is distributed under the [MIT Licence](https://opensource.org/licenses/mit-license.php).
+See [LICENSE](./LICENSE) for more information.
 
 
 Reference