.. _`Bokeh Figure`:

.. _`org.sysess.sympathy.visualize.bokehfigure`:

Bokeh Figure
````````````

.. image:: figure.svg
   :width: 48


Create a Bokeh Figure from some data.




Documentation
:::::::::::::

The tree view
=============
This configuration view consists of a tree view containing all the
parts of your figure. To add plots to the figure, you can either click on
its corresponding button in the toolbar, or press on a plot button and
dragging it to where in the tree view you want it (possible drop locations
will be shown in green). The plot will be added with some basic properties
depending on which plot type you added (e.g. *X Data* and *Y Data* for line
plot). Almost all configuration items support more than the default
properties. To add more, right-click on a configuration item and choose
"Add...".

Plot types
==========
There are many types of plots available in the Figure node. Here follows a
short word about some of the more common ones.

Scatter plots and line plots
----------------------------
These plot types are mostly pretty self-explanatory. The main difference
between these is while a *Line plot* can have marker, a *Scatter plot* can
not have lines. The *Scatter plot* can on the other hand have a different
size and color for each marker, whereas *Line plot* can only have a single
color and size for all markers.



Multiple axes
=============
There is support in the node for having an extra x or y axis. This
can for example be useful if you want to have two different y ranges for
two line plots. To get two y axes first add an extra *Axes* item to the
configuration tree. In the new *Axes*, you should set the *position* of the
*YAxis* to 'right'. Lastly add one or more plots to each *Axes*.

Legends
=======
To get a legend you must both set labels on all plots that you want to
include in the legend and also add a *Legend* item. Note that some plot
types have other configuration items called things like *Bin Labels* or
*Bar Labels*, but those are not used for the legend. Instead, look for a
property called simply *Label* or *Labels*.

To get a single legend which summarizes all signals across multiple *Axes*
you need to add the *Legend* to the root of the configuration tree, i.e.
next to the *Axes* items.



Iterators
=========
An *Iterator* can be used to create a dynamic number of plots in a single
figure. The iterator can only contain a single plot, but that plot will
then be repeated depending on the *Iterable*. For example if the data is a
Table and the *Iterable* is ``col_name = arg.column_names()`` then
``col_name`` will take on all the column names in the Table and can be used
in e.g. *Y Data* as such: ``arg[col_name]``.

Python expressions as values
============================
To allow the user extra flexibility, all properties can be given either as
a normal value or as a python expression which evaluates to a value for
that configuration item. To switch to Python mode click the grayed out
Python icon to the right of the normal input field. Note that some fields
can only be entered as Python expressions (notably fields like *X Data* and
*Y Data* for e.g. line plots).

In the python evironment the input data port is available under the name
``arg``. For example one can refer to data columns in a connected Table by
writing something like ``arg['My data column']``. Have a look at the
:ref:`datatypeapis` to see all the available methods and attributes for the
data type that you connect to the node.

Related nodes
=============

This node can not create subplots, but by creating multiple figure objects
you can use the node
:ref:`org.sysess.sympathy.visualize.bokehfiguresubplot` to arrange them as
subplots.

Use the node :ref:`org.sysess.sympathy.export.exportbokehfigures` to write
the figures you produce to files.

For creating non-interactive figures using the matplotlib backend see
:ref:`org.sysess.sympathy.visualize.figure`.


Definition
::::::::::


Input ports
===========

    **input**  <a>
        Input


Output ports
============

    **figure**  bokeh
        Output figure




Configuration
=============

    **(no label)** (parameters)
        The full configuration for this figure.





Related nodes
=============

* :ref:`org.sysess.sympathy.visualize.bokehfiguresubplot`

* :ref:`org.sysess.sympathy.export.exportbokehfigures`

* :ref:`org.sysess.sympathy.visualize.figure`






Implementation
==============

.. automodule:: node_bokeh_figure
    :noindex:

.. class:: BokehFigure
    :noindex: