plotters.rst 3.68 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
.. _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:

26
.. code-block:: javascript
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115

	{
	    "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