Commit 0cf2fda0 authored by Flavio TARSETTI's avatar Flavio TARSETTI

Merge branch 'remove_edition_from_doc' into 'remove_asset_edition'

Remove edition from doc

See merge request !407
parents b267f967 c7a4fe84
Pipeline #43879 passed with stage
in 15 minutes and 56 seconds
......@@ -29,130 +29,8 @@
Algorithms are user-defined piece of software that run within the blocks of a
toolchain. An algorithm can read data on the input(s) of the block and write
processed data on its output(s). For detailed information see the "Algorithms" section of "Getting Started with BEAT" in `BEAT documentation`_.
.. _Algorithm Editor:
Manipulating an Algorithm
-------------------------
The Algorithm editor can be accessed via the "User Resources" tab on your BEAT
login page (click on "User Resources" and select "Algorithms" from the
drop-down list). On your Algorithms page you should see something similar to
the following:
.. image:: img/SS_algorithms_info.*
Note the search-box and the privacy-filter above the list of algorithms
displayed on the page. You can use these to limit your search. For example,
entering "anjos" in the search-box will allow you to list only those algorithms
that have the string "anjos" in the algorithm name. An example is shown in the
image below.
.. image:: img/SS_algorithms_anjos_search.*
There are several options when defining algorithms. They can be *Analyzer*, and *Splittable*.
*Analyzer* algorithms are special algorithms where the purpose is to generate
statistics about the processing results (graphs, means, variances, etc.).
Usually, biometric data processing algorithms are *Splittable*, indicating
to the platform that these algorithms can be executed in a distributed fashion,
depending on the available computing resources.
There are also two types of algorithms depending on the way they handle data samples that are fed to them. They can be *Sequential* or *Autonomous*. For more information see the "Algorithms" section of "Getting Started with BEAT" in `BEAT documentation`_.
There are two basic ways to create an algorithm at the |project| platform. You
may either start from scratch or fork a new copy of an existing algorithm and edit that.
Create an algorithm from scratch
================================
To create an algorithm from scratch, start by clicking the ''new'' button (green
button on the top-right corner on the Algorithms page).
You should see a web-page similar to what is displayed below:
.. image:: img/algorithm_new.*
For instructions on how to create an algorithm from scratch, please refer to the Section of `algorithm editor`_ and see the "Algorithms" section of "Getting Started with BEAT" in `BEAT documentation`_ to understand how to write the source code for new algorithms.
Edit an existing algorithm
==========================
In general, an existing algorithm that is already used in a toolchain cannot be edited.
However, a new copy can be created by forking an existing algorithm, and this copy can
be edited to create a new algorithm.
The advantage is that the forked algorithm provides reference templates
assisting user in creating the new algorithm. To fork an algorithm displayed in
the list of algorithms, click on the violet ''fork'' icon to the right of the algorithm name.
You should see a webpage similar to what is displayed below
.. image:: img/algorithm_fork.*
Please refer to the Section of :ref:`algorithm editor` for creating an algorithm.
New Version
-----------
You can update your existing algorithm by clicking a new version button.
Please refer to the Section of :ref:`algorithm editor` for creating an algorithm.
Editor
------
To create an algorithm, there are seven sections which are:
* Name: the name of algorithm.
* Algorithm option: Analyzer or Splittable.
* Algorithm type: Sequential or Autonomous.
* Language: The language used to implement the algorithm (Python or C++).
* Endpoints: Define the properties of the Input and Output endpoints for this algorithm.
* Parameters: Define the configuration-parameters for the algorithm.
When you have saved the algorithm you can add documentation that describes that algorithm as well.
For Python-based algorithms only:
* Libraries: If there are functions in a library, you can add them for the algorithm to use.
* Source code: The (Python) code implementing the algorithm.
You should see a webpage similar to what is displayed below:
.. image:: img/algorithm_editor.*
How to debug?
=============
Even though the |project| platform is an evaluation system (as opposed to a
development tool), porting algorithms to run on it may require some debugging,
specially for blocks with multiple input groups with different synchronization
channels. For that purpose, the standard output and error streams for each
block ran in an experiment are logged for later inspection through the
experiment view page (see our :ref:`Experiments` section). This include stack
traces of uncaught exceptions, but also any data printed by an algorithm or
associated libraries, on any of these streams.
You may take advantage of this to include ``print`` statements or similar in
your algorithm code, to help with your debugging.
.. warning::
To comply with data privacy requirements in our `terms of service`_, only the
very last 4 kilobytes of these streams is kept for user inspection.
processed data on its output(s). For detailed information see the "Algorithms" section
of "Getting Started with BEAT" in `BEAT documentation`_.
.. _binary algorithms:
......
......@@ -30,15 +30,16 @@
Data formats specify the transmitted data between the blocks of a toolchain.
They describe the format of the data blocks that circulate between algorithms
and formalize the interaction between algorithms and data sets, so they can
communicate in an orderly manner. For more detailed information see the "Dataformats" section of "Getting Started with BEAT" in `BEAT documentation`_.
communicate in an orderly manner. For more detailed information see the "Dataformats"
section of "Getting Started with BEAT" in `BEAT documentation`_.
.. note::
.. note::
Data formats are named using three values joined by a ``/`` (slash)
operator. The first value is the **username**.
The ``system`` user, provides a number of pre-defined formats such as
integers, booleans, floats and arrays (see `here <https://www.beat-eu.org/platform/dataformats/system/>`_). You may also
integers, booleans, floats and arrays (see `here <https://www.idiap.ch/software/beat/platform/dataformats/system/>`_). You may also
browse `publicly available data formats`_ to see all available data formats
from the ``system`` and other users.
......@@ -54,20 +55,17 @@ to that data format, like shown on the image below:
Editing Operations
------------------
Deleting a Data Format
----------------------
You may delete a data format that you created by just clicking on the
``Delete`` button and once deleted it cannot be restored. Notice that, if the
data format has been already used by any algorithm within the platform, it
cannot be deleted any longer.
From the data formats page, the user can ``Fork`` that particular data format,
creating a new data format with a different name or creating a new version of
that particular data format which would be the action to choose if the user
just want to make a small correction on that existing declaration. As with
algorithms, the user can also add an optional documentation with the data
format or change the sharing preferences for that particular object.
Sharing a Data Format
---------------------
As with other components within the platform, all the elements that are created
within the platform are private in nature, so this means that only the user
......@@ -100,5 +98,4 @@ the ``Sharing`` tab, on the relevant data format page.
more information on our :ref:`faq`).
.. include:: ../links.rst
......@@ -112,96 +112,34 @@ same toolchain, analyzer or database are shown:
.. image:: img/similar.*
.. _newexperiment:
Creating a new experiment
-------------------------
On the main Experiments page, new experiments can be created by clicking on the
``New`` button. You will immediately be prompted to select a ``Toolchain`` for
your new experiment. Once you have specified a toolchain, a page similar to
that in the image below will be displayed:
.. image:: img/new.*
The next step in constructing a new experiment is to defined an experiment name
and, finally, configure the contents of each and every block of the selected
toolchain:
* **Datasets**: choose the database, from among the existing databases
fulfilling the toolchain requirements, and then choose the protocol among
the ones available in the database. In this "simplified" configuration
mode, the platform chooses the contents of the input dataset blocks based
on preset configurations for particular databases and protocols. Use this
configuration mode for making sure you respect protocol usage for a given
database.
You may optionally click on ``Advanced`` to turn-on advanced dataset
selection mode, in which you can hand-pick the datasets to be used in each
dataset block. In this mode, you're responsible for selecting the
appropriate dataset for each relevant block of your toolchain. You can mix
and match as you like. For example, train using a particular dataset, test
using another one.
You may reset back to "simplified" selection mode by clicking on ``Reset``.
* **Blocks**: assign one algorithm to each block, such as image
pre-processing, classifier or similarity score function. If similar blocks
exist on the toolchain, selecting an algorithm for a block will make the
platform *suggest* the same algorithm for similar blocks. This mechanism is
in place to ease algorithm selection and avoid common mistakes. You may
override platform suggestions (marked in orange) at any moment by removing
the automatically assigned algorithm and choosing another one from the
list.
The user should make sure that the correct algorithm is selected for each
block. Configurable parameters, if provided by the selected algorithms, are
dynamically added to the ``Global Parameters`` panel, to the right of the
screen.
Use that panel to setup global values which are effective for all instances
of the same algorithm on the experiment. You may, optionally, override
global values locally, by clicking on the algorithm's arrow down icon and
selecting which values, from the global parameters, to override for that
particular block.
Among local override options, you'll also find a handle to change the
environment, queue or the used number of slots (if the algorithm is
splittable) on a per-block basis. Use these options to allow the algorithm
on a specific block to run on a special queue (e.g., that makes available
more memory), a special environment (e.g., with a different backend that
contains a specific library version you need) or with more slots.
* **Analyzer**: algorithm used to evaluate the performance and generate
results. Options for this block are similar for normal blocks.
.. note::
As mentioned in the "Experiments" section of "Getting Started with BEAT" in `BEAT documentation`_, BEAT checks that connected datasets, algorithms and
analyzers produce or consume data in the right format. It only presents
options which are *compatible* with adjacent blocks.
Tip: If you reach a situation where no algorithms are available for a given
block, reset the experiment and try again, making sure the algorithms you'd
like to pick have compatible inputs and outputs respecting the adjacent
blocks.
.. note:: **Queues and Environments**
For a better understanding of queues and environments, please consult our
dedicated :ref:`backend` section.
The complete toolchain for the ``Experiment`` can be viewed on the
``Toolchain`` tab (expanded view shown below):
.. image:: img/toolchain.*
After an ``Experiment`` has been set up completely, you can save the the
experiment in the |project| platform via the blue ``Save`` button or execute
it immediately by clicking the green ``Go!`` button.
Sharing an experiment
---------------------
As with other components within the platform, all the elements that are created
within the platform are private in nature, so this means that only the user
that creates them have access to the information concerning that particular
object. If you *Share* an experiment, it becomes accessible by the users of the
platform. You can read the sharing properties of an experiment by browsing to
the ``Sharing`` tab, on the relevant data format page.
.. note:: **Sharing status**
The sharing status of an experiment is represented to the left of its name,
in the format of an icon. A data format can be in one of these three
sharing states:
* **Private** (icon shows a single person): If an experiment is private,
only you can and only you can view its properties, run results, etc.
* **Shared** (icon shows many persons): If an experiment is shared, only
people on the sharing list can view its properties and run results.
* **Public** (icon shows the globe): If an experiment is public, then
users and platform visitors can view its properties, run results, etc.
Sharing at the |project| platform is an irreversible procedure. For example,
public objects cannot be made private again. If you share an object with a
user or team and change your mind, you can still delete the object, for as
long as it is not being used by you or another colleagues with access (see
more information on our :ref:`faq`).
.. include:: ../links.rst
......@@ -31,7 +31,8 @@ Libraries
functions. Instead of re-implementing every function from scratch, you can
reuse functions already implemented by other users and published in the form of
|project| libraries. Similarly, you can create and publish your own libraries
of functions that you consider may be useful to other users. For more information see the "Libraries" section of "Getting Started with BEAT" in `BEAT documentation`_.
of functions that you consider may be useful to other users. For more information see
the "Libraries" section of "Getting Started with BEAT" in `BEAT documentation`_.
Usage of libraries in encouraged in the |project| platform. Besides saving you
time and effort, this also promotes reproducibility in research.
......@@ -45,61 +46,15 @@ drop-down list. You should see a page similar to that shown below:
This page shows you all the libraries you have access to, on the platform. You
can use the Search-Box and the Privacy filters to limit your search to your
specific requirements. The page provides a ``New`` button to create a new
library. Note two items to the right of each library displayed on the page:
* a black circle showing how many experiments currently refer to this library,
and,
* a ``fork`` symbol that allows you to fork a new copy of the existing
library.
New libraries can be created either from scratch, or by editing the code from
existing libraries. Functions from libraries already used in at least one
experiment cannot be edited. However, the library may be forked, to create a
new version that can be edited. The |project| platform provides a `Library
Editor`_, to help with the creation of new libraries. There are several ways
of starting the library editor:
* click on the ``New`` button, to start creating a new library from scratch,
* click on the ``fork`` icon next to an existing library to create a new,
editable version of an existing library, or,
* click on the ``New Version`` button to start editing a new version of an
existing library.
.. _library editor:
Library Editor
--------------
When you start the ``Library Editor`` you will see a page similar to the
following:
.. image:: img/SS_libraries_editor.*
To create a library you will need to provide the following information:
* Name: enter the desired library-name in the text-box ``Name:``.
* Source code: add your (Python) code implementing the functions comprising
your library in the ``Source code:`` text-box.
Of course, functions implemented in a new library may also call functions from
other shared libraries in the |project| platform. You can indicate the
dependencies on other libraries via the ``External library usage`` section.
To save your work, click on the green ``Save`` button (in the top-right region
of the page). After you have saved your library, you will be able to use
functions from this library in your Algorithms code, and you will also be able
to share your library with other users.
specific requirements.
Sharing a library
-----------------
Like any other object in the |project| platform, you may also share your
library your library with other users. To do this, click on the green arrow in
the top right region on the page showing the library you want to share. (See
library with other users. To do this, click on the green arrow in the top right region
on the page showing the library you want to share. (See
image below.)
.. image:: img/SS_libraries_share0.*
......
......@@ -28,7 +28,8 @@
============
Toolchains are the backbone of experiments within the |project| platform. They
determine the data flow for experiments in the |project| platform. For more information about toolchains see the "Toolchains" section of "Getting Started with BEAT" in `BEAT documentation`_.
determine the data flow for experiments in the |project| platform. For more information
about toolchains see the "Toolchains" section of "Getting Started with BEAT" in `BEAT documentation`_.
The *Toolchains* tab
......@@ -62,6 +63,13 @@ And some more buttons if you own the toolchain:
has not been used in an experiment**).
Sharing a toolchain
-------------------
Like any other object in the |project| platform, you may also share your
toolchain your with other users. To do this, click on the green arrow in
the top right region on the page showing the toolchain you want to share.
.. note:: **Sharing status**
The sharing status of an toolchain is represented to the left of its name,
......@@ -85,60 +93,4 @@ And some more buttons if you own the toolchain:
more information on our :ref:`faq`).
Create a new toolchain
-----------------------
To create a new toolchain, you have to select the tab 'Toolchains' and then to
click on the button ``New``.
You should see a webpage similar to what is displayed below:
.. image:: img/new-toolchain.*
Then you have to type a name in the ``Name`` bar. Now you can create your
toolchain on the canvas. To do that, you have to select the different blocks
(dataset, block or analyzer) to the left of the canvas and to set them on the
canvas. On each block, you can modify the name by double-clicking on it, add
some inputs or outputs by clicking on the ``+`` and remove some inputs or
outputs by clicking on the ``-``. Finally, you have to link the different
blocks. To do that, you have to click on the output of a block and then to
click on the input of another block.
To delete a block or a link, you have to select it by left-clicking on it and
to use the keyboard key ``delete``. To undo the last operation, you can type
``Ctrl+z`` (``Cmd+z`` on a Mac) or click the undo and redo buttons on the top
bar of the editor. To move the canvas, you can:
* use the middle mouse button
* use the left mouse button with the ``Alt`` key
* use the mouse wheel
Whenever you want, you can save your toolchain by clicking on the ``save``
button (green floppy disk), located on the top bar of the editor.
.. _modifytoolchain:
Modify a toolchain
------------------
There exist three ways to modify an existing toolchain:
* Fork: to fork an existing toolchain and to modify it. You have to rename
the toolchain and its version number will be re-initialized to 1.
* Edit: to modify one of your toolchains which has no associated experiment.
The toolchain will keep the same name and the same version number.
* New version: to modify one of your toolchain which may have some
experiments. The toolchain will keep the same name and its version number
will be incremented.
To modify a toolchain, you have to open the ``Toolchains`` tab by clicking on
the ``Toolchains`` link, then to move your mouse over a toolchain and finally
to click on one of the three buttons ``Fork``, ``Edit`` or ``New version``.
Then an editor window is presented so you can modify your toolchain by deleting
and/or adding some blocks and/or connections. At the end, you have to save your
new toolchain by clicking on the ``save`` button (green floppy disk). If you
fork a toolchain, you have to give it a new name on the ``Name`` bar.
.. include:: ../links.rst
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