Clean up of struct_bio_rec_sys.rst and experiments.rst, simplify index.rst

doc/experiments.rst

@@ -9,15 +9,14 @@
 Running Biometric Recognition Experiments
 ==========================================
 
-Now, you are almost ready to run your first biometric recognition experiment.
-Just a little bit of theory, and then: off we go.
+Now, you are ready to run your first biometric recognition experiment.
 
 .. _running_part_1:
 
 Running Experiments (part I)
 ----------------------------
 
-To run an experiment, we provide a generic script ``verify.py``, which is highly parametrizable.
+To run an experiment, we provide a generic script ``verify.py``, which is highly parameterizable.
 To get a complete list of command line options, please run:
 
 .. code-block:: sh
@@ -51,7 +50,7 @@ To get a list of registered resources, please call:
 
 Each package in ``bob.bio`` defines its own resources, and the printed list of registered resources differs according to the installed packages.
 If only ``bob.bio.base`` is installed, no databases and only one preprocessor will be listed.
-To see more details about the resources, i.e., the full constructor call fo the respective class, use the ``--details`` (or shortly ``-d``) option, and to sub-select only specific types of resources, use the ``--types`` (or ``-t``) option:
+To see more details about the resources, i.e., the full constructor call for the respective class, use the ``--details`` (or shortly ``-d``) option, and to sub-select only specific types of resources, use the ``--types`` (or ``-t``) option:
 
 .. code-block:: sh
 

doc/index.rst

@@ -9,28 +9,24 @@
 ===========================================
 
 The ``bob.bio`` packages provide open source tools to run comparable and reproducible biometric recognition experiments.
-To design a biometric recognition experiment, one has to choose:
+To design a biometric recognition experiment, you must choose:
 
-* a databases containing the original data, and a protocol that defines how to use the data,
-* a data preprocessing algorithm, e.g., face detection for face recognition experiments or voice activity detection for speaker recognition,
-* the type of features to extract from the preprocessed data,
-* the biometric recognition algorithm to employ,
-* the score fusion to combine outputs from different systems, and
-* the way to evaluate the results
+* A database to use for the raw biometric data and a protocol that defines how to use that data,
+* A data preprocessing algorithm to clean up the raw biometric data,
+* A feature extractor to extract the desired type of features from the preprocessed data,
+* A biometric matching algorithm,
+* An evaluation method to make sense of the matching scores.
 
-For any of these parts, several different types are implemented in the ``bob.bio`` packages, and basically any combination of the six parts can be executed.
-For each type, several meta-parameters can be tested.
-This results in a nearly infinite amount of possible experiments that can be run using the current setup.
-But it is also possible to use your own database, preprocessor, feature extractor, or biometric recognition algorithm and test this against the baseline algorithms implemented in the our packages.
+The ``bob.bio`` packages contain several implementations of each of the above steps, so you can either choose from the existing methods or use your own.   
 
 .. note::
    The ``bob.bio`` packages are derived from the former `FaceRecLib <http://pypi.python.org/pypi/facereclib>`__, which is herewith outdated.
 
-This package :py:mod:`bob.bio.base` includes the basic definition of a biometric recognition experiment, as well as a generic script, which can execute the full biometric experiment in a single command line.
-Changing the employed tools such as the database, protocol, preprocessor, feature extractor or recognition algorithm is as simple as changing a parameter in a configuration file or on the command line.
+The :py:mod:`bob.bio.base` package includes the basic definition of a biometric recognition experiment, as well as a generic script, which can execute the full biometric experiment in a single command line.
+Changing the employed tools, such as the database, protocol, preprocessor, feature extractor or matching algorithm is as simple as changing a parameter in a configuration file or on the command line.
 
 The implementation of (most of) the tools is separated into other packages in the ``bob.bio`` namespace.
-All these packages can be easily combined.
+All of these packages can be easily combined.
 Here is a growing list of derived packages:
 
 * :ref:`bob.bio.spear <bob.bio.spear>` Tools to run speaker recognition experiments, including voice activity detection, Cepstral feature extraction, and speaker databases

