Optimized documentation; fixed newly introduced bug in PLDA

bob/bio/base/algorithm/Algorithm.py

@@ -33,7 +33,7 @@ class Algorithm:
 
   performs_projection : bool
     Set to ``True`` if your derived algorithm performs a projection.
-    Also implement the :py:func:`project` function, and the :py:func:`load_projector` if necessary.
+    Also implement the :py:meth:`project` function, and the :py:meth:`load_projector` if necessary.
 
   requires_projector_training : bool
     Only valid, when ``performs_projection = True``.
@@ -41,12 +41,12 @@ class Algorithm:
 
   split_training_features_by_client : bool
     Only valid, when ``performs_projection = True`` and ``requires_projector_training = True``.
-    If set to ``True``, the :py:func:`train_projector` function will receive a double list (a list of lists) of data (sorted by identity).
-    Otherwise, the :py:func:`train_projector` function will receive data in a single list.
+    If set to ``True``, the :py:meth:`train_projector` function will receive a double list (a list of lists) of data (sorted by identity).
+    Otherwise, the :py:meth:`train_projector` function will receive data in a single list.
 
   use_projected_features_for_enrollment : bool
     Only valid, when ``performs_projection = True``.
-    If set to false, the enrollment is performed using the original features, otherwise the features projected using the :py:func:`project` function are used for model enrollment.
+    If set to false, the enrollment is performed using the original features, otherwise the features projected using the :py:meth:`project` function are used for model enrollment.
 
   requires_enroller_training : bool
     Set this flag to ``True``, when the enroller requires specialized training.
@@ -61,7 +61,7 @@ class Algorithm:
     See :py:func:`bob.bio.base.score_fusion_strategy` for possible values.
 
   kwargs : ``key=value`` pairs
-    A list of keyword arguments to be written in the :py:func:`__str__` function.
+    A list of keyword arguments to be written in the :py:meth:`__str__` function.
 
   """
 
@@ -106,7 +106,7 @@ class Algorithm:
 
     This function will project the given feature.
     It must be overwritten by derived classes, as soon as ``performs_projection = True`` was set in the constructor.
-    It is assured that the :py:func:`load_projector` was called once before the ``project`` function is executed.
+    It is assured that the :py:meth:`load_projector` was called once before the ``project`` function is executed.
 
     **Keyword Arguments:**
 
@@ -117,7 +117,7 @@ class Algorithm:
 
     projected : object
       The projected features.
-      Must be writable with the :py:func:`write_feature` function and readable with the :py:func:`read_feature` function.
+      Must be writable with the :py:meth:`write_feature` function and readable with the :py:meth:`read_feature` function.
 
     """
     raise NotImplementedError("Please overwrite this function in your derived class")
@@ -138,7 +138,7 @@ class Algorithm:
 
     model : object
       The model enrolled from the ``enroll_features``.
-      Must be writable with the :py:func:`write_model` function and readable with the :py:func:`read_model` function.
+      Must be writable with the :py:meth:`write_model` function and readable with the :py:meth:`read_model` function.
 
     """
     raise NotImplementedError("Please overwrite this function in your derived class")
@@ -154,11 +154,11 @@ class Algorithm:
 
     model : object
       The model to compare the probe with.
-      The ``model`` was read using the :py:func:`read_model` function.
+      The ``model`` was read using the :py:meth:`read_model` function.
 
     probe : object
       The probe object to compare the model with.
-      The ``probe`` was read using the :py:func:`read_probe` function.
+      The ``probe`` was read using the :py:meth:`read_probe` function.
 
     **Returns:**
 
@@ -173,9 +173,9 @@ class Algorithm:
     """score_for_multiple_models(models, probe) -> score
 
     This function computes the score between the given model list and the given probe.
-    In this base class implementation, it computes the scores for each model using the :py:func:`score` method,
+    In this base class implementation, it computes the scores for each model using the :py:meth:`score` method,
     and fuses the scores using the fusion method specified in the constructor of this class.
-    Usually this function is called from derived class :py:func:`score` functions.
+    Usually this function is called from derived class :py:meth:`score` functions.
 
     **Keyword Arguments:**
 
