.. _ug_intro:

Introduction
============

.. _ug_glossary:

Glossary
--------

These are the most important concepts and terms that you will encounter
throughout Bokeh's documentation:

.. glossary::

    Annotation
        Visual aids that make reading the plot easier. This includes titles,
        legends, labels, or bands, for example. See :ref:`ug_basic_annotations`
        in the |user guide| for more information and examples.

    Application
        A Bokeh application is a recipe for generating Bokeh
        :term:`documents<Document>`. Typically, this is Python code run by a
        Bokeh :term:`server<Server>` whenever a new sessions is created.

    BokehJS
        The JavaScript client library that actually renders the visuals and
        handles the UI interactions for Bokeh :term:`plots<Plot>` and
        :term:`widgets<Widget>` in the browser. In most cases, Bokeh handles all
        interactions with BokehJS automatically ("We write the JavaScript, so you
        don't have to"). For more details, see the :ref:`contributor_guide_bokehjs`
        chapter of the |contributor guide|.

    Document
        An organizing data structure for Bokeh
        :term:`applications<Application>`. Documents contain all the Bokeh
        :term:`models<Model>` and data needed to render an interactive
        visualization or application in the browser.

    Embedding
        Various methods that help with including Bokeh :term:`plots<Plot>` and
        :term:`widgets<Widget>` in web apps, web pages, or Jupyter notebooks.
        See :ref:`ug_output_embed` in the |user guide| for more details.

    Glyph
        API objects that draw vectorized graphics to represent data. Glyphs are
        the basic visual building blocks of Bokeh :term:`plots<Plot>`. This
        includes elements such as lines, rectangles, squares, wedges, or the
        circles of a scatter plot. The |plotting interface| provides a
        convenient way to create plots centered around glyphs. See
        :ref:`ug_basic` in the |user guide| for more information.

    Layout
        A collection of Bokeh objects. This can be several :term:`plots<Plot>`
        and :term:`widgets<Widget>`, arranged in nested rows and columns. See
        :ref:`ug_basic_layouts` in the |user guide| for more information and
        examples.

    Model
        The lowest-level objects that Bokeh visualizations consist of. Bokeh's
        models are part of the |models interface|. Most users will not use this
        level of interface to assemble plots directly. However, ultimately all
        Bokeh plots consist of collections of models. It is helpful to
        understand them enough to configure their attributes and properties.
        See :ref:`ug_styling` in the |user guide| for more
        information.

    Plot
        Containers that hold all the various objects (such as
        :term:`renderers<Renderer>`, :term:`glyphs<Glyph>`, or
        :term:`annotations<Annotation>`) of a visualization. The
        |plotting interface| provides the |figure| function to help with
        assembling all the necessary objects.

    Renderer
        General term for any method or function that draws elements of the plot.
        Examples of elements that are generated by renderers are
        :term:`glyphs<Glyph>` or :term:`annotations<Annotation>`.

    Server
        The Bokeh server is an optional component. You can use the Bokeh server
        to share and publish Bokeh plots and apps, to handle streaming of large
        data sets, or to enable complex user interactions based on
        :term:`widgets<Widget>` and selections. See :ref:`ug_server` in
        the |user guide| for more information and examples.

    Widget
        User interface elements that are not directly part of a Bokeh
        :term:`plot<Plot>`, such as sliders, drop-down menus, or buttons. You
        can use events and data from widgets in your Python code, or you can
        use input from widgets to update you Bokeh plot itself. You can use
        widgets in standalone :term:`applications<Application>` or with the
        Bokeh :term:`server<Server>`. For examples and information, see
        :ref:`ug_interaction` in the |user guide|.

.. _ug_output_methods:

Output methods
--------------

Bokeh offers a variety of ways to produce interactive output. The following
two functions are the most common:

|output_file|
    Generate simple standalone HTML documents for Bokeh visualizations.

|output_notebook|
    Display Bokeh visualizations in Jupyter/Zeppelin notebooks.

These output functions are usually used together with |show| or |save|. Here's
an example:

.. code-block:: python

    from bokeh.plotting import figure, output_file, show

    output_file("output.html")

    p = figure()
    p.line(x=[1, 2, 3], y=[4,6,2])

    show(p)

This script generates an HTML file called ``output.html`` that contains a line
plot. You can execute it with ``python foo.py``, where ``foo.py`` is the name
of the script.

These functions are often useful in interactive settings or for creating
standalone Bokeh documents to serve from backend web applications.

.. _ug_settings:

Bokeh settings
--------------

There are various global settings that influence how Bokeh operates. You can use
several methods to change Bokeh's configuration: Directly in the Python code, in
a YAML configuration file, or with environment variables, for example. The full
list of all available settings and how to change them is available at
:ref:`bokeh.settings`.

Some of most useful settings are:

``browser`` (environment variable ``BOKEH_BROWSER``)
    Set this configuration value to the browser you want Bokeh to use (for
    example when calling |show|). Valid values are any of the predefined browser
    names of the Python :doc:`webbrowser <python:library/webbrowser>` module.
    For example: ``chromium-browser`` or ``windows-default``. You can also set
    this variable to the full path of your browser. For example:

    .. tab-set::

        .. tab-item:: Linux/macOS
            :sync: sh

            .. code-block:: sh

                export BOKEH_BROWSER=/usr/bin/chromium-browser

        .. tab-item:: Windows (PS)
            :sync: ps

            .. code-block:: powershell

                $Env:BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"

        .. tab-item:: Windows (CMD)
            :sync: cmd

            .. code-block:: doscon

                set BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"

``resources`` (environment variable ``BOKEH_RESOURCES``)
    To display interactive visualizations in a browser, Bokeh needs to load
    :term:`BokehJS`. Set this configuration value to define where to load
    BokehJS from. For example:

    * ``cdn`` to load BokehJS from Bokeh's Content Delivery Network (CDN)
    * ``server`` to load from a Bokeh server
    * ``relative`` to load a local version relative to the given directory.

    All available options are listed at :class:`~bokeh.resources.Resources`.

    You can combine some of the values for this variable with other
    configuration values, such as ``cdn_version`` (``BOKEH_CDN_VERSION``) and
    ``rootdir`` (``BOKEH_ROOTDIR``). See :ref:`bokeh.settings` for details.

.. _ug_interfaces:

Interfaces
----------

Bokeh provides a simple and intuitive interface for users like data scientists
and domain experts who do not wish to be distracted by complex details of the
software. At the same time, Bokeh also caters to people such as application
developers and software engineers who may want more control or access to more
sophisticated features.

Because of this, Bokeh takes a layered approach and offers different programming
interfaces appropriate to different users.

This section provides an overview of the two interfaces that you can use: the
primary interface :ref:`bokeh.plotting <ug_interfaces_plotting>` and
the low-level :ref:`bokeh.models<ug_interfaces_models>` interface.

If you'd prefer to jump right into basic plotting, go to
:ref:`ug_basic`. For a simple step-by-step guide to creating
visualizations with Bokeh, see the :ref:`first steps guides <first_steps>`.

.. _ug_interfaces_plotting:

The *bokeh.plotting* interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|bokeh.plotting| is Bokeh's **primary** interface. This general-purpose
interface is similar to plotting interfaces of libraries such as Matplotlib_
or Matlab_.

The *bokeh.plotting* interface lets you focus on relating glyphs to data. It
automatically assembles plots with default elements such as axes, grids, and
tools for you.

The |figure| function is at the core of the |bokeh.plotting| interface. This
function creates a |figure| model that includes methods for adding different
kinds of glyphs to a plot. This function also takes care of composing the
various elements of your visualization, such as axes, grids, and tools.

Below is an example of |bokeh.plotting|, along with the resulting
plot:

.. bokeh-plot::
    :source-position: above

    from bokeh.plotting import figure, output_file, show

    # create a figure object
    p = figure(width=300, height=300, tools="pan,reset,save")

    # add a Circle renderer to this figure
    p.circle([1, 2.5, 3, 2], [2, 3, 1, 1.5], radius=0.3, alpha=0.5)

    # specify how to output the plot(s)
    output_file("foo.html")

    # display the figure
    show(p)

Calling the |figure| function is all it takes to create a basic plot object. To
add data renderers to your plot object, call a glyph method such as
|figure.circle|. You don't have to worry about axes and grids (although you can
configure them if you want to), and you only need to list the tools you want to
add. To display your visualization in a browser, in most cases, all you need to
do is call the output function |show|.

