Commit 384de23a authored by Zohreh's avatar Zohreh

[general][doc] eddited more the hands on tutorial

parent ea5220cc
Pipeline #24964 passed with stages
in 8 minutes and 38 seconds
* introduce the file system organisation
* introduce what is a prefix
* explain how to retrieve a "test" prefix
.. note::
All these building blocks are stored in a folder typically named `prefix`.
We will get back to this in :ref:`tutorial-`
.. _tutorial-:
=====================
A Hands-On Tutorial
=====================
This section includes the user-facing guide for creating BEAT objects locally using ``beat.editor`` and ``beat.cmdline``, in the form of a tutorial.
This section includes the user-facing guide for creating BEAT objects locally using ``beat.editor`` and ``beat.cmdline``, in the form of a tutorial.
Requirements
============
#. Working Internet connection.
#. Firefox or Chrome browser.
#. A ``BEAT`` installation: Please see :ref:`beat-installation`.
#. BEAT familiarity: This guide assumes you are somewhat familiar with what BEAT is and how it works. Please see :ref:`beat-system` and refer to it if you come across an unfamiliar BEAT term or concept.
#. A BEAT ``prefix``: All the building blocks of BEAT is stored in a folder typically named ``prefix``. For the purpose of this tutorial we provide this folder. Please download the prefix folder in this `git repository <https://gitlab.idiap.ch/beat/beat.tutorial.prefix>`_ . Run any BEAT commands relating to the prefix in the top-level folder of it, next to the prefix folder.
#. To simplify code examples, we will be using `Bob`_, a free signal-processing and machine learning toolbox originally developed by the Biometrics group at `Idiap`_ Research Institute, Switzerland. Please add the Conda channel for ``bob`` to the Conda environment with BEAT packages are installed and then install the packages needed for this tutorial.
* Working Internet connection.
* Firefox or Chrome browser.
* A **BEAT** installation: Please see :ref:`beat-installation`.
* BEAT familiarity: This guide assumes you are somewhat familiar with what BEAT is and how it works. Please see :ref:`beat-system` and refer to it if you come across an unfamiliar BEAT term or concept.
* A BEAT **prefix**: All the building blocks of BEAT is stored in a directory typically named *prefix* (see :ref:`prefix`). For the purpose of this tutorial we provide this folder. Please download the prefix folder in this `git repository <https://gitlab.idiap.ch/beat/beat.tutorial.prefix>`_ . Run any BEAT commands relating to the prefix in the top-level folder of it, next to the prefix folder.
.. code:: sh
* To simplify code examples, we will be using `Bob`_, a free signal-processing and machine learning toolbox originally developed by the Biometrics group at `Idiap`_ Research Institute, Switzerland. Please add the Conda channel for ``bob`` to the Conda environment with BEAT packages are installed and then install the packages needed for this tutorial.
.. code:: sh
$ conda activate beat
$ conda config --env --add channels https://www.idiap.ch/software/bob/conda
$ conda install bob bob.db.iris bob.bio.base bob.bio.face ipdb
.. _prefix:
$ conda activate beat_py3
$ conda config --env --add channels https://www.idiap.ch/software/bob/conda
$ conda install bob bob.db.iris bob.bio.base bob.bio.face ipdb
The Prefix
==========
The root of the BEAT object installation is commonly referred as a *prefix*. The
prefix is just a path to a known directory to which the user has write access, and it holds all of BEAT object data in a certain format. This directory is commonly named ``prefix`` but it could be named anything. This is the typical directory structure in a *prefix*:
.. code-block:: sh
../prefix/
├── algorithms
├── cache
├── databases
├── dataformats
├── experiments
├── libraries
├── plotterparameters
├── plotters
└── toolchains
Each of the subdirectories in the *prefix* keeps only objects of a given type.
For example, the ``dataformats`` subdirectory keeps only data format objects,
and so on. Inside each subdirectory, the user will find an organization that
resembles the naming convention of objects in the BEAT framework. For example,
you'd be able to find the data format ``my_dataformat``, belonging to user
``user``, version ``1``, under the directory
``<prefix>/dataformats/user/my_dataformat/1``. Objects are described by a JSON
file, an optional full-length description in reStructuredText format and,
depending on the object type, a program file containing user routines
programmed in one of the supported languages.
All the commands from ``beat.editor`` or ``beat.cmdline`` commands should be run it in the parent folder of prefix. Otherwise the system will not be able to access the BEAT objects. For more information about configuring the prefix please see :ref:`Command-line configurations <beat-cmdline-configuration>`.
The Workflow
============
BEAT objects consist of two main components.
There are a few things you have to do to create BEAT objects locally:
#. Create & edit the metadata of BEAT objects.
#. Edit the Python code for certain types of BEAT objects.
#. Test, debug, visualize, and manage your BEAT objects.
* A json file that represents the metadata of the object.
* A piece of code in the supported backend language (python or C++) that defines the behaviour of certain type of objects.
Each of these steps is filled by a different tool:
To use BEAT locally you need to be able to create and edit the mentioned components for BEAT objects, test and debug them, vialize and manage them, and finally run an experiment. These can be done using different tools in BEAT.
#. ``beat.editor`` edits metadata through a web application.
#. You use the editor of your choice to edit the necessary codes.
#. ``beat.cmdline`` does "the rest", letting you run & visualize experiments, manage the cache, debug, and much more. For more information see :ref:`beat_cmdline_introduction`.
* ``beat.editor`` is a graphical web application that enables you to edit metadata and manage the objects.
* The codes can be eddited using the eidtor of your choice.
* ``beat.cmdline`` does "the rest", letting you run and visualize experiments, manage the cache, debug, and much more. For more information see :ref:`beat_cmdline_introduction`.
You might have a window setup like the following:
......@@ -57,10 +79,6 @@ You might have a window setup like the following:
One of the terminals is for running the ``beat.editor`` server; one is for editing code and running ``beat.cmdline`` commands; the browser is for using the ``beat.editor`` web application.
The Prefix
==========
The prefix is a folder that holds all of your BEAT object data in a certain format. This folder is commonly named ``prefix`` but it could be named anything. Whenever you run any ``beat.editor`` or ``beat.cmdline`` commands, run it in the parent folder of your prefix. If you don't, the system won't know where your BEAT objects are and will probably not do or show anything. For more information about configuring the prefix please see :ref:`Command-line configurations <beat-cmdline-configuration>`.
A Sanity Check
==============
......@@ -157,7 +175,7 @@ Then we analyze our scores and generate our figures of merit:
And there is our conceptual experiment diagram! You've probably seen and thought of designs similar to this. Let's see how to split it into BEAT objects.
The data for BEAT experiments come from `databases`, so we need one of those:
We need `database` block that provides data to the BEAT experiments:
.. image:: ./img/iris_diagram_database.png
:width: 500px
......@@ -171,7 +189,7 @@ We need an `algorithm` for training the LDA machine:
:align: center
:height: 261px
We need another algorithm for testing the model:
We need another `algorithm` for testing the model:
.. image:: ./img/iris_diagram_testing.png
:width: 500px
......
Markdown is supported
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