@@ -202,7 +202,7 @@ class Algorithm:
     """score_for_multiple_probes(model, probes) -> score
 
     This function computes the score between the given model and the given probe files.
-    In this base class implementation, it computes the scores for each probe file using the :py:func:`score` method,
+    In this base class implementation, it computes the scores for each probe file using the :py:meth:`score` method,
     and fuses the scores using the fusion method specified in the constructor of this class.
 
     **Keyword Arguments:**
@@ -244,7 +244,7 @@ class Algorithm:
     **Keyword Arguments:**
 
     feature : object
-      A feature as returned by the :py:func:`project` function, which should be written.
+      A feature as returned by the :py:meth:`project` function, which should be written.
 
     feature_file : str or :py:class:`bob.io.base.HDF5File`
       The file open for writing, or the file name to write to.
@@ -287,7 +287,7 @@ class Algorithm:
     **Keyword Arguments:**
 
     model : object
-      A model as returned by the :py:func:`enroll` function, which should be written.
+      A model as returned by the :py:meth:`enroll` function, which should be written.
 
     model_file : str or :py:class:`bob.io.base.HDF5File`
       The file open for writing, or the file name to write to.
@@ -321,7 +321,7 @@ class Algorithm:
 
     Reads the probe feature from file.
     By default, the probe feature is identical to the projected feature.
-    Hence, this base class implementation simply calls :py:func:`read_feature`.
+    Hence, this base class implementation simply calls :py:meth:`read_feature`.
 
     If your algorithm requires different behavior, please overwrite this function.
 
@@ -353,14 +353,14 @@ class Algorithm:
 
     projector_file : str
       The file to write.
-      This file should be readable with the :py:func:`load_projector` function.
+      This file should be readable with the :py:meth:`load_projector` function.
     """
     raise NotImplementedError("Please overwrite this function in your derived class, or unset the 'requires_projector_training' option in the constructor.")
 
 
   def load_projector(self, projector_file):
     """Loads the parameters required for feature projection from file.
-    This function usually is useful in combination with the :py:func:`train_projector` function.
+    This function usually is useful in combination with the :py:meth:`train_projector` function.
     In this base class implementation, it does nothing.
 
     Please register `performs_projection = True` in the constructor to enable this function.
@@ -386,14 +386,14 @@ class Algorithm:
 
     enroller_file : str
       The file to write.
-      This file should be readable with the :py:func:`load_enroller` function.
+      This file should be readable with the :py:meth:`load_enroller` function.
     """
 
 
   def load_enroller(self, enroller_file):
     """Loads the parameters required for model enrollment from file.
-    This function usually is only useful in combination with the :py:func:`train_enroller` function.
-    This function is always called **after** calling :py:func:`load_projector`.
+    This function usually is only useful in combination with the :py:meth:`train_enroller` function.
+    This function is always called **after** calling :py:meth:`load_projector`.
     In this base class implementation, it does nothing.
 
     **Keyword Arguments:**

bob/bio/base/algorithm/PLDA.py

@@ -144,6 +144,10 @@ class PLDA (Algorithm):
     plda_machine = bob.learn.em.PLDAMachine(bob.io.base.HDF5File(model_file), self.plda_base)
     return plda_machine
 
+  def read_probe(self, probe_file):
+    """Reads the probe using :py:func:`bob.bio.base.load`."""
+    return bob.bio.base.load(probe_file)
+
 
   def score(self, model, probe):
     """Computes the PLDA score for the given model and probe"""

bob/bio/base/database/Database.py

@@ -263,7 +263,7 @@ class Database:
       Should the training files be arranged by client?
 
       .. note::
-         You can use :py:func:`arrange_by_client` in derived class implementations to arrange the files.
+         You can use :py:meth:`arrange_by_client` in derived class implementations to arrange the files.
 
     **Returns:**
 
@@ -412,7 +412,7 @@ class DatabaseZT (Database):
 
   def client_id_from_t_model_id(self, t_model_id, group = 'dev'):
     """Returns the client id for the given T-Norm model id.
-    In this base class implementation, we just use the :py:func:`client_id_from_model_id` function.
+    In this base class implementation, we just use the :py:meth:`client_id_from_model_id` function.
     Overload this function if you need another behavior.
 
     **Keyword Arguments:**

bob/bio/base/database/DatabaseBob.py

@@ -173,13 +173,11 @@ class DatabaseBob (Database):
 
     step : one of ``('train_extractor', 'train_projector', 'train_enroller')`` or ``None``
       The step for which the training data should be returned.
-      Might be ignored in derived class implementations.
 
     arrange_by_client : bool
       Should the training files be arranged by client?
