Commit 915c110e authored by Manuel Günther's avatar Manuel Günther
Browse files

Started documenting bob.bio.gmm

parent 21783cb5
from . import algorithm
from . import tools
from . import test
def get_config():
"""Returns a string containing the configuration information.
"""
......
......@@ -2,3 +2,6 @@ from .GMM import GMM, GMMRegular
from .JFA import JFA
from .ISV import ISV
from .IVector import IVector
# gets sphinx autodoc done right - don't remove it
__all__ = [_ for _ in dir() if not _.startswith('_')]
......@@ -3,3 +3,6 @@ from .command_line import *
from .gmm import *
from .isv import *
from .ivector import *
# gets sphinx autodoc done right - don't remove it
__all__ = [_ for _ in dir() if not _.startswith('_')]
......@@ -179,33 +179,3 @@ def train_whitener(algorithm, force=False):
algorithm.load_whitener(fs.whitener_file)
logger.info("Writing projector into file %s", fs.projector_file)
algorithm.save_projector(fs.projector_file)
"""
def whitening_ivector(self, indices=None, force=False):
""Performs IVector projection""
# read UBM into the IVector class
projector = self.m_tool.load_whitening(self.m_configuration.whitening_file)
projected_ivec_files = self.projected_list(groups=self.groups(), directory=self.m_configuration.ivec_directory)
projected_whitened_files = self.projected_list(groups=self.groups(), directory=self.m_configuration.whitening_directory)
# select a subset of indices to iterate
if indices != None:
index_range = range(indices[0], indices[1])
facereclib.utils.info("- Projection: splitting of index range %s" % str(indices))
else:
index_range = range(len(projected_ivec_files))
facereclib.utils.info("- Projection: projecting %d gmm stats from directory '%s' to directory '%s'" % (len(index_range), self.m_configuration.ivec_directory, self.m_configuration.whitening_directory))
# extract the features
for i in index_range:
if not self.m_tool_chain.__check_file__(projected_whitened_files[i], force):
# load feature
feature = facereclib.utils.load(str(projected_ivec_files[i]))
# project feature
whitened = self.m_tool.project_whitening(feature)
# write it
facereclib.utils.ensure_dir(os.path.dirname(projected_whitened_files[i]))
facereclib.utils.save(whitened, str(projected_whitened_files[i]))
"""
......@@ -86,7 +86,7 @@ release = distribution.version
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
#exclude_patterns = ['**/links.rst']
exclude_patterns = ['links.rst', 'references.rst']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
......@@ -133,12 +133,12 @@ if sphinx.__version__ >= "1.0":
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = ''
html_logo = 'img/logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = ''
html_favicon = 'img/favicon.ico'
# 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,
......@@ -187,7 +187,7 @@ html_favicon = ''
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'bob_example_project_doc'
htmlhelp_basename = 'bob_bio_gmm_doc'
# -- Options for LaTeX output --------------------------------------------------
......@@ -201,7 +201,7 @@ latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'bob_example_project.tex', u'Bob',
('index', 'bob_bio_gmm.tex', u'Bob',
u'Biometrics Group, Idiap Research Institute', 'manual'),
]
......@@ -236,7 +236,7 @@ rst_epilog = ''
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'bob.example.project', u'Bob Example Project Documentation', [u'Idiap Research Institute'], 1)
('index', 'bob.bio.gmm', u'Gaussian Mixture Models in bob.bio Documentation', [u'Idiap Research Institute'], 1)
]
# Default processing flags for sphinx
......@@ -246,8 +246,14 @@ autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-
# For inter-documentation mapping:
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.io.gmm', 'bob.db.verification.utils'])
intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.io.gmm'])
def skip(app, what, name, obj, skip, options):
# Do not skip the __call__ and the __str__ functions as we have special implementations for them.
if name in ("__call__"):
return False
return skip
def setup(app):
pass
app.connect("autodoc-skip-member", skip)
======================
Implementation Details
======================
.. todo::
Document the details of the GMM-based algorithms.
.. include:: links.rst
.. _bob.bio.gmm.implemented:
================================
Tools implemented in bob.bio.gmm
================================
Summary
-------
.. autosummary::
bob.bio.gmm.algorithm.GMM
bob.bio.gmm.algorithm.ISV
bob.bio.gmm.algorithm.JFA
bob.bio.gmm.algorithm.IVector
Details
-------
.. automodule:: bob.bio.gmm.algorithm
......@@ -4,17 +4,57 @@
.. _bob.bio.gmm:
====================================================
Biometric Recognition with Gaussian Mixture Models
====================================================
=========================================
Gaussian Mixture Model based Algorithms
=========================================
This package is part of the ``bob.bio`` packages, which provide open source tools to run comparable and reproducible biometric recognition experiments.
In this package, algorithms for executing experiments based on Gaussian Mixture Models are provided, including scripts to run the training procedures of the Expectation-Maximization loops in parallel.
Package Documentation
---------------------
For more detailed information about the structure of the ``bob.bio`` packages, please refer to the documentation of :ref:`bob.bio.base <bob.bio.base>`.
Particularly, the installation of this and other ``bob.bio`` packages, please read the :ref:`bob.bio.base.installation`.
.. automodule:: bob.bio.gmm
In the following, we provide more detailed information about the particularities of this package only.
Databases
---------
===========
Users Guide
===========
.. automodule:: bob.bio.gmm.database
.. toctree::
:maxdepth: 2
implementation
parallel
================
Reference Manual
================
.. toctree::
:maxdepth: 2
implemented
py_api
.. include:: references.rst
=========
ToDo-List
=========
This documentation is still under development.
Here is a list of things that needs to be done:
.. todolist::
==================
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. include:: links.rst
==================================
Executing the Training in Parallel
==================================
Sometimes the training of the GMM-based models require a lot of time.
However, the training procedures can be parallelized, i.e., by running the E-steps of the EM loop in parallel.
For this purpose, we provide a set of scripts ``./bin/verify_gmm.py``, ``./bin/verify_isv.py`` and ``./bin/verify_ivector.py``.
These scripts integrate perfectly into the ``bob.bio`` packages.
Particularly, they have exactly the same set of options as documented in :ref:`bob.bio.base.experiments`.
In fact, the scripts above only run in parallelized mode, i.e., the ``--grid`` option is required.
During the submission of the jobs, several hundred jobs might be created (depending on the ``number_of_..._training_iterations`` that you specify in the :py:class:`bob.bio.gmm.algorithms.GMM` constructor).
However, after the training has finished, it is possible to use the normal ``./bin/verify.py`` script to run similar experiments, e.g., if you want to change the protocol of your experiment.
.. todo:: improve the documentation of the parallelized scripts.
==========================
Python API for bob.bio.gmm
==========================
.. todo:: Improve documentation of the functions and classes of bob.bio.gmm.
Generic functions
-----------------
Miscellaneous functions
~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
bob.bio.base.get_config
Tools to run recognition experiments
------------------------------------
Command line generation
~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
bob.bio.gmm.tools.add_parallel_gmm_options
bob.bio.gmm.tools.initialize_parallel_gmm
bob.bio.gmm.tools.add_jobs
Parallel GMM
~~~~~~~~~~~~
.. autosummary::
bob.bio.gmm.tools.kmeans_initialize
bob.bio.gmm.tools.kmeans_estep
bob.bio.gmm.tools.kmeans_mstep
bob.bio.gmm.tools.gmm_initialize
bob.bio.gmm.tools.gmm_estep
bob.bio.gmm.tools.gmm_mstep
bob.bio.gmm.tools.gmm_project
Parallel ISV
~~~~~~~~~~~~
.. autosummary::
bob.bio.gmm.tools.train_isv
Parallel I-Vector
~~~~~~~~~~~~~~~~~
.. autosummary::
bob.bio.gmm.tools.ivector_estep
bob.bio.gmm.tools.ivector_mstep
bob.bio.gmm.tools.ivector_project
bob.bio.gmm.tools.train_whitener
Integration with bob.bio.video
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
bob.bio.gmm.tools.is_video_extension
bob.bio.gmm.tools.base
bob.bio.gmm.tools.read_feature
Details
-------
.. automodule:: bob.bio.gmm.tools
.. include:: links.rst
==========
References
==========
.. todo:: Provide the correct references for the algorithms defined in this package.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment