Commit 1a20a579 authored by Manuel Günther's avatar Manuel Günther
Browse files

Added and corrected tons of documentation; fixed issues with compressed score...

Added and corrected tons of documentation; fixed issues with compressed score file IO; small corrections
parent 56623d5d
......@@ -29,7 +29,7 @@ class Algorithm:
If your derived algorithm performs feature projection, please register this here.
If it needs training for the projector or the enroller, please set this here, too.
**Keyword Arguments:**
**Parameters:**
performs_projection : bool
Set to ``True`` if your derived algorithm performs a projection.
......@@ -108,7 +108,7 @@ class Algorithm:
It must be overwritten by derived classes, as soon as ``performs_projection = True`` was set in the constructor.
It is assured that the :py:meth:`load_projector` was called once before the ``project`` function is executed.
**Keyword Arguments:**
**Parameters:**
feature : object
The feature to be projected.
......@@ -129,7 +129,7 @@ class Algorithm:
This function will enroll and return the model from the given list of features.
It must be overwritten by derived classes.
**Keyword Arguments:**
**Parameters:**
enroll_features : [object]
A list of features used for the enrollment of one model.
......@@ -150,7 +150,7 @@ class Algorithm:
This function will compute the score between the given model and probe.
It must be overwritten by derived classes.
**Keyword Arguments:**
**Parameters:**
model : object
The model to compare the probe with.
......@@ -177,7 +177,7 @@ class Algorithm:
and fuses the scores using the fusion method specified in the constructor of this class.
Usually this function is called from derived class :py:meth:`score` functions.
**Keyword Arguments:**
**Parameters:**
models : [object]
A list of model objects.
......@@ -205,7 +205,7 @@ class Algorithm:
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:**
**Parameters:**
model : object
A model object to compare the probes with.
......@@ -241,7 +241,7 @@ class Algorithm:
Please register 'performs_projection = True' in the constructor to enable this function.
**Keyword Arguments:**
**Parameters:**
feature : object
A feature as returned by the :py:meth:`project` function, which should be written.
......@@ -261,7 +261,7 @@ class Algorithm:
Please register ``performs_projection = True`` in the constructor to enable this function.
**Keyword Arguments:**
**Parameters:**
feature_file : str or :py:class:`bob.io.base.HDF5File`
The file open for reading, or the file name to read from.
......@@ -284,7 +284,7 @@ class Algorithm:
If you have a different format, please overwrite this function.
**Keyword Arguments:**
**Parameters:**
model : object
A model as returned by the :py:meth:`enroll` function, which should be written.
......@@ -303,7 +303,7 @@ class Algorithm:
If you have a different format, please overwrite this function.
**Keyword Arguments:**
**Parameters:**
model_file : str or :py:class:`bob.io.base.HDF5File`
The file open for reading, or the file name to read from.
......@@ -325,7 +325,7 @@ class Algorithm:
If your algorithm requires different behavior, please overwrite this function.
**Keyword Arguments:**
**Parameters:**
probe_file : str or :py:class:`bob.io.base.HDF5File`
The file open for reading, or the file name to read from.
......@@ -344,7 +344,7 @@ class Algorithm:
If you do this, please also register the function by calling this base class constructor
and enabling the training by ``requires_projector_training = True``.
**Keyword Arguments:**
**Parameters:**
training_features : [object] or [[object]]
A list of *extracted* features that can be used for training the projector.
......@@ -365,7 +365,7 @@ class Algorithm:
Please register `performs_projection = True` in the constructor to enable this function.
**Keyword Arguments:**
**Parameters:**
projector_file : str
The file to read the projector from.
......@@ -378,7 +378,7 @@ class Algorithm:
If you do this, please also register the function by calling this base class constructor
and enabling the training by ``require_enroller_training = True``.
**Keyword Arguments:**
**Parameters:**
training_features : [object] or [[object]]
A list of *extracted* features that can be used for training the projector.
......@@ -396,7 +396,7 @@ class Algorithm:
This function is always called **after** calling :py:meth:`load_projector`.
In this base class implementation, it does nothing.
**Keyword Arguments:**
**Parameters:**
enroller_file : str
The file to read the enroller from.
......
......@@ -14,7 +14,28 @@ import logging
logger = logging.getLogger("bob.bio.base")
class PCA (Algorithm):
"""Performs PCA on the given data"""
"""Performs PCA on the given data.
This algorithm computes a PCA projection (:py:class:`bob.learn.linear.PCATrainer`) on the given training features, projects the features to face space and computes the distance of two projected features in face space.
For eaxmple, the eigenface algorithm as proposed by [TP91]_ can be run with this class.
**Parameters:**
subspace_dimension : int or float
If specified as ``int``, defines the number of eigenvectors used in the PCA projection matrix.
If specified as ``float`` (between 0 and 1), the number of eigenvectors is calculated such that the given percentage of variance is kept.
distance_function : function
A function taking two parameters and returns a float.
If ``uses_variances`` is set to ``True``, the function is provided with a third parameter, which is the vector of variances (aka. eigenvalues).
is_distance_function : bool
Set this flag to ``False`` if the given ``distance_function`` computes a similarity value (i.e., higher values are better)
use_variances : bool
If set to ``True``, the ``distance_function`` is provided with a third argument, which is the vector of variances (aka. eigenvalues).
"""
def __init__(
self,
......@@ -25,8 +46,7 @@ class PCA (Algorithm):
**kwargs # parameters directly sent to the base class
):
"""Initializes the PCA Algorithm with the given setup"""
# call base class constructor and register that the tool performs a projection
# call base class constructor and register that the algorithm performs a projection
Algorithm.__init__(
self,
performs_projection = True,
......@@ -56,7 +76,16 @@ class PCA (Algorithm):
def train_projector(self, training_features, projector_file):
"""Generates the PCA covariance matrix"""
"""Generates the PCA covariance matrix and writes it into the given projector_file.
**Parameters:**
training_features : [1D :py:class:`numpy.ndarray`]
A list of 1D training arrays (vectors) to train the PCA projection matrix with.
projector_file : str
A writable file, into which the PCA projection matrix (as a :py:class:`bob.learn.linear.Machine`) and the eigenvalues will be written.
"""
# Assure that all data are 1D
[self._check_feature(feature) for feature in training_features]
......@@ -89,7 +118,13 @@ class PCA (Algorithm):
def load_projector(self, projector_file):
"""Reads the PCA projection matrix from file"""
"""Reads the PCA projection matrix and the eigenvalues from file.
**Parameters:**
projector_file : str
An existing file, from which the PCA projection matrix and the eigenvalues are read.
"""
# read PCA projector
f = bob.io.base.HDF5File(projector_file)
self.variances = f.read("Eigenvalues")
......@@ -98,14 +133,40 @@ class PCA (Algorithm):
def project(self, feature):
"""Projects the data using the stored covariance matrix"""
"""project(feature) -> projected
Projects the given feature into eigenspace.
**Parameters:**
feature : 1D :py:class:`numpy.ndarray`
The 1D feature to be projected.
**Returns:**
projected : 1D :py:class:`numpy.ndarray`
The ``feature`` projected into eigenspace.
"""
self._check_feature(feature)
# Projects the data
return self.machine(feature)
def enroll(self, enroll_features):
"""Enrolls the model by storing all given input vectors"""
"""enroll(enroll_features) -> model
Enrolls the model by storing all given input vectors.
**Parameters:**
enroll_features : [1D :py:class:`numpy.ndarray`]
The list of projected features to enroll the model from.
**Returns:**
model : 2D :py:class:`numpy.ndarray`
The enrolled model.
"""
assert len(enroll_features)
[self._check_feature(feature, True) for feature in enroll_features]
# just store all the features
......@@ -113,7 +174,24 @@ class PCA (Algorithm):
def score(self, model, probe):
"""Computes the distance of the model to the probe using the distance function"""
"""score(model, probe) -> float
Computes the distance of the model to the probe using the distance function specified in the constructor.
**Parameters:**
model : 2D :py:class:`numpy.ndarray`
The model storing all enrollment features.
probe : 1D :py:class:`numpy.ndarray`
The probe feature vector in eigenspace.
**Returns:**
score : float
A similarity value between ``model`` and ``probe``
"""
self._check_feature(probe, True)
# return the negative distance (as a similarity measure)
if len(model.shape) == 2:
......
......@@ -3,7 +3,7 @@ class Database:
Please use this class as a base class for your database access classes.
Do not forget to call the constructor of this base class in your derived class.
**Keyword Arguments:**
**Parameters:**
name : str
A unique name for the database.
......@@ -94,7 +94,7 @@ class Database:
Returns a sorted version of the given list of File's (or other structures that define an 'id' data member).
The files will be sorted according to their id, and duplicate entries will be removed.
**Keyword Parameters:**
**Parameters:**
files : [:py:class:`File`]
The list of files to be uniquified and sorted.
......@@ -116,7 +116,7 @@ class Database:
Arranges the given list of files by client id.
This function returns a list of lists of File's.
**Keyword Parameters:**
**Parameters:**
files : :py:class:`File`
A list of files that should be split up by :py:attr:`File.client_id`.
......@@ -144,7 +144,7 @@ class Database:
Returns the annotations for the given File object, if available.
It uses :py:func:`bob.db.verification.utils.read_annotation_file` to load the annotations.
**Keyword Parameters:**
**Parameters:**
file : :py:class:`File`
The file for which annotations should be returned.
......@@ -177,7 +177,7 @@ class Database:
Returns the full path of the given File objects.
**Keyword Parameters:**
**Parameters:**
files : [:py:class:`File`]
The list of file object to retrieve the file names for.
......@@ -207,7 +207,7 @@ class Database:
Returns the full path of the original data of the given File objects.
**Keyword Parameters:**
**Parameters:**
files : [:py:class:`File`]
The list of file object to retrieve the original data file names for.
......@@ -233,7 +233,7 @@ class Database:
Returns all files of the database.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
groups : some of ``('world', 'dev', 'eval')`` or ``None``
The groups to get the data for.
......@@ -253,7 +253,7 @@ class Database:
Returns all training File objects for the given step, and arranges them by client, if desired.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
step : one of ``('train_extractor', 'train_projector', 'train_enroller')`` or ``None``
The step for which the training data should be returned.
......@@ -279,7 +279,7 @@ class Database:
Returns a list of model ids for the given group.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the model ids for.
......@@ -300,7 +300,7 @@ class Database:
This function converts the given model id into its according the client id.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
model_id : int or str
A unique ID that identifies the model for the client.
......@@ -322,7 +322,7 @@ class Database:
Returns a list of File objects that should be used to enroll the model with the given model id from the given group.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
model_id : int or str
A unique ID that identifies the model.
......@@ -346,7 +346,7 @@ class Database:
Otherwise, all probe files of the given group are returned.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
model_id : int or str or ``None``
A unique ID that identifies the model.
......@@ -370,7 +370,7 @@ class Database:
Otherwise, all probe files of the given group are returned.
This function needs to be implemented in derived class implementations, if the :py:meth:`uses_probe_file_sets` returns ``True``.
**Keyword Arguments:**
**Parameters:**
model_id : int or str or ``None``
A unique ID that identifies the model.
......@@ -397,7 +397,7 @@ class DatabaseZT (Database):
Returns a list of model ids of T-Norm models for the given group.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the model ids for.
......@@ -411,11 +411,13 @@ 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.
"""client_id_from_t_model_id(t_model_id, group = 'dev') -> client_id
Returns the client id for the given T-Norm model id.
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:**
**Parameters:**
t_model_id : int or str
A unique ID that identifies the T-Norm model.
......@@ -436,7 +438,7 @@ class DatabaseZT (Database):
Returns a list of File objects that should be used to enroll the T-Norm model with the given model id from the given group.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
t_model_id : int or str
A unique ID that identifies the model.
......@@ -457,7 +459,7 @@ class DatabaseZT (Database):
Returns a list of probe File objects used to compute the Z-Norm.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the Z-norm probe files for.
......@@ -475,7 +477,7 @@ class DatabaseZT (Database):
Returns a list of probe FileSet objects used to compute the Z-Norm.
This function needs to be implemented in derived class implementations.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the Z-norm probe files for.
......
......@@ -6,7 +6,7 @@ import bob.db.verification.utils
class DatabaseBob (Database):
"""This class can be used whenever you have a database that follows the Bob verification database interface, which is defined in :py:class:`bob.db.verification.utils.Database`
**Keyword Parameter:**
**Parameters:**
database : derivative of :py:class:`bob.db.verification.utils.Database`
The database instance (such as a :py:class:`bob.db.atnt.Database`) that provides the actual interface, see :ref:`verification_databases` for a list.
......@@ -104,7 +104,7 @@ class DatabaseBob (Database):
If no annotation files are available (e.g. when they are stored inside the ``database``), the annotation directory can be left out.
**Keyword Parameter:**
**Parameters:**
replacements : dict or str
A dictionary with replacements, or a name of a file to read the dictionary from.
......@@ -149,7 +149,7 @@ class DatabaseBob (Database):
Returns all files of the database, respecting the current protocol.
The files can be limited using the ``all_files_options`` in the constructor.
**Keyword Arguments:**
**Parameters:**
groups : some of ``('world', 'dev', 'eval')`` or ``None``
The groups to get the data for.
......@@ -169,7 +169,7 @@ class DatabaseBob (Database):
Returns all training files for the given step, and arranges them by client, if desired, respecting the current protocol.
The files for the steps can be limited using the ``..._training_options`` defined in the constructor.
**Keyword Arguments:**
**Parameters:**
step : one of ``('train_extractor', 'train_projector', 'train_enroller')`` or ``None``
The step for which the training data should be returned.
......@@ -207,7 +207,7 @@ class DatabaseBob (Database):
Returns all test files (i.e., files used for enrollment and probing) for the given groups, respecting the current protocol.
The files for the steps can be limited using the ``all_files_options`` defined in the constructor.
**Keyword Arguments:**
**Parameters:**
groups : some of ``('dev', 'eval')``
The groups to get the data for.
......@@ -224,7 +224,7 @@ class DatabaseBob (Database):
Returns a list of model ids for the given group, respecting the current protocol.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the model ids for.
......@@ -242,7 +242,7 @@ class DatabaseBob (Database):
Uses :py:meth:`bob.db.verification.utils.Database.get_client_id_from_model_id` to retrieve the client id for the given model id.
**Keyword Arguments:**
**Parameters:**
model_id : int or str
A unique ID that identifies the model for the client.
......@@ -263,7 +263,7 @@ class DatabaseBob (Database):
Returns a list of File objects that should be used to enroll the model with the given model id from the given group, respecting the current protocol.
**Keyword Arguments:**
**Parameters:**
model_id : int or str
A unique ID that identifies the model.
......@@ -286,7 +286,7 @@ class DatabaseBob (Database):
If a ``model_id`` is specified, only the probe files that should be compared with the given model id are returned (for most databases, these are all probe files of the given group).
Otherwise, all probe files of the given group are returned.
**Keyword Arguments:**
**Parameters:**
model_id : int or str or ``None``
A unique ID that identifies the model.
......@@ -313,7 +313,7 @@ class DatabaseBob (Database):
If a ``model_id`` is specified, only the probe files that should be compared with the given model id are returned (for most databases, these are all probe files of the given group).
Otherwise, all probe files of the given group are returned.
**Keyword Arguments:**
**Parameters:**
model_id : int or str or ``None``
A unique ID that identifies the model.
......@@ -337,7 +337,7 @@ class DatabaseBob (Database):
Returns the annotations for the given File object, if available.
**Keyword Parameters:**
**Parameters:**
file : :py:class:`bob.db.verification.utils.File`
The file for which annotations should be returned.
......@@ -355,7 +355,7 @@ class DatabaseBob (Database):
Returns the full path of the original data of the given File objects, as returned by :py:meth:`bob.db.verification.utils.Database.original_file_names`.
**Keyword Parameters:**
**Parameters:**
files : [:py:class:`bob.db.verification.utils.File`]
The list of file object to retrieve the original data file names for.
......@@ -373,7 +373,7 @@ class DatabaseBob (Database):
class DatabaseBobZT (DatabaseBob, DatabaseZT):
"""This class can be used whenever you have a database that follows the Bob ZT-norm verification database interface, which is defined in :py:class:`bob.db.verification.utils.ZTDatabase`.
**Keyword Parameters:**
**Parameters:**
database : derivative of :py:class:`bob.db.verification.utils.ZTDatabase`
The database instance (such as a :py:class:`bob.db.mobio.Database`) that provides the actual interface, see :ref:`verification_databases` for a list.
......@@ -406,7 +406,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
Returns all files of the database, including those for ZT norm, respecting the current protocol.
The files can be limited using the ``all_files_options`` and the the ``z_probe_options`` in the constructor.
**Keyword Arguments:**
**Parameters:**
groups : some of ``('world', 'dev', 'eval')`` or ``None``
The groups to get the data for.
......@@ -432,7 +432,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
Returns a list of model ids of T-Norm models for the given group, respecting the current protocol.
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the model ids for.
......@@ -450,7 +450,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
Returns a list of File objects that should be used to enroll the T-Norm model with the given model id from the given group, respecting the current protocol.
**Keyword Arguments:**
**Parameters:**
t_model_id : int or str
A unique ID that identifies the model.
......@@ -472,7 +472,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
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.z_probe_files`
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the Z-norm probe files for.
......@@ -492,7 +492,7 @@ class DatabaseBobZT (DatabaseBob, DatabaseZT):
Returns a list of probe FileSet objects used to compute the Z-Norm.
The Z-probe files can be limited using the ``z_probe_options`` in the query to
**Keyword Arguments:**
**Parameters:**
group : one of ``('dev', 'eval')``
The group to get the Z-norm probe files for.
......
......@@ -19,24 +19,27 @@
from .DatabaseBob import DatabaseBobZT
import bob.db.verification.filelist
class DatabaseFileList (DatabaseBobZT):
"""This class should be used whenever you have an :py:class:`bob.db.verification.filelist.Database`."""
"""This class can be used whenever you have a database that uses the Bob filelist database interface, which is defined in :py:class:`bob.db.verification.filelist.Database`
**Parameters:**
database : a :py:class:`bob.db.verification.filelist.Database`
The database instance that provides the actual interface.
kwargs : ``key=value`` pairs
The arguments of the :py:class:`DatabaseBobZT` or :py:class:`DatabaseBob` base class constructors.
.. note:: Usually, the ``name``, ``protocol``, ``training_depends_on_protocol`` and ``models_depend_on_protocol`` keyword parameters of the base class constructor need to be specified.
"""
def __init__(
self,
database, # The bob database that is used
**kwargs # The default parameters of the base class
):
"""
Parameters of the constructor of this database:
database : :py:class:`bob.db.verification.filelist.Database`
The database that provides the actual interface
kwargs
Keyword arguments directly passed to the :py:class:`DatabaseBobZT` base class constructor
"""
DatabaseBobZT.__init__(
self,
......@@ -44,40 +47,122 @@ class DatabaseFileList (DatabaseBobZT):
**kwargs
)
assert isinstance(database, bob.db.verification.filelist.Database)
def all_files(self, groups = ['dev']):
"""Returns all File objects of the database for the current protocol. If the current protocol is 'None' (a string), None (NoneType) will be used instead"""
files = self.database.objects(protocol = self.protocol if self.protocol != 'None' else None, groups = groups, **self.all_files_options)
"""all_files(groups=None) -> files
Returns all files of the database, respecting the current protocol.
If the current protocol is ``'None'``, ``None`` will be used instead.
When the underlying file list database provides files for ZT score normalization, these files are returned as well.
The files can be limited using the ``all_files_options`` in the constructor.
**Parameters:**
groups : some of ``('world', 'dev', 'eval')`` or ``None``
The groups to get the data for.
If ``None``, data for all groups is returned.
**Returns:**
files : [:py:class:`bob.db.verification.filelist.File`]
The sorted and unique list of all files of the database.
"""
protocol = self.protocol if self.protocol != 'None' else None