-
-      .. note::
-         You can use :py:func:`arrange_by_client` in derived class implementations to arrange the files.
+      If set to ``True``, training files will be returned in [[:py:class:`bob.db.verification.utils.File`]], where each sub-list contains the files of a single client.
+      Otherwise, all files will be stored in a simple [:py:class:`bob.db.verification.utils.File`].
 
     **Returns:**
 
@@ -381,7 +379,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
     The database instance (such as a :py:class:`bob.db.mobio.Database`) that provides the actual interface, see :ref:`verification_databases` for a list.
 
   z_probe_options : dict
-    Dictionary of options passed to the :py:meth:`bob.db.verification.utils.ZTDatabase.z_objects` database query when retrieving files for Z-probing.
+    Dictionary of options passed to the :py:meth:`bob.db.verification.utils.ZTDatabase.z_probe_files` database query when retrieving files for Z-probing.
 
   kwargs : ``key=value`` pairs
     The arguments of the :py:class:`DatabaseBob` base class constructor.
@@ -472,7 +470,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
     """z_probe_files(group = 'dev') -> files
 
     Returns a list of probe files used to compute the Z-Norm, respecting the current protocol.
-    The Z-probe files can be limited using the ``z_probe_options`` in the query to :py:meth:`bob.db.verification.utils.ZTDatabase.zobjects`
+    The Z-probe files can be limited using the ``z_probe_options`` in the query to :py:meth:`bob.db.verification.utils.ZTDatabase.z_probe_files`
 
     **Keyword Arguments:**
 
@@ -504,5 +502,5 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
     files : [:py:class:`FileSet`] or similar
       The unique list of file sets used to compute the Z-norm.
     """
-    file_sets = self.database.z_probf_file_sets(protocol = self.protocol, groups = group, **self.z_probe_options)
+    file_sets = self.database.z_probe_file_sets(protocol = self.protocol, groups = group, **self.z_probe_options)
     return self.sort(file_sets)

bob/bio/base/database/DatabaseFileList.py

@@ -21,7 +21,7 @@
 from .DatabaseBob import DatabaseBobZT
 
 class DatabaseFileList (DatabaseBobZT):
