.. 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/. .. .. _searchlabel: ======== Search ======== When you first interact with the |project| platform, it is very likely you'd start by searching existing results from experiments already shared with you. This guide explains how to perform searches based on the criteria of your choosing and store filtering criteria, so it is easy to repeat the search at any point in the future. Starting a search for experiment results ---------------------------------------- You can use the omni-search bar or strategically placed buttons at the |project| platform to search and compare results of experiments that have successfully finished. You may save search criteria so it is easy to re-run search terms and created your own leader boards following the topic of your interest. There are two basic ways to start a new search at the |project| platform. You may either type a search for experiment results using the omni-bar, present at the top of each displayed page or using strategically placed buttons with predefined search criteria. Search from the omni-bar ======================== To search from the omni-bar, type any search criteria. For example, try to search for results containing the term ``eigenfaces``, by typing on the omni-bar:: eigenfaces You should see a webpage similar to what is displayed below: .. image:: img/eigenface-results.* Searching at the |project| platform uses filters which are similar in nature to those you have for filtering e-mails on your mail reader. The more you add filters, the more specific the search is. Please refer to the Section `search-filters`_. Predefined search terms ======================= You may also start a search from one of the existing preset buttons available at the platform. These buttons only trigger a search with predefined search terms based on the current start position. For example: 1. You may start a search from an experiment view page, by clicking on the button entitled `Similar experiments`. This triggers a search with the following predefined criteria: * Experiments that were done using the same toolchain as that experiment, AND * Experiments that were analyzed with the same analyzer algorithm, AND * Experiments that used the same input database 2. You may start a search from a toolchain view page, by clicking on the button entitled `Search experiments`. This triggers a search for all experiments using the said toolchain. 3. You may also start a search from an algorithm view page, by clicking on the button entitled `Search experiments`. This triggers a search for all experiments using the said algorithm. 4. Finally, you may also start a search from a database view page, by clicking either on the `Search experiments` in the database view (triggers a search for all experiments using that database) or individual protocol buttons which are similarly purposed. Clicking on protocol buttons narrows the search for experiments using the specific protocol of a given database. .. _search-filters: Search Filters ============== Searching for a specific set of experiments can be accomplished by either narrowing or broadening search terms. Narrowing your search ~~~~~~~~~~~~~~~~~~~~~ In order to narrow your search (i.e., apply logical AND rules), add more search terms by clicking on the ``+`` buttons on the Filters panel. If you change your mind, you can broaden your search back again by clicking on the ``-`` buttons. Each filter can be configured to narrow your search in a specific way. Currently available filters are: * Database names: the name of a particular database, e.g. `mobio` or `mobio/1` (including the database version number); * Protocols: the name of a protocol, e.g. `idiap_eyepos`; * Algorithms: the name of an algorithm, e.g. `tutorial/pca/2`; * Analyzers: the name of an analysis algorithm (i.e., use in the last block of a toolchain), e.g. `tutorial/postperf_iso/1`; * Experiments: the name of an experiment * Experiment authors: the username for the author of an experiment; * Experiment dates: allows you to narrow your search to experiments executed in a given date or date range. E.g. all experiments execute before October 1st. 2015; * Experiment results: narrows your search by looking to experimental results that can be set to be greater or smaller than a threshold; * Toolchains: the name of a toolchain, e.g. `tutorial/eigenface/1`; * Toolchain authors: the username of a toolchain, e.g. `tutorial`. After selecting a filter type, the interface will change to accomodate specific options for that particular field type. For example, comparing experiment dates require you can input thresholds whereas data names don't. When inputing object names, it is possible to specify a precise match (use ``is``) or relative (use ``contains``), which allows users to adjust filters to specific needs. Broadening your search ~~~~~~~~~~~~~~~~~~~~~~ You may broaden your search by either removing search filters or by adding more terms to a given search filter. For example, if you set the filter to `Database names` `that contain` `atnt,mobio` (**separated by comma**), it indicates to the platform you want to perform a search for all experiments using either the database named `atnt` or the database named `mobio`. Comparing results ~~~~~~~~~~~~~~~~~ The |project| platform allows you to compare results of experiments together creating tables and aggregated plots. The only requirement which is imposed by the platform is: .. important:: Experiments can only be compared if they use the same analyzer algorithm. This requirements simplifies the comparison machinery and is enforced by the search application. If the search criteria is such that experiments can't be compared, you'll be warned in a visible manner, such as displayed in the figure below: .. image:: img/impossible-to-compare.* In these cases, make sure to narrow your search by selecting the appropriate analyzer from the list of available filter options. Once that is done, the displayed table should now show you the relevant result information: .. image:: img/simple-comparison.* The experiment results are compared by certain pre-defined criteria such as `eer` (these are outputs of the analyzer). You can add or remove these criteria by clicking on the criteria bar available on the top-right of the table. Some of the options refer to plots, in which case the display will refresh to show you the plot(s) for the selected experiments. For example: .. image:: img/example-search-plot.* You may also click on any of the columns displayed to order the experiments by the information displayed on that column. This allows you to set up your own leader board with the information of your interest taking into consideration all experiments available at the platform. Search for other resources -------------------------- You can also search for specific resources such as toolchains, algorithms, and etc. by going to their respected page from your homepage and using the search bar that becomes available. For example, to search for a specific `Algorithm`, go to your homepage and find the `Algorithms` tab under the `User Resources` tab and use the search bar that is available under the `Algorithms` tab. You can also narrow your search by using the `Privacy` filter that is available next to the search bar. Saving your Search ------------------ The |project| platform allows you to save your search filters, ordering and display options (plots, table columns), so that you can easily repeat the search in the future. To save your search, you **must** be logged in with your user account. If so, a button saying ``Save`` will be displayed under your search filters. Click on this button and set a name for your new setup. All saved searches are available for re-execution at the `Searches` tab available through your home page, under the ``User Resources`` tab. .. note:: **Naming Convention** Stored searches are named using two values joined by a ``/`` (slash) operator: * **username**: indicates the author of the search * **name**: an identifier for the object Each tuple of these two components defines a *unique* name inside the platform. For a grasp, you may browse `publicly available stored searches `_. You may add a documentation string to your saved search and share it like any other component at the platform. Changing the Search documentation --------------------------------- In order to add or change the documentation associated to a search, click on the button `Add` in the `Documentation` part, situated under the search title, at the search view page. The box shown below will be displayed: .. image:: img/doc.* You may fill in a short description, that will be displayed at the search page and a longer one, in restructured text format. Use the editor and the links displayed to retrieve more information. Click on the `Save` button to save your documentation or the `Cancel` button to cancel the add/change operation. You may change the documentation of objects at the |project| platform at any time. Sharing a Search ---------------- Like any other object in the |project| platform, your searches may also be shared with other people. This may be a great way to engage a community in a challenge for example. In order to share your search, while on the search list display, click on the button entitled `Share`. When you click this button, you will be redirected to the `Sharing` tab in the search page. Click on `Edit` and a pop-up window will appear allowing you to type in the usernames of affected users and teams you want to share your contribution with, like on the image below: .. image:: img/share.* You may optionally select to share the search with any platform users and anonymous visitors by clicking on the checkbox `Public`. In this case, the fields for authorized users and teams are automatically disabled. Sharing at the platform is an irreversible procedure. You can only additively share contributions. You cannot unshare once share is performed. You may cancel the operation by clicking on the `Cancel` button. Deleting a Search ----------------- You may delete searches at any time through the search listing page. Just click on the button `Delete` to delete the stored search. Once deleted, the search cannot be restored. You may re-create the search again as explained in this guide.