Commit 89a23257 authored by André Anjos's avatar André Anjos 💬

Suggestions (AA+ZM)

parent 6b00edcd
Pipeline #24702 passed with stages
in 7 minutes and 30 seconds
......@@ -27,8 +27,9 @@
BEAT
======
Let's start learning BEAT!
This guide contains installation instructions, a general introduction to core
components of the BEAT framework and a brief tutorial that examplifies how to
build and execute a complete experiment locally.
.. toctree::
......
......@@ -7,9 +7,9 @@
Installation Instructions
===========================
The BEAT is available as conda packages for linux and MacOS for locall usage.
The BEAT framework is distributed as conda packages for Linux and MacOS.
#. Please install `conda`_ (miniconda is preferred) and get familiar with it.
#. Install `conda`_ (miniconda is preferred) and get familiar with it.
#. Make sure you have an up-to-date `conda`_ installation (conda 4.4 and above
is needed) with the **correct configuration** by running the commands
below:
......@@ -23,29 +23,26 @@ The BEAT is available as conda packages for linux and MacOS for locall usage.
.. code:: sh
$ conda create --name beat_py3 --override-channels \
-c https://www.idiap.ch/software/beat/conda -c defaults \
python=3
$ conda activate beat_py3
$ conda create --name beat --override-channels -c https://www.idiap.ch/software/beat/conda -c defaults python=3
$ conda activate beat
$ conda config --env --add channels defaults
$ conda config --env --add channels https://www.idiap.ch/software/bob/conda
$ conda config --env --add channels https://www.idiap.ch/software/beat/conda/label/beta
$ conda install beat.core beat.cmdline beat.backend.python beat.editor
$ conda config --env --add channels https://www.idiap.ch/software/beat/conda
$ conda install beat.editor
#. Install other packages that you need in that environement:
.. code:: sh
$ conda install bob.ip.base bob.db.atnt ..
#. The BEAT commands, ``beat`` and ``beat editor serve``, should be available.
#. Install other packages that you may need in this environment if you're
running local tests. For example:
**Repeat the last three steps for every conda environment that you create for
BEAT.**
.. code:: sh
$ conda install tensorflow opencv ...
#. The commands, ``beat`` and ``beat editor serve``, should be available.
.. include:: links.rst
.. tip::
Repeat the last three steps for every conda environment that you create
including BEAT components.
.. include:: links.rst
......@@ -26,15 +26,16 @@
===========================
Getting Started with BEAT
===========================
The Beat system has certain building blocks used by all the packages in the BEAT
software suite. These are:
The BEAT framework describes experiments through fundamental building blocks
(object types):
* **Data formats**: the specification of data which is transmitted between
blocks of a toolchain;
* **Libraries**: routines (source-code or binaries) that can be incorporated
into other libraries or user code on algorithms;
* **Algorithms**: the program (source-code or binaries) that defines the user
algorithm to be run within the blocks of a toolchain;
* **Libraries**: routines (source-code or binaries) that can be incorporated
into other libraries or user code on algorithms;
* **Databases** and **Datasets**: means to read raw-data from a disk and feed
into a toolchain, respecting a certain usage protocol;
* **Toolchain**: the definition of the data flow in an experiment;
......@@ -42,8 +43,9 @@ 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`
Instances of these building blocks are represented in JSON_ using a specific
schema. Multiple objects can be stored on disk as files following a directory
structure.
.. _beat-system-example:
......@@ -175,11 +177,11 @@ objects in the platform. In the example above, you can identify some examples.
The BEAT platform provides a graphical user interface so that you can program
data formats, algorithms, toolchains and define experiments rather intuitively.
data formats, algorithms, toolchains and define experiments rather intuitively.
For expert users, we provide a command-line interface to the platform, allowing
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.
editors. When using BEAT locally the graphical user interface is used in parallel
with the command-line interface.
BEAT Building Blocks
====================
......
.. _tutorial:
* 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`
=====================
A Hands-On Tutorial
......@@ -55,7 +64,7 @@ The prefix is a folder that holds all of your BEAT object data in a certain form
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
......@@ -258,10 +267,10 @@ There is a subfolder in your prefix called ``cache``. This folder holds all the
* You may re-run an experiment and immediately get its results, since all of the experiment's steps are found in the cache.
* Changing a block in an experiment (whether its a source code file or metadata) will re-run that step and every step that depends on it.
* Changing a database means that all experiments ran using that database cannot use any of their caches.
* Changing a database means that all experiments ran using that database cannot use any of their caches.
* Changing an analyzer of an experiment means that only the last step will have to be re-ran.
.. note:: Please note that the root folder of the database is not a part of information used for producing the hash of the database block. Therefore if the only modification in a database block is changing its root folder, BEAT will use the previous cach data available. You need to clear the cache manually to make sure that the new root folder is accessable by beat. for more information about the data used for making the hashes of each block please refer to the `hash.py <https://gitlab.idiap.ch/beat/beat.core/blob/master/beat/core/hash.py>`_ from beat.core.
.. note:: Please note that the root folder of the database is not a part of information used for producing the hash of the database block. Therefore if the only modification in a database block is changing its root folder, BEAT will use the previous cach data available. You need to clear the cache manually to make sure that the new root folder is accessable by beat. for more information about the data used for making the hashes of each block please refer to the `hash.py <https://gitlab.idiap.ch/beat/beat.core/blob/master/beat/core/hash.py>`_ from beat.core.
......
......@@ -4,33 +4,19 @@
BEAT
======
BEAT is a system for computing and certifying results for
BEAT is a framework for the definition, execution and comparison of
software-based data-driven workflows that can be sub-divided functionally (into
processing blocks). The user provides the
description of data formats, algorithms, data flows (also known as toolchains)
and experimental details (parameters), which are used to
produce beautiful results, easily exportable into computer graphics or tables
for scientific reports.
processing blocks). The user provides the description of data exchange
formats, algorithms, data flows (also known as toolchains) and experimental
details (parameters). The framework can execute the experiment locally or in a
computing infrastructure transparently. Results can be shared and compared
via traditional exchange mechanisms or by using a web-based platform.
BEAT can be easily installed and used locally (see :ref:`beat_editor`). It can
also be used on a web based platform that lets the user leverage from the benefit
of higher computation power as well as interacting with other teams and projects (see :ref:`beat_web_user`).
The platform takes all burden of hosting data and software
away from users by providing a capable computing farm that handles both aspects
graciously. Data is kept sequestered inside the platform.
The BEAT is intended as a fundamental building-block in `Reproducible Research`_,
allowing academic and industrial parties to prescribe system behavior and have
it reproducible through software, hardware and staff generations. Here are some
known applications:
* Challenges and competitions on defined data, protocols and workflow
components;
* Study group exercises and exams;
* Support to publication submission;
* System and algorithm performance optimization;
* Reproduction of experiments through communities;
* Support for industry-academy relationship.
The BEAT framework is intended as a fundamental building-block in `Reproducible
Research`_, allowing academic and industrial parties to describe and exchange
system behavior. The web-platform takes all burden of hosting data and
software away from users by providing a capable computing farm that handles
both aspects transparently. Data privacy is guaranteed inside the platform.
Start here
......@@ -62,4 +48,4 @@ Index of all Packages
beat.web <beat.web/doc/index.rst>
readme_index.rst
.. include:: links.rst
\ No newline at end of file
.. 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