Commit 5274081c authored by Zohreh MOSTAANI's avatar Zohreh MOSTAANI

[general][doc] added hands-on experiment with fixes in links

parent f9a8f258
Pipeline #24623 passed with stages
in 5 minutes and 14 seconds
......@@ -23,9 +23,9 @@
.. _beat-system:
==============
===========================
Getting Started with BEAT
==============
===========================
The Beat system has certain building blocks used by all the packages in the BEAT
software suite. These are:
......@@ -42,11 +42,14 @@ software suite. These are:
parameters that allow the system to run the prescribed recipe
to produce displayable results.
.. note::
All this building blocks are stored in a folder typically named `prefix`. We will get back to this in :ref:`tutorial`
.. _beat-system-example:
A Simple Example
----------------
================
The next figure shows a representation of a very simple toolchain, composed of
only a few color-coded components:
......@@ -121,7 +124,7 @@ experimental setup.
.. _beat-system-design:
Design
------
======
The next figure shows an UML representation of main BEAT components, showing
some of their interaction and interdependence. Experiments use algorithms, data
......@@ -178,11 +181,16 @@ such users to create, modify and dispose of such objects using their own private
editors. When using BEAT locally the graphical user interface is used in parallel
with the command-line interface.
BEAT Building Blocks
====================
For developers and programmers, the rest of this guide details each of
BEAT building blocks, their relationships and how to use such a command-line
interface to interact with the platform efficiently.
.. toctree::
dataformats
......
......@@ -18,3 +18,4 @@
.. _conda: https://conda.io/
.. _beat editor: https://www.idiap.ch/software/beat/docs/beat/docs/new/beat.editor/doc/index.html
.. _bob: https://www.idiap.ch/software/bob/docs/bob/docs/stable/bob/doc/index.html
.. _idiap: http://www.idiap.ch
.. _tutorial:
============
User Guide
============
=====================
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.
Requirements
============
#. A ``beat.editor`` installation: Please follow the Installation guide.
#. BEAT familiarity: This guide assumes you are somewhat familiar with what BEAT is and how it works. Please see the `BEAT User Guide <https://www.beat-eu.org/platform/static/guide/index.html>`_ and refer to it if you come across an unfamiliar BEAT term or concept.
#. A BEAT prefix: The BEAT prefix found in the ``prefix/`` folder in the ``beat.tutorial.prefix`` repository is used in the tutorial. If you are using the VM image, you will find this folder at ``~/beat.tutorial.prefix/prefix/``, otherwise you will need to download it yourself.
#. The following (Bob) packages installed in the same Conda environment as ``beat.editor`` (already installed in the VM):
- ``bob``
- ``bob.db.iris``
- ``bob.bio.base``
- ``bob.bio.face``
- ``ipdb``
#. 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 named ``prefix``. For the purpose of this tutorial we provide a ``prefix``. 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 this project, 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 your conda environment and then install the packages needed for this tutorial.
.. code:: sh
$ 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 Workflow
============
......@@ -29,25 +36,27 @@ There are a few things you have to do to create BEAT objects locally:
Each of these steps is filled by a different tool:
#. ``beat.editor`` edits metadata through a web app
#. You use your own editor of your choice to edit code
#. ``beat.cmdline`` does "the rest", letting you run & visualize experiments, manage the cache, debug, and much more (see that project's documentation for more)
#. ``beat.editor`` edits metadata through a web application.
#. You use your own editor of your choice to edit the neccasary 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`.
You might have a window setup like the following:
.. image:: ./img/workflow_screenshot.png
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 app.
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
==========
This has been referenced above but not explained. The prefix is a folder that holds all of your BEAT object data in a certain format. This folder is commonly named `prefix` but 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.
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
==============
Let's make sure your installation is working as intended. Run the following in a terminal (in the parent folder of your prefix!): ::
Let's make sure your installation is working as intended. Run the following in a terminal (in the parent folder of your prefix!):
.. code:: sh
$ beat exp list
......@@ -104,7 +113,6 @@ We will get 3 figures of merit from running the experiment:
* ROC plot
* Scores histogram plot
To simplify code examples, we will be using `Bob`, a free signal-processing and machine learning toolbox developed by the same group that BEAT is.
Designing our Experiment outside of BEAT
----------------------------------------
......
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