:orphan:

************************************
chart recipes
************************************

Common examples to start building charts with the ``visualization_toolkit``.
Each tile below will have a different configuration of the ``chart`` function to display data.

.. caution::
    Many of the code examples in these recipes include loading CSV data from pandas.
    This should not be used in production scenarios and is only done for the purposes of
    creating live code demos in the documentation.

    Pass data to the ``chart`` function using pyspark dataframes in Databricks notebooks or using lists of dictionaries generated from DBSQL queries
    via the ``execute_query`` function for data apps.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Area Chart Examples
===================================

See below for common area chart options to use when creating visualizations.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Area charts are similar to line charts, except that they shade the region below them and are stacked on top of each other. These can be useful to show a percent mix chart.">

.. only:: html

  .. image:: /recipes/area_chart/images/thumb/sphx_glr_plot_area_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_area_chart_plot_area_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Area Chart</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Axes Customization Examples
===================================

See below for common options to style axes. Axis can be adjusted for tick positioning and number formatting.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Charts can be truncated on either axis by specifying an axis_min or axis_max as axis arguments. This will limit the plot area to the specified range of values.">

.. only:: html

  .. image:: /recipes/axes/images/thumb/sphx_glr_plot_date_axis_start_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_axes_plot_date_axis_start.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Truncate X-axis and Y-Axis</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Axes in general work the same way independent of what type of mode a series is. For example a bar chart can be used with a date type x-axis. Options like tick_interal or tick_format are still respected.">

.. only:: html

  .. image:: /recipes/axes/images/thumb/sphx_glr_plot_date_axis_bar_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_axes_plot_date_axis_bar_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Date Axis for Bar Charts</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Charts tick intervals are automatically sized by the relevant axis&#x27; start and end values and calculating a reasonable number of ticks. However, many visualizations might be presented better with specific tick interavls given the use case. In these situations a tick_interval can be specified as an axis argument.">

.. only:: html

  .. image:: /recipes/axes/images/thumb/sphx_glr_plot_data_axis_tick_interval_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_axes_plot_data_axis_tick_interval.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Set Date Axis Intervals</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Charts with axis_type=&quot;date&quot; can have ticks be formatted to match certain styles especially for dates. Use the tick_format and pass a python date format string (Python Docs).">

.. only:: html

  .. image:: /recipes/axes/images/thumb/sphx_glr_plot_date_axis_tick_format_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_axes_plot_date_axis_tick_format.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Specify Date Axis Tick Formats</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Numerical axes can be formatted with the tick_interval and tick_format arguments for axis.">

.. only:: html

  .. image:: /recipes/axes/images/thumb/sphx_glr_plot_numerical_axis_tick_format_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_axes_plot_numerical_axis_tick_format.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Numerical axis formatting and intervals</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Bar Chart Examples
===================================

See below for common bar chart options to use when creating visualizations.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a bar chart with 2 series and general x and y-axis configurations via the chart function.">

.. only:: html

  .. image:: /recipes/bar_chart/images/thumb/sphx_glr_plot_bar_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_bar_chart_plot_bar_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Bar Chart</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Bar charts can be stacked by specifying the is_stacked argument on series.">

.. only:: html

  .. image:: /recipes/bar_chart/images/thumb/sphx_glr_plot_stacked_bar_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_bar_chart_plot_stacked_bar_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Stacked Bar Chart</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Bar charts can be clustered by a categorical column while plotting values on a time-series for each &quot;category&quot;. This can be created by setting mode=clustered_bar in a series of the chart.">

.. only:: html

  .. image:: /recipes/bar_chart/images/thumb/sphx_glr_plot_clustered_bar_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_bar_chart_plot_clustered_bar_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Clustered Bar Chart</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Chart Context Examples
===================================

See below for examples of modifying charts to convey context such as annotations or shaded regions.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="It can be useful to call out positive or negative areas within a chart, especially for growth rate visualizations. This is achieved using the shade_y instance and specifying the appropriate start, end, and color.">

.. only:: html

  .. image:: /recipes/chart_context/images/thumb/sphx_glr_plot_positive_negative_regions_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_chart_context_plot_positive_negative_regions.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Shade Positive and Negative Regions</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Shaded regions can be used to call attention to general section of the chart. The shaded_regions argument is used to define these areas. Pass in a list of shade_x or shade_y instances. Similar to annotations they use an inverval of values to position the shaded area along its axis.">

.. only:: html

  .. image:: /recipes/chart_context/images/thumb/sphx_glr_plot_shaded_region_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_chart_context_plot_shaded_region.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Shaded Regions</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Annotations be placed on a chart that is positioned on both axes. This can be useful to draw attentiong to specific point(s).">

.. only:: html

  .. image:: /recipes/chart_context/images/thumb/sphx_glr_plot_floating_annotations_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_chart_context_plot_floating_annotations.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Chart Floating Annotations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Annotations can be added to a chart using the annotations argument and passing a list of annotation instances. By default, annotations will include a veritical or horizontal line across the axis it lives on and a text box with a given text message.">

