diff --git a/doc/_static/img/index_api.svg b/doc/_static/img/index_api.svg deleted file mode 100644 index 69f7ba1..0000000 --- a/doc/_static/img/index_api.svg +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - diff --git a/doc/_static/img/index_examples.svg b/doc/_static/img/index_examples.svg deleted file mode 100644 index de3d902..0000000 --- a/doc/_static/img/index_examples.svg +++ /dev/null @@ -1,76 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - diff --git a/doc/_static/img/index_getting_started.svg b/doc/_static/img/index_getting_started.svg deleted file mode 100644 index 2d36622..0000000 --- a/doc/_static/img/index_getting_started.svg +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - diff --git a/doc/_static/img/index_user_guide.svg b/doc/_static/img/index_user_guide.svg deleted file mode 100644 index bd17053..0000000 --- a/doc/_static/img/index_user_guide.svg +++ /dev/null @@ -1,67 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - diff --git a/doc/api.rst b/doc/api.rst index 768ab5c..17e99f8 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -4,37 +4,18 @@ API Reference ############# -This is an example on how to document the API of your own project. +API reference for the `fsvm` package. .. currentmodule:: fsvm -Estimator +FuzzySVC ========= .. autosummary:: :toctree: generated/ :template: class.rst - TemplateEstimator - -Transformer -=========== - -.. autosummary:: - :toctree: generated/ - :template: class.rst - - TemplateTransformer - -Predictor -========= - -.. autosummary:: - :toctree: generated/ - :template: class.rst - - TemplateClassifier - + FuzzySVC Utilities ========= diff --git a/doc/conf.py b/doc/conf.py index dec5ab9..305872a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,9 +10,9 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information from importlib.metadata import version as get_version -project = "Scikit-learn Project Template" -copyright = "2016, V. Birodkar" -author = "V. Birodkar" +project = "fsvm" +copyright = "2024, J. Baliński" +author = "J. Baliński" release = get_version("fsvm") version = ".".join(release.split(".")[:3]) @@ -51,24 +51,22 @@ "css/fsvm.css", ] html_sidebars = { - "quick_start": [], - "user_guide": [], + "api": [], "auto_examples/index": [], } html_theme_options = { "external_links": [], "github_url": "https://github.com/balins/fsvm", - # "twitter_url": "https://twitter.com/pandas_dev", "use_edit_page_button": True, "show_toc_level": 1, # "navbar_align": "right", # For testing that the navbar items align properly } html_context = { - "github_user": "scikit-learn-contrib", - "github_repo": "project-template", - "github_version": "master", + "github_user": "balins", + "github_repo": "fsvm", + "github_version": "main", "doc_path": "doc", } diff --git a/doc/index.rst b/doc/index.rst index 2c66c59..3448501 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,4 +1,4 @@ -.. project-template documentation master file, created by +.. fsvm documentation master file, created by sphinx-quickstart on Mon Jan 18 14:44:12 2016. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -6,103 +6,22 @@ :notoc: ############################################# -Project template for `scikit-learn` extension +Fuzzy Support Vector Machine (FSVM) ############################################# -**Date**: |today| **Version**: |version| +**Date**: 31.08.2024 **Version**: 0.1.0 **Useful links**: -`Source Repository `__ | -`Issues & Ideas `__ | - -This is the documentation for the `project-template` to help at extending -`scikit-learn`. It provides some information on how to build your own custom -`scikit-learn` compatible estimators as well as a template to package them. - - -.. grid:: 1 2 2 2 - :gutter: 4 - :padding: 2 2 0 0 - :class-container: sd-text-center - - .. grid-item-card:: Getting started - :img-top: _static/img/index_getting_started.svg - :class-card: intro-card - :shadow: md - - Information regarding this template and how to modify it for your own project. - - +++ - - .. button-ref:: quick_start - :ref-type: ref - :click-parent: - :color: secondary - :expand: - - To the getting started guideline - - .. grid-item-card:: User guide - :img-top: _static/img/index_user_guide.svg - :class-card: intro-card - :shadow: md - - An example of narrative documentation. Here, we will explain how to create your - own `scikit-learn` estimator. - - +++ - - .. button-ref:: user_guide - :ref-type: ref - :click-parent: - :color: secondary - :expand: - - To the user guide - - .. grid-item-card:: API reference - :img-top: _static/img/index_api.svg - :class-card: intro-card - :shadow: md - - An example of API documentation. This is an example how to use `sphinx` to - automatically generate reference API page. - - +++ - - .. button-ref:: api - :ref-type: ref - :click-parent: - :color: secondary - :expand: - - To the reference guide - - .. grid-item-card:: Examples - :img-top: _static/img/index_examples.svg - :class-card: intro-card - :shadow: md - - A set of examples. It complements the User Guide and it is the right place to - show how to use your compatible estimator. - - +++ - - .. button-ref:: general_examples - :ref-type: ref - :click-parent: - :color: secondary - :expand: - - To the gallery of examples +`Source Repository `__ | +`Issues & Ideas `__ | +This is the documentation for the `fsvm`, a package providing a Fuzzy Support Vector Machine +implementation compatible with `scikit-learn`. .. toctree:: :maxdepth: 3 :hidden: :titlesonly: - quick_start - user_guide api auto_examples/index diff --git a/doc/quick_start.rst b/doc/quick_start.rst deleted file mode 100644 index b624f09..0000000 --- a/doc/quick_start.rst +++ /dev/null @@ -1,181 +0,0 @@ -.. _quick_start: - -############### -Getting started -############### - -This package serves as a skeleton package aiding at developing compatible -scikit-learn contribution. - -Creating your own scikit-learn contribution package -=================================================== - -Download and setup your repository ----------------------------------- - -To create your package, you need to clone the ``project-template`` repository: - -.. prompt:: bash $ - - git clone https://github.com/scikit-learn-contrib/project-template.git - -Before to reinitialize your git repository, you need to make the following -changes. Replace all occurrences of ``skltemplate``, ``sklearn-template``, or -``project-template`` with the name of you own project. You can find all the -occurrences using the following command: - -.. prompt:: bash $ - - git grep skltemplate - git grep sklearn-template - git grep project-template - -To remove the history of the template package, you need to remove the `.git` -directory: - -.. prompt:: bash $ - - rm -rf .git - -Then, you need to initialize your new git repository: - -.. prompt:: bash $ - - git init - git add . - git commit -m 'Initial commit' - -Finally, you create an online repository on GitHub and push your code online: - -.. prompt:: bash $ - - git remote add origin https://github.com/your_remote/your_contribution.git - git push origin main - -Develop your own scikit-learn estimators ----------------------------------------- - -.. _check_estimator: http://scikit-learn.org/stable/modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator -.. _`Contributor's Guide`: http://scikit-learn.org/stable/developers/ -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ -.. _PEP257: https://www.python.org/dev/peps/pep-0257/ -.. _NumPyDoc: https://github.com/numpy/numpydoc -.. _doctests: https://docs.python.org/3/library/doctest.html - -You can modify the source files as you want. However, your custom estimators -need to pass the check_estimator_ test to be scikit-learn compatible. We provide a -file called `test_common.py` where we run the checks on our custom estimators. - -You can refer to the :ref:`User Guide ` to help you create a compatible -scikit-learn estimator. - -In any case, developers should endeavor to adhere to scikit-learn's -`Contributor's Guide`_ which promotes the use of: - -* algorithm-specific unit tests, in addition to ``check_estimator``'s common - tests; -* PEP8_-compliant code; -* a clearly documented API using NumpyDoc_ and PEP257_-compliant docstrings; -* references to relevant scientific literature in standard citation formats; -* doctests_ to provide succinct usage examples; -* standalone examples to illustrate the usage, model visualisation, and - benefits/benchmarks of particular algorithms; -* efficient code when the need for optimization is supported by benchmarks. - -Managing your local and continuous integration environment ----------------------------------------------------------- - -Here, we set up for you an repository that uses `pixi`. The `pixi.toml` file defines -the packages and tasks to be run that we will present below. You can refer to the -following documentation link to install `pixi`: https://pixi.sh/latest/#installation - -Once done, you can refer to the documentation to get started but we provide the -command below to interact with the main task requested to develop your package. - -Edit the documentation ----------------------- - -.. _Sphinx: http://www.sphinx-doc.org/en/stable/ - -The documentation is created using Sphinx_. In addition, the examples are -created using ``sphinx-gallery``. Therefore, to generate locally the -documentation, you can leverage the following `pixi` task: - -.. prompt:: bash $ - - pixi run build-doc - -The documentation is made of: - -* a home page, ``doc/index.rst``; -* an API documentation, ``doc/api.rst`` in which you should add all public - objects for which the docstring should be exposed publicly. -* a User Guide documentation, ``doc/user_guide.rst``, containing the narrative - documentation of your package, to give as much intuition as possible to your - users. -* examples which are created in the `examples/` folder. Each example - illustrates some usage of the package. the example file name should start by - `plot_*.py`. - -Local testing -------------- - -To run the tests locally, you can use the following command: - -.. prompt:: bash $ - - pixi run test - -It will use `pytest` under the hood to run the package tests. - -In addition, you have a linter task to check the code consistency in terms of style: - -.. prompt:: bash $ - - pixi run lint - -Activating the development environment --------------------------------------- - -In the case that you don't want to use the `pixi run` commands and directly interact -with the usual python tools, you can activate the development environment: - -.. prompt:: bash $ - - pixi shell -e dev - -This will activate an environment containing the dependencies needed to run the linters, -tests, and build the documentation. So for instance, you can run the tests with: - -.. prompt:: bash $ - - pytest -vsl skltemplate - -In this case, you can even use pre-commit before using git. You will need to initialize -it with: - -.. prompt:: bash $ - - pre-commit install - -Setup the continuous integration --------------------------------- - -The project template already contains configuration files of the continuous -integration system. It leverage the above pixi commands and run on GitHub Actions. -In short, it will: - -* run the tests on the different platforms (Linux, MacOS, Windows) and upload the - coverage report to codecov.io; -* check the code style (linter); -* build the documentation and deploy it automatically on GitHub Pages. - -Publish your package -==================== - -.. _PyPi: https://packaging.python.org/tutorials/packaging-projects/ -.. _conda-forge: https://conda-forge.org/ - -You can make your package available through PyPi_ and conda-forge_. Refer to -the associated documentation to be able to upload your packages such that -it will be installable with ``pip`` and ``conda``. diff --git a/doc/user_guide.rst b/doc/user_guide.rst deleted file mode 100644 index 527d4c6..0000000 --- a/doc/user_guide.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. title:: User guide : contents - -.. _user_guide: - -========== -User Guide -========== - -Estimator ---------- - -The central piece of transformer, regressor, and classifier is -:class:`sklearn.base.BaseEstimator`. All estimators in scikit-learn are derived -from this class. In more details, this base class enables to set and get -parameters of the estimator. It can be imported as:: - - >>> from sklearn.base import BaseEstimator - -Once imported, you can create a class which inherate from this base class:: - - >>> class MyOwnEstimator(BaseEstimator): - ... pass - -Transformer ------------ - -Transformers are scikit-learn estimators which implement a ``transform`` method. -The use case is the following: - -* at ``fit``, some parameters can be learned from ``X`` and ``y``; -* at ``transform``, `X` will be transformed, using the parameters learned - during ``fit``. - -.. _mixin: https://en.wikipedia.org/wiki/Mixin - -In addition, scikit-learn provides a -mixin_, i.e. :class:`sklearn.base.TransformerMixin`, which -implement the combination of ``fit`` and ``transform`` called ``fit_transform``. - -One can import the mixin class as:: - - >>> from sklearn.base import TransformerMixin - -Therefore, when creating a transformer, you need to create a class which -inherits from both :class:`sklearn.base.BaseEstimator` and -:class:`sklearn.base.TransformerMixin`. The scikit-learn API imposed ``fit`` to -**return ``self``**. The reason is that it allows to pipeline ``fit`` and -``transform`` imposed by the :class:`sklearn.base.TransformerMixin`. The -``fit`` method is expected to have ``X`` and ``y`` as inputs. Note that -``transform`` takes only ``X`` as input and is expected to return the -transformed version of ``X``:: - - >>> class MyOwnTransformer(TransformerMixin, BaseEstimator): - ... def fit(self, X, y=None): - ... return self - ... def transform(self, X): - ... return X - -We build a basic example to show that our :class:`MyOwnTransformer` is working -within a scikit-learn ``pipeline``:: - - >>> from sklearn.datasets import load_iris - >>> from sklearn.pipeline import make_pipeline - >>> from sklearn.linear_model import LogisticRegression - >>> X, y = load_iris(return_X_y=True) - >>> pipe = make_pipeline(MyOwnTransformer(), - ... LogisticRegression(random_state=10, - ... solver='lbfgs')) - >>> pipe.fit(X, y) # doctest: +ELLIPSIS - Pipeline(...) - >>> pipe.predict(X) # doctest: +ELLIPSIS - array([...]) - -Predictor ---------- - -Regressor -~~~~~~~~~ - -Similarly, regressors are scikit-learn estimators which implement a ``predict`` -method. The use case is the following: - -* at ``fit``, some parameters can be learned from ``X`` and ``y``; -* at ``predict``, predictions will be computed using ``X`` using the parameters - learned during ``fit``. - -In addition, scikit-learn provides a mixin_, i.e. -:class:`sklearn.base.RegressorMixin`, which implements the ``score`` method -which computes the :math:`R^2` score of the predictions. - -One can import the mixin as:: - - >>> from sklearn.base import RegressorMixin - -Therefore, we create a regressor, :class:`MyOwnRegressor` which inherits from -both :class:`sklearn.base.BaseEstimator` and -:class:`sklearn.base.RegressorMixin`. The method ``fit`` gets ``X`` and ``y`` -as input and should return ``self``. It should implement the ``predict`` -function which should output the predictions of your regressor:: - - >>> import numpy as np - >>> class MyOwnRegressor(RegressorMixin, BaseEstimator): - ... def fit(self, X, y): - ... return self - ... def predict(self, X): - ... return np.mean(X, axis=1) - -We illustrate that this regressor is working within a scikit-learn pipeline:: - - >>> from sklearn.datasets import load_diabetes - >>> X, y = load_diabetes(return_X_y=True) - >>> pipe = make_pipeline(MyOwnTransformer(), MyOwnRegressor()) - >>> pipe.fit(X, y) # doctest: +ELLIPSIS - Pipeline(...) - >>> pipe.predict(X) # doctest: +ELLIPSIS - array([...]) - -Since we inherit from the :class:`sklearn.base.RegressorMixin`, we can call -the ``score`` method which will return the :math:`R^2` score:: - - >>> pipe.score(X, y) # doctest: +ELLIPSIS - -3.9... - -Classifier -~~~~~~~~~~ - -Similarly to regressors, classifiers implement ``predict``. In addition, they -output the probabilities of the prediction using the ``predict_proba`` method: - -* at ``fit``, some parameters can be learned from ``X`` and ``y``; -* at ``predict``, predictions will be computed using ``X`` using the parameters - learned during ``fit``. The output corresponds to the predicted class for each sample; -* ``predict_proba`` will give a 2D matrix where each column corresponds to the - class and each entry will be the probability of the associated class. - -In addition, scikit-learn provides a mixin, i.e. -:class:`sklearn.base.ClassifierMixin`, which implements the ``score`` method -which computes the accuracy score of the predictions. - -One can import this mixin as:: - - >>> from sklearn.base import ClassifierMixin - -Therefore, we create a classifier, :class:`MyOwnClassifier` which inherits -from both :class:`slearn.base.BaseEstimator` and -:class:`sklearn.base.ClassifierMixin`. The method ``fit`` gets ``X`` and ``y`` -as input and should return ``self``. It should implement the ``predict`` -function which should output the class inferred by the classifier. -``predict_proba`` will output some probabilities instead:: - - >>> class MyOwnClassifier(ClassifierMixin, BaseEstimator): - ... def fit(self, X, y): - ... self.classes_ = np.unique(y) - ... return self - ... def predict(self, X): - ... return np.random.randint(0, self.classes_.size, - ... size=X.shape[0]) - ... def predict_proba(self, X): - ... pred = np.random.rand(X.shape[0], self.classes_.size) - ... return pred / np.sum(pred, axis=1)[:, np.newaxis] - -We illustrate that this regressor is working within a scikit-learn pipeline:: - - >>> X, y = load_iris(return_X_y=True) - >>> pipe = make_pipeline(MyOwnTransformer(), MyOwnClassifier()) - >>> pipe.fit(X, y) # doctest: +ELLIPSIS - Pipeline(...) - -Then, you can call ``predict`` and ``predict_proba``:: - - >>> pipe.predict(X) # doctest: +ELLIPSIS - array([...]) - >>> pipe.predict_proba(X) # doctest: +ELLIPSIS - array([...]) - -Since our classifier inherits from :class:`sklearn.base.ClassifierMixin`, we -can compute the accuracy by calling the ``score`` method:: - - >>> pipe.score(X, y) # doctest: +ELLIPSIS - 0... diff --git a/examples/README.txt b/examples/README.txt index 6a1d992..298303c 100644 --- a/examples/README.txt +++ b/examples/README.txt @@ -3,4 +3,4 @@ Example Gallery =============== -Introductory examples. +Examples of FSVM usage. diff --git a/examples/plot_classifier.py b/examples/plot_classifier.py index ec88676..f0c31c1 100644 --- a/examples/plot_classifier.py +++ b/examples/plot_classifier.py @@ -1,6 +1,6 @@ """ ============================ -Plotting Template Classifier +Plotting FSVM Classifier ============================ An example plot of :class:`fsvm.FuzzySVC` diff --git a/fsvm/_fuzzy_svc.py b/fsvm/_fuzzy_svc.py index 0d59343..8d810d3 100644 --- a/fsvm/_fuzzy_svc.py +++ b/fsvm/_fuzzy_svc.py @@ -397,11 +397,14 @@ def fit(self, X, y): return self def predict(self, X): - """A reference implementation of a prediction for a classifier. + """ + A reference implementation of a prediction for a classifier. + Parameters ---------- X : array-like, shape (n_samples, n_features) The input samples. + Returns ------- y : ndarray, shape (n_samples,)