Commit c054de7a authored by Zohreh MOSTAANI's avatar Zohreh MOSTAANI

[general][doc] combining the information about toolchains on beat.core and beat.web

parent 5095b3c9
Pipeline #24914 passed with stages
in 9 minutes and 24 seconds
This diff is collapsed.
......@@ -90,7 +90,7 @@ Similarly to algorithms, a library consists of two folds:
return value * self.multiplier
The graphical interface of BEAT provides editors for the main components of the
system (for example: algorithms, data formats, etc.), which simplifies their
system (for example: libraries, data formats, etc.), which simplifies their
`JSON`_ declaration definition.
......
......@@ -19,3 +19,4 @@
.. _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
.. _eigenface: https://en.wikipedia.org/wiki/Eigenface
\ No newline at end of file
......@@ -27,31 +27,116 @@
Toolchains
============
A toolchain describes the workflow of a particular experiment. Its declaration
defines:
Toolchains are the backbone of experiments within the BEAT framework. They
determine the data flow for experiments in BEAT.
* a collection of *processing blocks*, including for each of them:
You can see an example toolchain for a toy `eigenface`_ system on the image
below.
* a *name* (unique in the toolchain)
* a list of *inputs*
* a list of *outputs*
.. _beat-system-toolchains-example-figure:
.. figure:: img/eigenfaces.*
A complete toolchain that train and test an Eigenfaces system
From this block diagram, the framework can identify all it requires to conduct
an experiment with this workflow:
* There are three types of blocks:
1. **Dataset blocks** (light yellow, left side): are the input blocks of a
toolchain. They only have outputs.
2. **Regular blocks** (gray): represent processing steps of the toolchain.
3. **Analysis blocks** (light blue, right side): is the output of a
toolchain. They only have inputs.
* Each block defines *place holders* for datasets and algorithms to be
inserted when the user wants to execute an experiment based on such a
toolchain (see the :ref:`beat-system-experiments` section).
* Each block is linked to the next one via a **connection**. The sequence of
blocks in a toolchain and their connectivity defines a natural data flow.
Data is output by data sets on the left and flow to the right until a
result is produced.
* Each dataset block (light yellow, left side) define a unique
*synchronization channel*, which is encoded in BEAT via a color.
For example, the sychronization channel ``train`` is blue. The
synchronization channel ``templates`` is green and, finally, the
synchronization channel ``probes`` is red.
* Each regular or analysis block on the toolchain respects exactly one of
these synchronization channels. This is indicated by the colored circle on
the top-right of each block. For example, the block called ``scoring`` is
said to be *synchronized with* the ``probes`` channel.
When a block is synchronized with a channel, it means the platform will
iterate on that channel contents when calling the user algorithm on that
block. For example, the block ``linear_(machine)_training``, on the top
left of the image, following the data set block ``train``, is synchronized
with that dataset block. Therefore, it will be executed as many times as
the dataset block outputs objects through its ``image`` output. I.e., the
``linear_machine_training`` block *loops* or *iterates* over the ``train``
data.
Notice, the toolchain does not define what an ``image`` will be. That is
defined by the concrete dataset implementation chosen by the user when an
experiment is constructed. The block ``linear_machine_training`` also does not
define which type of images it can input. That is defined by the algorithm
chosen by the user when an experiment is constructed. For example, if the user
chooses a data set that outputs objects with the data format
``system/array_2d_uint8/1`` objects then, an algorithm that can input those
types of objects must be chosen for the block following that dataset. Don't
worry! |project| experiment configuration will check that for you!
The order of execution can also be abstracted from this diagram. We sketched
that for you in this overlay:
.. image:: img/eigenfaces-ordered.*
The backend processing farm will first "push" the data out of the datasets. It
will then run the code on the block ``linear_machine_training`` (numbered 2).
The blocks ``template_builder`` and ``probe_builder`` are then ready to run.
The BEAT framework may choose to run them at the *same time* if enough computing
resources are available. The ``scoring`` block runs by fourth. The last block
to be executed is the ``analysis`` block. In the figure above, you can also see
marked what is the channel data in which the block *loops* on. When you read
about :ref:`beat-system-experiments`, you'll understand, concretely, how synchronization is
handled on algorithm code.
.. note:: **Naming Convention**
Toolchains are named using three values joined by a ``/`` (slash) operator:
* **username**: indicates the author of the toolchain
* **name**: indicates the name of the toolchain
* **version**: indicates the version (integer starting from ``1``) of the
toolchain
Each tuple of these three components defines a *unique* toolchain name
inside the framework.
* the *interconnections* between those blocks (from an output to an input)
* a list of *datasets*, that yield raw input data for the experiment
* a list of *result outputs*, that produce the results of the experiment
.. _beat-system-toolchains-declaration:
Declaration of a toolchain
--------------------------
The declaration of a toolchain defines:
.. note::
* a collection of *processing blocks*, including for each of them:
* a *name* (unique in the toolchain)
* a list of *inputs*
* a list of *outputs*
* the *interconnections* between those blocks (from an output to an input)
* a list of *datasets*, that yield raw input data for the experiment
* a list of *result outputs*, that produce the results of the experiment
One needs only to declare a toolchain using those specifications when not
using the web interface (i.e. when doing local development or using the web
api). The web interface provides a user-friendly way to declare and modify
toolchains.
A toolchain is declared in a JSON file, and must contain at least the following
fields:
......@@ -78,6 +163,10 @@ For display purposes, the JSON file may contain an additional field called
a graphical way.
The graphical interface of BEAT provides editors for the main components of the
system (for example: toolchains, data formats, etc.), which simplifies their
`JSON`_ declaration definition.
.. _beat-system-toolchains-datasets:
Declaration of the datasets
......@@ -312,10 +401,6 @@ on the web interface.
Putting it all together: a complete example
-------------------------------------------
.. _beat-system-toolchains-example-figure:
.. figure:: img/toolchain-example-2.*
A complete toolchain that train and test an Eigenfaces system
The following example describes the toolchain visible at
:numref:`beat-system-toolchains-example-figure`, a complete toolchain that:
......@@ -499,3 +584,4 @@ The following example describes the toolchain visible at
]
}
.. include:: links.rst
\ No newline at end of file
......@@ -16,6 +16,7 @@
.. _markdown: http://daringfireball.net/projects/markdown/
.. _restructuredtext: http://docutils.sourceforge.net/rst.html
.. _conda: https://conda.io/
.. _beat editor: https://www.idiap.ch/software/beat/docs/beat/docs/new/beat.editor/doc/index.html
.. _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
.. _eigenface: https://en.wikipedia.org/wiki/Eigenface
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