.. _beat-system-plotters:

==========
 Plotters
==========

The plotters are the building blocks of BEAT that provide the visualization for the output result of BEAT experiments, such as bar plots or ROC curves. 



.. _beat-system-plotters-definition:

Definition of a Plotter
=======================
A plotter just like other building blocks of BEAT consists of two main components:

* a `JSON`_ object with several fields, specifying the inputs, the produced figure, the parameters and additional information such as the language in which it is implemented.
* source code describing how to produce the desired figure using the given parameters. They are mostly implemented in python and use matplotlib library. 

.. _beat-system-plotters-definition-json:

JSON Declaration
----------------
The `JSON`_ declaration of plotters consists of several field. Here is an example of a plotter that produces bar plots:

.. code-block:: javascript

	{
	    "dataformat": "plot/bar/1",
	    "description": "Basic bar plotter for simple histograms",
	    "language": "python",
	    "parameters": {
	        "axis-fontsize": {
	            "default": 10,
	            "description": "Controls the axis font size (labels and values)",
	            "type": "uint16"
	        },
	        "bar-norm": {
	            "default": true,
	            "description": "If set to true will normalize the distribution between 0-1",
	            "type": "bool"
        	},
	        ...
	    },
	    "uses": {
	        "baselib": "plot/baselib/1"
	    }
	}

Here are the description for each of the fields in the example above:

* **dataformat** is the specific dataformat in the input of a plotter. 

* **description** gives a small description of the plotter.

* **language** is the language in which the source code is implemented.

* **parameters** are the given parameters to the source code to produce the figure. These parameters can be manipulated by the :ref:`beat-system-plotterparameters`. Default values for some of the parameters can be defined in a separate text file in the same directory as the `JSON`_ file. This text file has key/value format similar to a `JSON`_ file.

* **uses** are the libraries used by the plotter.


The graphical interface of BEAT provides user-friendly editors to configure the `JSON`_ declaration definition of plotters when using BEAT locally. At the moment, defining new plotters on the platform is possible only under administrative privilege.

.. _beat-system-plotters-types:

Plotter Types and Dataformats
-----------------------------
At the moment there are three different types of plotters provided by BEAT platform; bar plots, ROC/DET plots, and scatter plots. However users can make their own plotters when using BEAT locally.  

Each plotter accepts only a specific type of dataformat in their input. For example a **bar** plot only accepts ``plot/bar/1`` dataformat. Here is the `JSON`_  declaration for this dataformat. 

.. code-block:: json

	{
	    "#description": "Array of bar plots",
	    "data": [
	        0,
	        {
	            "label": "string",
	            "x": [
	                0,
	                "float64"
	            ],
	            "y": [
	                0,
	                "float64"
	            ]
	        }
	    ]
	}

and the **scatter** plot only accepts ``plot/scatter/1`` dataformat which has the following `JSON`_ declaration:

.. code-block:: json

	{
	    "#description": "A set of 2-D scatter plots with X/Y and a label",
	    "data": [
	        0,
	        {
	            "label": "string",
	            "x": [
	                0,
	                "float64"
	            ],
	            "y": [
	                0,
	                "float64"
	            ]
	        }
	    ]
	}

.. include:: links.rst