doc/struct_bio_rec_sys.rst

+..  _bob.bio.base.struct_bio_rec_sys:
+
 ============================================
 Structure of a Biometric Recognition System
 ============================================
 
+This section will familiarize you with the structure of a typical biometric recognition system to help you understand and use the ``bob.bio`` framework to set up your own biometric recognition experiments.
+
 "Biometric recognition" refers to the process of establishing a person's identity based on their biometric data.
 A biometric recognition system can operate in one of two modes: *verification* or *identification*.  
 A *verification* system establishes whether or not a person is who they say they are (i.e., the person claims an identity and the system tries to prove whether or not that claim is true).
@@ -100,7 +104,7 @@ The matching stage in ``bob.bio`` is referred to as the "Algorithm".  The Algori
 
    The enrollment part of the Algorithm stage in ``bob.bio``'s biometric recognition experiment framework.
 
-Note that there is sometimes a model enroller training stage prior to enrollment.  This is only necessary when you are trying to fit an existing model to a set of biometric features, e.g., fitting a UBM to features extracted from a speech signal.  In other cases, the model is calculated from the features themselves, e.g., by averaging the feature vectors from multiple samples of the same biometric, in which case model enroller training is not necessary.
+Note that there is sometimes a model enroller training stage prior to enrollment.  This is only necessary when you are trying to fit an existing model to a set of biometric features, e.g., fitting a UBM (Universal Background Model) to features extracted from a speech signal.  In other cases, the model is calculated from the features themselves, e.g., by averaging the feature vectors from multiple samples of the same biometric, in which case model enroller training is not necessary.
 
 
 (iii) Scoring: The scoring part of the Algorithm stage essentially works as follows.  Each model is associated with a number of probes, so we first query the input biometric database to determine which biometric samples should be used as the probes for each model.  Every model is then compared to its associated probes (some of which come from the same person, and some of which come from different people), and a score is calculated for each comparison.  The score may be a distance, and it tells us how similar or dissimilar the model and probe biometrics are.  Ideally, if the model and probe come from the same biometric (e.g., two images of the same finger), they should be very similar, and if they come from different sources (e.g., two images of different fingers) then they should be very different.  Fig. 7 illustrates the scoring part of the Algorithm module:
@@ -124,10 +128,11 @@ Once a decision has been made, we can quantify the overall performance of the pa
    Evaluation stage in ``bob.bio``'s biometric recognition experiment framework.
 
 
-*Notes:*
+.. note::
 
-* The communication between any two steps in the recognition framework is file-based, usually using a binary HDF5_ interface, which is implemented, for example, in the :py:class:`bob.io.base.HDF5File` class.
-* The output of one step usually serves as the input of the subsequent step(s), as portrayed in Fig. 3 -- Fig. 7.
-* ``bob.bio`` ensures that the correct files are always forwarded to the subsequent steps.  For example, if you choose to implement a feature projection after the feature extraction stage, as illustrated in Fig. 5, ``bob.bio`` will make sure that the files in the "projected" directory are passed on as the input to the Enrollment stage; otherwise, the "extracted" directory will become the input to the Enrollment stage.
+   * The "Data Preprocessing" to "Matching" steps are carried out by ``bob.bio.base``s ``verify.py`` script.  The "Decision Making" step is carried out by ``bob.bio.base``'s ``evaluate.py`` script.  These scripts will be discussed in the next sections. 
+   * The communication between any two steps in the recognition framework is file-based, usually using a binary HDF5_ interface, which is implemented, for example, in the :py:class:`bob.io.base.HDF5File` class.
+   * The output of one step usually serves as the input of the subsequent step(s), as portrayed in Fig. 3 -- Fig. 7.
+   * ``bob.bio`` ensures that the correct files are always forwarded to the subsequent steps.  For example, if you choose to implement a feature projection after the feature extraction stage, as illustrated in Fig. 5, ``bob.bio`` will make sure that the files in the "projected" directory are passed on as the input to the Enrollment stage; otherwise, the "extracted" directory will become the input to the Enrollment stage.
 
 .. include:: links.rst
\ No newline at end of file