From 50bffef0d8a9bc4a9a8a3f12dbe40cf5cdce9f3c Mon Sep 17 00:00:00 2001 From: Marinka Zitnik Date: Wed, 16 Dec 2015 02:26:41 +0100 Subject: [PATCH] Update docs --- .gitignore | 39 ++++++ docs/source/code/usage6.py | 2 - docs/source/conf.py | 32 ++++- docs/source/index.rst | 120 ++++++------------ docs/source/nimfa.examples.all_aml.rst | 2 +- docs/source/nimfa.examples.cbcl_images.rst | 4 +- docs/source/nimfa.examples.documents.rst | 4 +- .../nimfa.examples.gene_func_prediction.rst | 4 +- .../source/nimfa.examples.medulloblastoma.rst | 4 +- docs/source/nimfa.examples.orl_images.rst | 4 +- .../source/nimfa.examples.recommendations.rst | 4 +- docs/source/nimfa.examples.synthetic.rst | 4 +- nimfa/examples/all_aml.py | 6 +- 13 files changed, 124 insertions(+), 105 deletions(-) create mode 100755 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100755 index 0000000..0e696d1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,39 @@ +# Ignore temporary editor files. +*.swp +*~ + +# Ignore project files +*.pyproj + +# Ignore dot files. +.* + +# Ignore backup files. +*.orig +*.bak + +# Ignore temporary editor files. +*.swp +*~ + +# Ignore binaries. +*.py[cod] +*.so +*.dll + +# Ignore built documentation +html + +# Ignore files created by setup.py. +build +dist +MANIFEST +*.egg-info +*.egg +distribute*.tar.gz + +# Ignore virtualenv folder +venv + +# Ignore datasets +nimfa/datasets/* diff --git a/docs/source/code/usage6.py b/docs/source/code/usage6.py index 85ecb08..6820dc9 100644 --- a/docs/source/code/usage6.py +++ b/docs/source/code/usage6.py @@ -2,7 +2,6 @@ import nimfa - V = np.random.rand(30, 20) init_W = np.random.rand(30, 4) @@ -13,6 +12,5 @@ nmf_fit = nmf() print("Euclidean distance: %5.3f" % nmf_fit.distance(metric="euclidean")) - print('Initialization type: %s' % nmf_fit.seeding) print('Iterations: %d' % nmf_fit.n_iter) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8701589..6a1ff8b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,7 +1,6 @@ # -*- coding: utf-8 -*- # # nimfa - A Python Library for Nonnegative Matrix Factorization Techniques documentation build configuration file, created by -# sphinx-quickstart on Tue Aug 23 13:23:27 2011. # # This file is execfile()d with the current directory set to its containing dir. # @@ -12,6 +11,7 @@ # serve to show the default. import sys, os +import alabaster # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -25,7 +25,9 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.ifconfig'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.ifconfig', + 'alabaster'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -40,8 +42,8 @@ master_doc = 'index' # General information about the project. -project = 'nimfa - A Python Library for Nonnegative Matrix Factorization Techniques' -copyright = '2011, Marinka Zitnik' +project = 'Nimfa' +copyright = '2015, Marinka Zitnik' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -89,14 +91,32 @@ # -- Options for HTML output --------------------------------------------------- +html_theme_path = [alabaster.get_path()] +html_theme = 'alabaster' +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' +# html_theme = 'nature' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'github_user': 'marinkaz', + 'github_repo': 'nimfa', + 'github_button': True, + 'github_banner': True, + 'sidebar_width': '250px', +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] diff --git a/docs/source/index.rst b/docs/source/index.rst index 2148859..94cd12f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,21 +1,15 @@ -.. nimfa - A Python Library for Nonnegative Matrix Factorization Techniques documentation master file, created by - sphinx-quickstart on Tue Aug 23 13:23:27 2011. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -nimfa - A Python Library for Nonnegative Matrix Factorization Techniques -================================================================================ +Welcome to Nimfa +================ -**Nimfa** is an open-source Python library that provides a unified interface to nonnegative matrix factorization algorithms. -It includes implementations of state-of-the-art factorization methods, initialization approaches, and quality scoring. +Nimfa is a Python library for nonnegative matrix factorization. It includes implementations of several factorization methods, initialization approaches, and quality scoring. Both dense and sparse matrix representation are supported. The sample script using Nimfa on medulloblastoma gene expression data is given below. It uses alternating least squares nonnegative matrix factorization with projected gradient method for subproblems [Lin2007]_ and Random Vcol [Albright2006]_ initialization algorithm. An object returned by ``nimfa.mf_run`` is fitted factorization model through which user can access matrix factors and estimate quality measures. - .. literalinclude:: /code/usage.py +.. literalinclude:: /code/usage.py Running this script produces the following output, where slight differences in reported scores across different runs can be attributed to randomness of the Random Vcol initialization method:: @@ -25,20 +19,17 @@ runs can be attributed to randomness of the Random Vcol initialization method:: K-L divergence: 38.8744 Sparseness, W: 0.7297, H: 0.8796 -Further real-world examples and demonstrations of library capabilities are provided in the `Examples section`_ and in `sample scripts on this page`_. +.... + +See also `Examples`_, `sample scripts on this page`_ and `a short presentation about nimfa.`_ -.. note:: See also a `short presentation about nimfa.`_ - - .. _A Python Library for Nonnegative Matrix Factorization, Journal of Machine Learning Research: http://jmlr.csail.mit.edu/papers/v13/zitnik12a.html -.. _Examples section: nimfa.examples.html +.. _Examples: nimfa.examples.html .. _sample scripts on this page: http://nimfa.biolab.si/#usage -.. _Orange: http://orange.biolab.si - -.. _short presentation about nimfa.: http://helikoid.si/mf/GSoC_MF.pdf +.. _a short presentation about nimfa.: http://helikoid.si/mf/GSoC_MF.pdf ################### Scripting Reference @@ -77,9 +68,9 @@ Initialization Methods .. include:: /content-initialization.rst -******************************** +**************** Quality Measures -******************************** +**************** .. include:: /content-quality-performance.rst @@ -95,45 +86,28 @@ Utils Installation ############ -****** -Source -****** +Nimfa is compatible with Python 2 and Python 3 versions. +The recommended way to install Nimfa is by issuing:: -No special installation procedure is specified. However, the nimfa library makes extensive use of `SciPy`_ and `NumPy`_ + pip install nimfa + +from the command line. + +Nimfa makes extensive use of `SciPy`_ and `NumPy`_ libraries for fast and convenient dense and sparse matrix manipulation and some linear -algebra operations. There are not any additional prerequisites. Nimfa is compatible with Python 2 and Python 3 versions. +algebra operations. There are not any additional prerequisites. .. _SciPy: http://www.scipy.org/ .. _NumPy: http://numpy.scipy.org/ -Download source code (zipped archive) from `Github repository`_. +Alternatively, you can download source code from `Github`_. -.. _Github repository: http://github.com/marinkaz/mf +.. _Github: http://github.com/marinkaz/mf Unzip the archive. To build and install run:: python setup.py install -************* -Documentation -************* - -For building the documentation use Sphinx 1.0 or newer. Sphinx is available at `Sphinx home page`_ and -nimfa library documentation sources are available at `Github repository`_. Before building documentation, -please install the nimfa library. - -Documentation can be built by issuing:: - - sphinx-build -b html -E - -from the nimfa root directory. After completion, the documentation should reside in the `html` directory. The built documentation -should resemble closely the one you are currently reading. - -.. note:: The nimfa library documentation is contained in ``docs`` source directory and and scripts are in ``nimfa`` directory. - -.. _Sphinx home page: http://sphinx.pocoo.org - - ############# @@ -153,39 +127,36 @@ For details and descriptions on algorithm specific options see specific algorith Usage ##### -Following are basic usage examples that employ different implemented factorization algorithms. For examples with real world -applications see Examples section and methods' documentation. - -.. note:: Consider these examples as Hello World examples for the nimfa library. +Following are basic usage examples that employ different implemented factorization algorithms. Standard NMF - Divergence on ``scipy.sparse`` matrix with matrix factors estimation. - .. literalinclude:: /code/usage1.py +.. literalinclude:: /code/usage1.py LSNMF on ``numpy`` dense matrix with quality and performance measures. - .. literalinclude:: /code/usage2.py +.. literalinclude:: /code/usage2.py LSNMF with Random VCol initialization and error tracking. - .. literalinclude:: /code/usage3.py +.. literalinclude:: /code/usage3.py ICM with Random C initialization and passed callback initialization function. - .. literalinclude:: /code/usage4.py +.. literalinclude:: /code/usage4.py BMF with default parameters, multiple runs and factor tracking for consensus matrix computation. - .. literalinclude:: /code/usage5.py +.. literalinclude:: /code/usage5.py Standard NMF - Euclidean update equations and fixed initialization (passed matrix factors). - .. literalinclude:: /code/usag6.py +.. literalinclude:: /code/usage6.py ########## @@ -250,33 +221,25 @@ Acknowledgements We would like to acknowledge support for this project from the Google Summer of Code 2011 program and from the Slovenian Research Agency grants P2-0209, J2-9699, and L2-1112. -The nimfa - A Python Library for Nonnegative Matrix Factorization Techniques was part of the Google Summer of Code 2011 (`Orange`_). It is authored by `Marinka Zitnik`_, advised by `Blaz Zupan, Ph.D.`_. +The nimfa - A Python Library for Nonnegative Matrix Factorization Techniques was part of the Google Summer of Code 2011. It is authored by `Marinka Zitnik`_ and `Blaz Zupan`_. -.. _Blaz Zupan, Ph.D.: http://www.biolab.si/en/blaz/ +.. _Blaz Zupan: http://www.biolab.si/en/blaz/ .. _Marinka Zitnik: http://helikoid.si -.. image:: /images/base/orange-logo.png - :target: http://orange.biolab.si - - -.. image:: /images/base/google-logo.png - :target: http://code.google.com/soc/ - :scale: 50 % - ######## Citation ######## - .. code-block:: none - - @article{ZitnikZ12, - author = {Marinka Zitnik and Blaz Zupan}, - title = {NIMFA: A Python Library for Nonnegative Matrix Factorization}, - journal = {Journal of Machine Learning Research}, - volume = {13}, - year = {2012}, - pages = {849-853}, - } +.. code-block:: none + + @article{ZitnikZ12, + author = {Marinka Zitnik and Blaz Zupan}, + title = {NIMFA: A Python Library for Nonnegative Matrix Factorization}, + journal = {Journal of Machine Learning Research}, + volume = {13}, + year = {2012}, + pages = {849-853}, + } ########## @@ -292,7 +255,7 @@ License ####### nimfa - A Python Library for Nonnegative Matrix Factorization Techniques -Copyright (C) 2011-2015 Marinka Zitnik and Blaz Zupan +Copyright (C) 2011-2015 Marinka Zitnik and Blaz Zupan. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -312,4 +275,3 @@ Index and Search * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/source/nimfa.examples.all_aml.rst b/docs/source/nimfa.examples.all_aml.rst index 59f6466..2a90f09 100644 --- a/docs/source/nimfa.examples.all_aml.rst +++ b/docs/source/nimfa.examples.all_aml.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/all_aml.py +.. comment literalinclude:: ../../nimfa/examples/all_aml.py :lines: 106-209 :linenos: diff --git a/docs/source/nimfa.examples.cbcl_images.rst b/docs/source/nimfa.examples.cbcl_images.rst index f07bc9f..070391a 100644 --- a/docs/source/nimfa.examples.cbcl_images.rst +++ b/docs/source/nimfa.examples.cbcl_images.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/cbcl_images.py +.. comment literalinclude:: ../../nimfa/examples/cbcl_images.py :lines: 82-198 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.documents.rst b/docs/source/nimfa.examples.documents.rst index 439e1b7..eff3f63 100644 --- a/docs/source/nimfa.examples.documents.rst +++ b/docs/source/nimfa.examples.documents.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/documents.py +.. comment literalinclude:: ../../nimfa/examples/documents.py :lines: 99-262 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.gene_func_prediction.rst b/docs/source/nimfa.examples.gene_func_prediction.rst index cd251ca..aa2d095 100644 --- a/docs/source/nimfa.examples.gene_func_prediction.rst +++ b/docs/source/nimfa.examples.gene_func_prediction.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/gene_func_prediction.py +.. comment literalinclude:: ../../nimfa/examples/gene_func_prediction.py :lines: 57-461 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.medulloblastoma.rst b/docs/source/nimfa.examples.medulloblastoma.rst index f42e374..442421e 100644 --- a/docs/source/nimfa.examples.medulloblastoma.rst +++ b/docs/source/nimfa.examples.medulloblastoma.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/medulloblastoma.py +.. comment literalinclude:: ../../nimfa/examples/medulloblastoma.py :lines: 96-199 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.orl_images.rst b/docs/source/nimfa.examples.orl_images.rst index c86a89d..ed26014 100644 --- a/docs/source/nimfa.examples.orl_images.rst +++ b/docs/source/nimfa.examples.orl_images.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/orl_images.py +.. comment literalinclude:: ../../nimfa/examples/orl_images.py :lines: 93-209 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.recommendations.rst b/docs/source/nimfa.examples.recommendations.rst index 06978a4..c695a41 100644 --- a/docs/source/nimfa.examples.recommendations.rst +++ b/docs/source/nimfa.examples.recommendations.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/recommendations.py +.. comment literalinclude:: ../../nimfa/examples/recommendations.py :lines: 43-173 - :linenos: \ No newline at end of file + :linenos: diff --git a/docs/source/nimfa.examples.synthetic.rst b/docs/source/nimfa.examples.synthetic.rst index e659d43..d52eaa9 100644 --- a/docs/source/nimfa.examples.synthetic.rst +++ b/docs/source/nimfa.examples.synthetic.rst @@ -4,6 +4,6 @@ :inherited-members: :show-inheritance: -.. literalinclude:: ../../nimfa/examples/synthetic.py +.. comment literalinclude:: ../../nimfa/examples/synthetic.py :lines: 35-378 - :linenos: \ No newline at end of file + :linenos: diff --git a/nimfa/examples/all_aml.py b/nimfa/examples/all_aml.py index 30d0b3c..e16a7f4 100644 --- a/nimfa/examples/all_aml.py +++ b/nimfa/examples/all_aml.py @@ -1,8 +1,8 @@ """ - ################################################# - ALL AML Leukemia Data Sets (``examples.aml_all``) - ################################################# + ####################################### + ALL AML Leukemia (``examples.aml_all``) + ####################################### This module demonstrates the ability of NMF to recover meaningful biological information from cancer related microarray data. NMF appears to have advantages over other methods such as HC or SOM.