Commit b85d0099 authored by André Anjos's avatar André Anjos 💬

Merge branch 'docedit' into 'master'

merge the new documentation to master

See merge request !55
parents 1ca51ac9 70a72c76
Pipeline #25499 passed with stages
in 12 minutes and 27 seconds
......@@ -27,24 +27,22 @@ Configuration
-------------
The ``beat`` command-line utility can operate independently of any initial
configuration. By runnig for example the following command:
configuration. By runig for example the following command:
.. code-block:: sh
$ beat dataformats list --remote
By default, the ``beat`` application is pre-configured to access the `main BEAT
By default, ``beat`` is pre-configured to access the `main BEAT
website`_ anonymously, but it can be configured to use secret keys for any of
its users and/or access an alternative website installed somewhere else. This
allows users to push modified objects into the platform, completing the
development loop:
1. Pull objects of interest locally
2. Develop new objects based on existing ones or modify existing objects
3. Test locally, on an environment similar to the one available at the remote
platform
4. Push back modifications and then scale-up experiment running to explore more
databases and more parameter combinations
1. Pull objects of interest locally.
2. Develop new objects or modify existing ones.
3. Test locally, on an environment similar to the one available at the remote platform. (If the user wants to run the experiment locally without pushing it back to the platform they can use their own environment)
4. Push back modifications and then scale-up experiment running to explore more databases and more parameter combinations.
In order to properly configure a working prefix and memorize access options on
that directory, do the following from your shell:
......@@ -66,7 +64,7 @@ current working directory as your prefix. You can override this setting using th
.. code-block:: sh
$ ./bin/beat --prefix=/Users/myname/work/beat config show
$ beat --prefix=/Users/myname/work/beat config show
...
......@@ -121,8 +119,8 @@ like this:
Database Root Directories
=========================
When running an experiment via the ``beat`` application using the local
executor (the default executor, also behind the ``--local`` flag), ``beat``
When running an experiment in the BEAT ecosystem using the local
executor (the default executor, also behind the ``--local`` flag), ``beat``
will look into your configuration for any options set by the user that follow
the format ``database/<db name>/<db version>``. ``beat`` expects that this
option points to a string representing the path to the root folder of the
......@@ -137,7 +135,7 @@ Instead, you may override that path by setting the configuration option
``database/atnt/3`` to your local path to the database files.
Assuming your username is "user" and you extracted the database files to
``~/Downloads/atnt_db``, you can set ``database/atnt/3`` to
``/home/user/Downloads/atnt_db``, and ``beat`` will find the database files.
``/home/user/Downloads/atnt_db``, and BEAT will find the database files.
You may explore different configuration options with the ``--help`` flag of
``beat config``:
......
......@@ -45,9 +45,14 @@ be obtained by running the following command:
Creating a new database
=======================
To create a new database locally, create the necessary files (JSON declaration,
Python view and restructured text documentation) and place them on your prefix.
Once done, issue the following sequence of commands to upload it to the server:
To create a new database locally, create the necessary files (see `database view python`_) and place them on your prefix.
Once done, use the following command to index the database:
.. code-block:: sh
$ beat database index <db>/1
and if you wan to upload it to the web server issue the following command:
.. code-block:: sh
......@@ -91,3 +96,9 @@ Replace the string ``<db>`` with the name of your database. For example,
``mynewdatabase``. Replace ``<platform>`` by the address of the BEAT platform
you're trying to interact with. Replace ``<your-token>`` by your user token
(you can get that information via your settings window on the platform itself).
.. note::
At the moment only users with administrative privilege can push databases to the web serve however all users can create and modify databases locally.
.. include:: links.rst
......@@ -29,14 +29,14 @@ Experiments
The BEAT command-line utility called ``beat`` can perform a variety of actions
concerning experiments. These actions are grouped in two sets:
* local: Local actions allow the user to act on locally installed objects
* remote: Actions on the remote web platform
* local: Local actions allow the user to act on locally installed objects.
* remote: Actions on the remote web server.
Once you have setup your prefix directory as explained in
:ref:`beat-cmdline-configuration`, you're ready to start configuring new
experiments.
The commands available for experiments are:
The commands available for the experiments are:
.. command-output:: beat experiments --help
......@@ -66,7 +66,7 @@ a simple environment with PDB support without advanced features
Here, the ``--prefix`` option is used to tell the scripts where all our data
formats, toolchains and algorithms are located. This option can be set
in your configuration file (see ``beat config``).
in your configuration file (see :ref:`beat-cmdline-configuration`).
This command displays for each block the files containing the data to use as
input, and the files generated by the outputs of the block.
......@@ -80,10 +80,9 @@ Executors
"Executors" are modules that execute each block in an experiment. On the BEAT
platform, there is only the one executor, which executes the experiment using
Docker containers with advanced scheduling and security features. When
developing using ``beat.cmdline``, however, you have the option of using either
the BEAT platform's executor, behind the ``--docker`` flag, or the "local"
executor, provided in this project. The local executor, as explained above, is
Docker containers with advanced scheduling and security features. When using ``beat.cmdline`` locally, however, you have the option of using either
the BEAT platform's executor, behind the ``--docker`` flag (for more information about using docker executors (see `here <https://www.idiap.ch/software/beat/docs/beat/docs/master/beat.core/doc/develop.html>`_), or the "local"
executor (refer to `BEAT installation`_ for information about local environment). The local executor, is
much simpler, aimed at providing a smooth development experience. However,
there are two important tradeoffs:
......@@ -93,13 +92,6 @@ there are two important tradeoffs:
``beat.cmdline`` is used. This means that many BEAT experiments that
rely on different/multiple environments will not work.
If you want to use the local executor, pay attention to the python environment
used to call `buildout` in your copy of ``beat.cmdline``. The suggested way
to use Bob libraries while developing on the local executor is to use install
``zc.buildout`` in a Python2.7 conda environment with Bob installed. Using
the ``buildout`` command from the environment will make the entire environment
available to ``beat.cmdline`` even when the environment is not active.
.. _beat-cmdline-experiments-displaydata:
......@@ -113,7 +105,7 @@ The ``beat cache`` collection of commands interact with the cache:
How to plot output images from experiments?
...........................................
The command ``beat experiments plot <name>`` can be used to plot output images
The command ``beat experiments plot <experiment name>`` can be used to plot output images
for the various experiments.
There a two ways to plot data:
......@@ -122,14 +114,16 @@ There a two ways to plot data:
.. code-block:: sh
$ beat experiments plot --remote experimentname
$ beat experiments plot --remote <experiment name>
* using data from the cache of locally ran experiments
.. code-block:: sh
$ beat experiments plot experimentname
$ beat experiments plot <experiment name>
In both cases the 'outputfolder' option can be specified to save all the plots to a specific directory. By default, if nothing was specified, the plots will be saved under the experiment path.
In both cases the 'output folder' option can be specified to save all the plots to a specific directory. By default, if nothing was specified, the plots will be saved under the experiment path.
Take into account that some extra options are available such as '--show' which will pop out the generated plots on your screen.
.. include:: links.rst
......@@ -46,7 +46,6 @@ implement more advanced functionality than this client (``beat``) provides.
databases
plotters
plotterparameters
walkthrough
api
......
......@@ -20,49 +20,25 @@
.. You should have received a copy of the GNU Affero Public License along ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/. ..
.. _beat-core-introduction:
Introduction
============
The user objects (data formats, toolchains, experiments, etc) are stored
locally in a directory with specific structure that is commonly referred to as
a **prefix** (see `Prefix`_). The user objects on the web platform are
also stored in a similar directory structure. It is possible to extract a
representation from the objects on the BEAT web server and interact with them
locally. Local object copies contain the same amount of information that is
displayed through the web interface.
The BEAT command-line utility can be used for simple functionalities (e.g.
deleting an existing algorithm or making small modifications) or advanced
tasks (e.g. database development, experiment debugging) both for local objects
and remote objects. In order to make this possible for the remote objects, the
web platform provides a RESTful API which third-party applications can use to
list, query and modify existing remote objects.
Even though user objects (data formats, toolchains, experiments, etc) are
stored on a remote BEAT web server, it is possible to extract a representation
from such a website and, in a limited way, interact with such objects locally.
This functionality may be useful for simple (e.g. deleting an existing
algorithm on the platform or making small modifications) or advanced tasks
(e.g. database development, experiment debugging). In order to make this
possible, the web platform provides a RESTful API which third-party
applications can use to list, query and modify existing remote objects. Local
object copies contain the same amount of information that is displayed through
the web interface, and are stored following a precise directory organization.
The root of the 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,
so as to store objects which are downloaded from the web server. This is the
typical directory structure in a prefix directory:
.. 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 platform. 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.
The ``beat`` command-line utility bridges user interaction with a remote BEAT
web platform and locally available objects in a seamless way:
......@@ -70,8 +46,10 @@ web platform and locally available objects in a seamless way:
.. command-output:: beat --help
The command-line interface is separated in subcommands, for acting on specific
objects in the platform. Actions can be driven to operate on locally installed
objects. Actions can be driven to operate on locally installed
or remotely available objects. You'll find detailed information about
sub-commands on specific sub-sections of this documentation dedicated to that
particular type of object. In this section, we cover basic usage and
particular type of object. In :ref:`beat-cmdline-configuration`, we cover basic usage and
configuration only.
.. include:: links.rst
.. _main beat website: https://wwww.beat-eu.org/platform
.. _main beat website: https://www.beat-eu.org/platform/
.. _database view python: https://www.idiap.ch/software/beat/docs/beat/docs/master/beat/databases.html#database-view
.. _Prefix: https://www.idiap.ch/software/beat/docs/beat/docs/master/beat/user.html#the-prefix
.. _BEAT installation: https://www.idiap.ch/software/beat/docs/beat/docs/master/beat/install.html
\ No newline at end of file
.. vim: set fileencoding=utf-8 :
.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/ ..
.. Contact: beat.support@idiap.ch ..
.. ..
.. This file is part of the beat.cmdline module of the BEAT platform. ..
.. ..
.. Commercial License Usage ..
.. Licensees holding valid commercial BEAT licenses may use this file in ..
.. accordance with the terms contained in a written agreement between you ..
.. and Idiap. For further information contact tto@idiap.ch ..
.. ..
.. Alternatively, this file may be used under the terms of the GNU Affero ..
.. Public License version 3 as published by the Free Software and appearing ..
.. in the file LICENSE.AGPL included in the packaging of this file. ..
.. The BEAT platform is distributed in the hope that it will be useful, but ..
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
.. or FITNESS FOR A PARTICULAR PURPOSE. ..
.. ..
.. You should have received a copy of the GNU Affero Public License along ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/. ..
.. _beat-cmdline-walkthrough:
Walkthrough
-----------
This page gives an overview on setting up an environment to develop BEAT
experiments locally. The topics covered are the following:
- Preparing a proper Python environment
- Bootstrapping ``beat.cmdline``
- Running the `BEAT web platform <https://gitlab.idiap.ch/beat/beat.web>`_
locally
- Detailing an example workflow for BEAT development
Tips for preparing a proper environment
.......................................
- Using a `Conda <https://conda.io/docs/>`_ environment is recommended.
- ``beat.cmdline`` requires Python 2.7 and will not work on Python 3.x.
- It uses `Buildout <http://www.buildout.org/en/latest/>`_, to bootstrap,
commonly known as `zc.buildout`. This package is also available on Conda.
- The Python 2.7 environment used for bootstrapping will also be the
environment used to execute BEAT code when using the local executor.
- While you can bootstrap and use ``beat.cmdline`` without having a local
BEAT instance, ``beat`` can't yet create BEAT objects (experiments, etc.)
from scratch. We recommend you instead modify existing BEAT objects.
- Running experiments using the Docker executor requires Docker to be
set up locally and several docker containers.
Boostrapping ``beat.cmdline``
.............................
Thanks to Buildout, setup is simple:
- Clone the ``beat.cmdline`` repository.
- Using a compatible environment (see above) run ``buildout`` in the project's
root directory. Assuming this step is successful, the ``beat`` tool is now
functional.
- To build this documentation locally, use the ``sphinx-build`` tool in
``bin/``: ``./bin/sphinx-build doc/ sphinx/`` to output to ``sphinx/``.
Running the BEAT Platform locally
.................................
- Build
`the BEAT web environment <https://gitlab.idiap.ch/beat/beat.env.web>`_
locally.
- Build ``beat.web`` using the Python environment built from ``beat.env.web``.
- Install the example environment in ``beat.web`` via ``./bin/django install``.
- Run ``./bin/django runserver`` and go to ``localhost:8000/`` to see if it
works. The default example login is ``user`` with password ``user``.
An example workflow
...................
First, have ``beat.web`` running locally. To interact with the local instance
through ``beat.cmdline``, set the ``platform`` config option through ``beat``
to ``http://localhost:8000/``: ``beat set platform 'http://localhost:8080/'``.
Pull example experiments from the platform via the ``beat`` tool:
``beat exp pull user/single/1``. Run the example experiment using the
local executor: ``beat exp run user/single/1/single`` to make sure one works.
Fork the ``single`` experiment, using the same ``user/single/1`` toolchain:
``beat exp fork user/single/1/single user/single/1/single_test``.
Run the new experiment to make sure the fork works:
``beat exp run user/single/1/single_test``.
Feel free to edit the ``single_test`` JSON file to change the experiment.
Likewise, you can fork other BEAT objects (algorithms, databases, toolchains,
etc.).
To see if your new BEAT objects will run on the BEAT platform, try to run
using the Docker executor (which will use the BEAT docker images it can find):
``beat exp run --docker user/single/1/single_test``.
If it works, you can push it to your BEAT platform to have it on your BEAT
platform instance: ``beat exp push``.
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