From 1be8420e868aa898da512aead3160d48867b07ed Mon Sep 17 00:00:00 2001 From: Gertjan van den Burg Date: Wed, 13 Dec 2017 14:36:16 -0500 Subject: various documentation updates --- .gitignore | 3 +++ CHANGELOG.rst | 2 +- Makefile | 3 ++- README.rst | 39 ++++++++++++++++++++++++++------------- docs/cls_gensvm.rst | 2 +- docs/conf.py | 2 +- docs/index.rst | 7 ++++--- 7 files changed, 38 insertions(+), 20 deletions(-) diff --git a/.gitignore b/.gitignore index e691660..dde7e83 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ *.pyc gensvm/*.so +README +build/* +cover/* diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 9a203e1..ae918c0 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,2 +1,2 @@ Change Log -========== +---------- diff --git a/Makefile b/Makefile index c330cd5..353cddc 100644 --- a/Makefile +++ b/Makefile @@ -31,7 +31,8 @@ install2: ## Install for the current user using the python2 command test: in ## Run nosetests using the default nosetests command nosetests -v -test2: develop2 ## Run nosetests using the nosetests2 command +test2: ## Run nosetests using the nosetests2 command + python2 setup.py build_ext -i nosetests2 -v cover: test ## Test unit test coverage using default nosetests diff --git a/README.rst b/README.rst index 0182103..5e68024 100644 --- a/README.rst +++ b/README.rst @@ -14,6 +14,11 @@ The source code of this package is available on GitHub at: Installation ------------ +**Before** GenSVM can be installed, a working NumPy installation is required. +Please see `the installation instructions for NumPy +`_, then install +GenSVM using the instructions below. + GenSVM can be easily installed through pip: .. code:: bash @@ -23,15 +28,15 @@ GenSVM can be easily installed through pip: Usage ----- -The package contains two classes to fit the GenSVM model: :class:`GenSVM` and -:class:`GenSVMGridSearchCV`. These classes respectively fit a single GenSVM -model or fit a series of models for a parameter grid search. The interface to -these classes is the same as that of classifiers in `Scikit-Learn `_ so users -familiar with `Scikit-Learn `_ should have no trouble using this package. Below +The package contains two classes to fit the GenSVM model: `GenSVM`_ and +`GenSVMGridSearchCV`_. These classes respectively fit a single GenSVM model +or fit a series of models for a parameter grid search. The interface to these +classes is the same as that of classifiers in `Scikit-Learn`_ so users +familiar with Scikit-Learn should have no trouble using this package. Below we will show some examples of using the GenSVM classifier and the GenSVMGridSearchCV class in practice. -In the examples We assume that we have loaded the `iris dataset +In the examples we assume that we have loaded the `iris dataset `_ from Scikit-Learn as follows: @@ -53,7 +58,7 @@ computation time of GenSVM and is `generally recommended for SVMs Example 1: Fitting a single GenSVM model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Let's start by fitting the most basic GenSVM model on the training data: @@ -121,7 +126,7 @@ For other parameters that can be tuned in the GenSVM model, see `GenSVM`_. Example 2: Fitting a GenSVM model with a "warm start" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One of the key features of the GenSVM classifier is that training can be accelerated by using so-called "warm-starts". This way the optimization can be @@ -170,7 +175,7 @@ can be used to do a grid search of parameters. Example 3: Running a GenSVM grid search -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Often when we're fitting a machine learning model such as GenSVM, we have to try several parameter configurations to figure out which one performs best on @@ -180,8 +185,7 @@ overfitting. To do this efficiently and to make use of warm starts, the `GenSVMGridSearchCV`_ class is available. This class works in the same way as the `GridSearchCV `_ -class of `Scikit-Learn `_, but uses -the GenSVM C library for speed. +class of `Scikit-Learn`_, but uses the GenSVM C library for speed. To do a grid search, we first have to define the parameters that we want to vary and what values we want to try: @@ -216,8 +220,8 @@ found in the grid search: >>> gg.score(X_test, y_test) 1.0 -A nice feature borrowed from `Scikit-Learn `_ is that -the results from the grid search can be represented as a ``pandas`` DataFrame: +A nice feature borrowed from `Scikit-Learn`_ is that the results from the grid +search can be represented as a ``pandas`` DataFrame: .. code:: python @@ -262,6 +266,15 @@ License ------- This package is licensed under the GNU General Public License version 3. + Copyright G.J.J. van den Burg, excluding the sections of the code that are explicitly marked to come from Scikit-Learn. +.. _Scikit-Learn: + http://scikit-learn.org/stable/index.html + +.. _GenSVM: + https://gensvm.readthedocs.io/en/latest/#gensvm + +.. _GenSVMGridSearchCV: + https://gensvm.readthedocs.io/en/latest/#gensvmgridsearchcv diff --git a/docs/cls_gensvm.rst b/docs/cls_gensvm.rst index 082df8f..4e67631 100644 --- a/docs/cls_gensvm.rst +++ b/docs/cls_gensvm.rst @@ -10,7 +10,7 @@ errors. It is this flexibility that makes it perform well on diverse datasets. - The :func:`.~GenSVM.fit` and :func:`~GenSVM.predict` methods of this class + The :func:`~GenSVM.fit` and :func:`~GenSVM.predict` methods of this class use the GenSVM C library for the actual computations. :param p: Parameter for the L_p norm of the loss function (1.0 <= p <= 2.0) diff --git a/docs/conf.py b/docs/conf.py index 8a02df3..e3eb6b9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -136,7 +136,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = {'collapse_navigation': True} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/index.rst b/docs/index.rst index 7f539b8..7a28f0e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,19 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. toctree:: .. include:: ../README.rst Classes -======= +------- GenSVM ------- +^^^^^^ .. include:: ./cls_gensvm.rst GenSVMGridSearchCV ------------------- +^^^^^^^^^^^^^^^^^^ .. include:: ./cls_gridsearch.rst -- cgit v1.2.3