.. only:: html

  .. image:: /recipes/chart_context/images/thumb/sphx_glr_plot_annotation_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_chart_context_plot_annotation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Chart Annotations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Combo Chart Examples
===================================

See below for combo chart options to use when creating visualizations.
Combo charts are a mix of lines or bar charts.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Combo charts that mix line and bar series can share the same axis. This is the behavior by default if location is not specified for a series, or shares the same value with other series locations.">

.. only:: html

  .. image:: /recipes/combo_chart/images/thumb/sphx_glr_plot_combo_chart_same_axis_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_combo_chart_plot_combo_chart_same_axis.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Combo Chart on Same Axis</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Plotting charts with mixes series of lines and bars is possible, as well as plotting them on different Y-axes.">

.. only:: html

  .. image:: /recipes/combo_chart/images/thumb/sphx_glr_plot_combo_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_combo_chart_plot_combo_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Combo Charts on Different Y Axes</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Heatmap Chart Examples
===================================

See below for examples of creating heatmap visualizations



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a heatmap chart across two categorical dimensions with a z_axis representing the value at each category pair. The heatmap chart will be a table-like visualization where each table cell maps to a category pair and is colored based on a colorscale">

.. only:: html

  .. image:: /recipes/heatmap_chart/images/thumb/sphx_glr_plot_heatmap_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_heatmap_chart_plot_heatmap_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Heatmap Chart</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Line Chart Examples
===================================

See below for common line chart options to use when creating visualizations.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a line chart with 2 series and general x and y-axis configurations via the chart function.">

.. only:: html

  .. image:: /recipes/line_chart/images/thumb/sphx_glr_plot_line_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_line_chart_plot_line_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Line Chart</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a line chart with adding shaded area around the line series through the shade_series function. The shaded region will appear as a single entity on the legend but when hovering over data points, the lower and upper boundary data values are shown.">

.. only:: html

  .. image:: /recipes/line_chart/images/thumb/sphx_glr_plot_line_chart_with_shaded_bounds_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_line_chart_plot_line_chart_with_shaded_bounds.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Line Chart with Shaded Bounds</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Line charts have different options to control styling behavior. Options are arguments passed to a given series in the chart function.">

.. only:: html

  .. image:: /recipes/line_chart/images/thumb/sphx_glr_plot_line_format_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_line_chart_plot_line_format_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Line Chart Formatting</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Pivot Chart Examples
===================================

See below for options to pivot charts based on data with multiple categories that need to be plotted individually.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="If plotting a pivoted chart where all categories should be included, the include_all_categories flag can be used. When this flag is enabled, all categories within the pivot_column_name will have as series dynamically generated based on the specified series.">

.. only:: html

  .. image:: /recipes/pivoting/images/thumb/sphx_glr_plot_pivot_chart_all_categories_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_pivoting_plot_pivot_chart_all_categories.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pivot Charts across All Categories</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Plotting charts where the input data is aggregated by a categorical column can be pivoted using pivot_column_name in the series function.">

.. only:: html

  .. image:: /recipes/pivoting/images/thumb/sphx_glr_plot_pivot_chart_comparison_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_pivoting_plot_pivot_chart_comparison.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pivot Charts without Stacking</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Plotting charts where the input data is aggregated by a categorical column can be pivoted using pivot_column_name in the series function.">

.. only:: html

  .. image:: /recipes/pivoting/images/thumb/sphx_glr_plot_pivot_chart_stacked_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_pivoting_plot_pivot_chart_stacked.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Stacked Pivot Charts</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Styling Chart Examples
===================================

See below for options to change overall styles for charts



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Charts will default to using the YD_CLASSIC_THEME that is meant to replicate YD report styles.">

.. only:: html

  .. image:: /recipes/styling/images/thumb/sphx_glr_plot_atlas_chart_theme_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_styling_plot_atlas_chart_theme.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Use Atlas theme for charts</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Hover templates can be customized for series to display different values when hovering over a datapoint.">

.. only:: html

  .. image:: /recipes/styling/images/thumb/sphx_glr_plot_hover_template_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_styling_plot_hover_template.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Customize Tooltops (Hover Templates)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Waterfall Chart Examples
===================================

See below for examples to create a waterfall (bridge) chart



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a waterfall chart using the waterfall_chart function. Waterfall charts can show the net result of a starting value after a series of positive/negative adjustments.">

.. only:: html

  .. image:: /recipes/waterfall_chart/images/thumb/sphx_glr_plot_waterfall_chart_thumb.png
    :alt:

  :ref:`sphx_glr_recipes_waterfall_chart_plot_waterfall_chart.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Waterfall Chart</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /recipes/area_chart/index.rst
   /recipes/axes/index.rst
   /recipes/bar_chart/index.rst
   /recipes/chart_context/index.rst
   /recipes/combo_chart/index.rst
   /recipes/heatmap_chart/index.rst
   /recipes/line_chart/index.rst
   /recipes/pivoting/index.rst
   /recipes/styling/index.rst
   /recipes/waterfall_chart/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_