.. 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.web 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/.          ..


.. _libraries:

=========
Libraries
=========

|project| supports libraries that can be used to organize commonly used
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`_.

Usage of libraries in encouraged in the |project| platform. Besides saving you
time and effort, this also promotes reproducibility in research.

You can access the Libraries section from your home-page on |project| by
clicking the ``User Resources`` tab and selecting ``Libraries`` from the
drop-down list.  You should see a page similar to that shown below:

.. image:: img/SS_libraries_main.*


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.


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
image below.)

.. image:: img/SS_libraries_share0.*


Clicking on the green (sharing) arrow, will present you a page similar to the
following:

.. image:: img/SS_libraries_share1.*


As you see on this page, by default your library is ``Private`` and not shared
with other users. To change the sharing-properties of your library, click on
the blue ``Edit`` button on the right side of the page (see picture above).
This will show you the following page, with options you can select for sharing
your library:

.. image:: img/SS_libraries_share2.*


You can select one of three levels of sharing:

  * Public: every user of the platform is allowed to use your library
  * Shared: you decide to share it only with certain users or teams (the names
    of users and teams can be explicitly specified in the respective text-boxes
    below)
  * Usable: specific users and teams are allowed to use the library but not to
    fork it.

The sharing operation may be cancelled by clicking on the ``Cancel`` button.


.. note:: **Sharing status**

   The sharing status of an library is represented to the left of its name,
   in the format of an icon. A library can be in one of these four sharing
   states:

     * **Private** (icon shows a single person): If a library is private,
       only you can use it on your algorithms and only you can view its source
       code.
     * **Usable** (icon shows a cog): If a library is usable, only you can
       view its source code. People on a sharing list can use the library as
       a *black-box* (i.e. without looking at the source code) on their
       algorithms (and, of course, provided you documented well its API). If
       there is no one on the sharing list, then everyone can use the library.
     * **Shared** (icon shows many persons): If a library is shared, only
       people on the sharing list can use the library and view its source code.
     * **Public** (icon shows the globe): If a library is public, then users
       and platform visitors can view the source code of the library. All
       platform users can use the library on their algorithms.

   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`).


Deleting a Library
------------------

To delete an existing library, click on the red cross in the top right region.
If a library is already being used in any experiment, the experiment should
first be deleted, before the library can be deleted. Once deleted, your library
cannot be restored.

.. include:: ../links.rst