-  """This class should be used whenever you have an :py:class:`bob.db.verification.filelist.Database``."""
+  """This class should be used whenever you have an :py:class:`bob.db.verification.filelist.Database`."""
 
   def __init__(
       self,

bob/bio/base/extractor/Extractor.py

@@ -31,14 +31,14 @@ class Extractor:
 
   requires_training : bool
     Set this flag to ``True`` if your feature extractor needs to be trained.
-    In that case, please override the :py:func:`train` and :py:func:`load` methods
+    In that case, please override the :py:meth:`train` and :py:meth:`load` methods
 
   split_training_data_by_client : bool
     Set this flag to ``True`` if your feature extractor requires the training data to be split by clients.
     Ignored, if ``requires_training`` is ``False``
 
   kwargs : ``key=value`` pairs
-    A list of keyword arguments to be written in the :py:func:`__str__` function.
+    A list of keyword arguments to be written in the :py:meth:`__str__` function.
   """
 
   def __init__(
@@ -103,7 +103,7 @@ class Extractor:
     **Keyword Arguments:**
 
     feature : object
-      The extracted feature, i.e., what is returned from :py:func:`__call__`.
+      The extracted feature, i.e., what is returned from :py:meth:`__call__`.
 
     feature_file : str or :py:class:`bob.io.base.HDF5File`
       The file open for writing, or the name of the file to write.
@@ -131,7 +131,7 @@ class Extractor:
 
   def load(self, extractor_file):
     """Loads the parameters required for feature extraction from the extractor file.
-    This function usually is only useful in combination with the :py:func:`train` function.
+    This function usually is only useful in combination with the :py:meth:`train` function.
     In this base class implementation, it does nothing.
 
     **Keyword Arguments:**
@@ -156,6 +156,6 @@ class Extractor:
 
     extractor_file : str
       The file to write.
-      This file should be readable with the :py:func:`load` function.
+      This file should be readable with the :py:meth:`load` function.
     """
     raise NotImplementedError("Please overwrite this function in your derived class, or unset the 'requires_training' option in the constructor.")

bob/bio/base/grid.py

@@ -35,11 +35,11 @@ PREDEFINED_QUEUES = {
 class Grid:
   """This class is defining the options that are required to submit parallel jobs to the SGE grid, or jobs to the local queue.
 
-  If the given ``grid`` is ``'sge'`` (the default), this configuration is set up to submit algorithms to the SGE grid.
+  If the given ``grid_type`` is ``'sge'`` (the default), this configuration is set up to submit algorithms to the SGE grid.
   In this setup, specific SGE queues can be specified for different steps of the tool chain, and different numbers of parallel processes can be specified for each step.
   Currently, only the SGE at Idiap_ is tested and supported, for other SGE's we do not assure compatibility.
 
-  If the given ``grid`` is ``'local'``, this configuration is set up to run using a local scheduler on a single machine.
+  If the given ``grid_type`` is ``'local'``, this configuration is set up to run using a local scheduler on a single machine.
   In this case, only the ``number_of_parallel_processes`` and ``scheduler_sleep_time`` options will be taken into account.
 
   **Keyword Parameters:**
@@ -49,15 +49,16 @@ class Grid:
     Currently, only sge and local submissions are supported.
 
   number_of_preprocessing_jobs, number_of_extraction_jobs, number_of_projection_jobs, number_of_enrollment_jobs, number_of_scoring_jobs : int
-    Only valid if ``grid = 'sge'``.
+    Only valid if ``grid_type = 'sge'``.
     The number of parallel processes that should be executed for preprocessing, extraction, projection, enrollment or scoring.
 
   training_queue, preprocessing_queue, extraction_queue, projection_queue, enrollment_queue, scoring_queue : str or dict
+    Only valid if ``grid_type = 'sge'``.
     SGE queues that should be used for training, preprocessing, extraction, projection, enrollment or scoring.
     The queue can be defined using a dictionary of keywords that will directly passed to the :py:func:`gridtk.tools.qsub` function, or one of our :py:data:`PREDEFINED_QUEUES`, which are adapted for Idiap_.
 
   number_of_parallel_processes : int
-    Only valid if ``grid = 'local'``.
+    Only valid if ``grid_type = 'local'``.
     The number of parallel processes, with which the preprocessing, extraction, projection, enrollment and scoring should be executed.
 
   scheduler_sleep_time : float
@@ -123,7 +124,7 @@ class Grid:
     This helper function translates the given queue parameters to grid options.
     When the given ``params`` are a dictionary already, they are simply returned.
     If ``params`` is a string, the :py:data:`PREDEFINED_QUEUES` are indexed with them.
-    If ``params`` is ``None``, or the :py:attr:`grid_type` is ``'local'``, an empty dictionary is returned.
+    If ``params`` is ``None``, or the ``grid_type`` is ``'local'``, an empty dictionary is returned.
     """
     if self.is_local():
       return {}

bob/bio/base/preprocessor/Preprocessor.py

@@ -30,7 +30,7 @@ class Preprocessor:
   **Keyword Arguments:**
 
   kwargs : ``key=value`` pairs
-    A list of keyword arguments to be written in the :py:func:`__str__` function.
+    A list of keyword arguments to be written in the :py:meth:`__str__` function.
   """
 
   def __init__(self, **kwargs):
@@ -108,7 +108,7 @@ class Preprocessor:
     **Keyword Arguments:**
 
     data : object
-      The preprocessed data, i.e., what is returned from :py:func:`__call__`.
+      The preprocessed data, i.e., what is returned from :py:meth:`__call__`.
 
     data_file : str or :py:class:`bob.io.base.HDF5File`
       The file open for writing, or the name of the file to write.

doc/conf.py

@@ -246,7 +246,7 @@ autodoc_default_flags = ['members', 'inherited-members', 'show-inheritance']
 
 # For inter-documentation mapping:
 from bob.extension.utils import link_documentation
-intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.io.base', 'bob.db.verification.utils', 'bob.bio.face', 'bob.bio.speaker', 'bob.bio.gmm', 'bob.bio.video', 'bob.bio.csu', 'gridtk'])
+intersphinx_mapping = link_documentation(['python', 'numpy', 'bob.io.base', 'bob.db.verification.utils', 'bob.db.verification.filelist', 'bob.bio.face', 'bob.bio.speaker', 'bob.bio.gmm', 'bob.bio.video', 'bob.bio.csu', 'gridtk'])
 
 
 def skip(app, what, name, obj, skip, options):