Engines
=======
Overview
--------
**fivecentplots** is *not a new graphics generation library*. All plots are created using existing Python plotting
packages.
**fivecentplots** was conceived around two guiding principles:
1. many users would benefit from a simplified API that still enables complex plots with customized styling
2. many users would benefit from being able to choose the plotting "engine" or package that meets their needs without having to learn a completely new API
For example, a user preparing plots for a paper in a scientific journal might prefer the quality rendering and
rich feature set of `matplotlib` but while exploring experimental results in a jupyter notebook might instead prefer
an interactive web-based plotting implementation like `plotly` or `bokeh`. The kwarg-based API of **fivecentplots**
makes this kind of library switching incredibly easy, requiring only a single keyword (`engine`) to perform the toggle:
.. code-block:: python
fcp.plot(df, x='Voltage', y='I [A]', legend='Die', col='Boost Level', ax_size=[225, 225],
filter='Substrate=="Si" & Target Wavelength==450 & Temperature [C]==25', engine='mpl', theme='gray')
.. image:: ../_static/images/mpl.png
:align: center
.. code-block:: python
fcp.plot(df, x='Voltage', y='I [A]', legend='Die', col='Boost Level', ax_size=[225, 225],
filter='Substrate=="Si" & Target Wavelength==450 & Temperature [C]==25', engine='plotly', theme='gray_plotly')
.. raw:: html
.. code-block:: python
fcp.plot(df, x='Voltage', y='I [A]', legend='Die', col='Boost Level', ax_size=[225, 225],
filter='Substrate=="Si" & Target Wavelength==450 & Temperature [C]==25', engine='bokeh', theme='gray_bokeh')
.. raw:: html
Bokeh Plot
Adding New Engines
------------------
Each engine is a ``Layout`` class that lives in a separate file within ``fivecentplots/src/fivecentplots/engines`` and
inherits the ``BaseLayout`` class found in ``layout.py``. This file exclusively contains all the plotting-module specific
code that is needed by **fivecentplots**.
Not seeing a plotly engine you need? Please join the effort and make one!
``fivecentplots/src/fivecentplots/engines/new_engine_template.py`` is provided as a template to get started. Simply
(or maybe not that simply?) populate the functions in this template and bring your new engine to life.
.. toctree::
:maxdepth: 1
:caption: Examples
plotly.ipynb
bokeh.ipynb