With the *bokeh.plotting* interface, you have many more possibilities to
create and customize your visualization. For example:

* saving the plot to an HTML file instead of showing it
* styling and removing axes, grids, annotations, and interactive elements
* adding more data renderers
* arranging multiple plots and widgets into layouts

The :ref:`ug_basic` section of this |user guide| will walk you
through many more examples and common use cases for the |bokeh.plotting|
interface.

For an easy to follow guide to building your first visualizations with Bokeh,
see the :ref:`first steps guides <first_steps>`.

.. _ug_interfaces_models:

The *bokeh.models* interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With Bokeh's **low-level** |bokeh.models| interface, you have complete control
over how Bokeh creates all elements of your visualization. However, Bokeh's
low-level interface doesn't help you assemble the various elements in meaningful
or correct ways. It is entirely up to you to put them together.

Therefore, unless you have special applications that require finer control,
you will probably want to use the *bokeh.plotting* interface
:ref:`described above <ug_interfaces_plotting>`.

To be able to use the *bokeh.models* interface, you need to understand the
basic principle by which Bokeh enables you to generate interactive,
browser-based visualizations. Behind the scenes, Bokeh consists of two
libraries:

* BokehJS, the JavaScript library
    :term:`BokehJS` runs in the browser. This library handles rendering and user
    interactions. It takes a collection of declarative JSON objects as its input
    and uses them as instructions on how to handle the various aspects of your
    visualization in a browser. For example:

    * plots and widgets
    * layouts and arrangements
    * tools and renderers
    * plot axes

    In the browser, BokehJS converts these JSON objects into BokehJS models and
    renders them according to corresponding BokehJS views.

* Bokeh, the Python library
    The Python library generates the JSON objects that BokehJS uses to render
    your visualization in a browser.

    At its lowest level, the Python library uses a set of ``model`` classes that
    exactly mirror the set of models that BokehJS creates in a browser.

    These Python ``model`` classes are able to validate their content and
    attributes and serialize themselves to JSON. Most of the models are very
    simple and usually consist of only a few property attributes and no methods.
    You can configure the attributes of those models either by setting them when
    creating a model or later by setting attribute values on the model object.

You can access all low-level ``model`` objects through Bokeh's |bokeh.models|
interface.

For example, to create and configure a |Rect| glyph object:

.. code-block:: python

    # configure attributes when initializing a model object
    glyph = Rect(x="x", y="y2", w=10, h=20, line_color=None)

    # assign values to attributes to an existing model object
    glyph.fill_alpha = 0.5
    glyph.fill_color = "navy"

You can generally configure all Bokeh models this way. Since all Bokeh
interfaces ultimately produce collections of Bokeh models, this lets you
style and configure plots and widgets the same way regardless of the
interface.

For more information on Bokeh models, see |bokeh.models| in the |reference guide|.

.. note::

   The Python library allows for binding with other languages that can produce
   appropriate JSON output. For more details and available bindings, see
   :ref:`contributor_guide_bindings`.


.. _Matlab: http://www.mathworks.com/products/matlab/
.. _Matplotlib: http://matplotlib.org

.. |bokeh.io|       replace:: :ref:`bokeh.io <bokeh.io>`

.. |Rect| replace:: :class:`~bokeh.models.glyphs.Rect`

.. |figure.circle|   replace:: :func:`figure.circle <bokeh.plotting.figure.circle>`
