<commit_before>.. currentmodule:: altair

.. _user-guide-encoding:

Encodings
---------

The key to creating meaningful visualizations is to map *properties of the data*
to *visual properties* in order to effectively communicate information.
In Altair, this mapping of visual properties to data columns is referred to
as an **encoding**, and is most often expressed through the :meth:`Chart.encode`
method.

For example, here we will visualize the cars dataset using four of the available
encodings: ``x`` (the x-axis value), ``y`` (the y-axis value),
``color`` (the color of the marker), and ``shape`` (the shape of the point marker):

.. altair-plot::

   import altair as alt
   from vega_datasets import data
   cars = data.cars()

   alt.Chart(cars).mark_point().encode(
       x='Horsepower',
       y='Miles_per_Gallon',
       color='Origin',
       shape='Origin'
   )

For data specified as a DataFrame, Altair can automatically determine the
correct data type for each encoding, and creates appropriate scales and
legends to represent the data.

.. _encoding-channels:

Encoding Channels
~~~~~~~~~~~~~~~~~

Altair provides a number of encoding channels that can be useful in different
circumstances; the following table summarizes them:

Position Channels:

==========  ===================  =================================  ===================================
Channel     Altair Class         Description                        Example
==========  ===================  =================================  ===================================
x           :class:`X`           The x-axis value                   :ref:`gallery_simple_scatter`
y           :class:`Y`           The y-axis value                   :ref:`gallery_simple_scatter`
x2          :class:`X2`          Second x value for ranges          :ref:`gallery_error_bars_with_ci`
y2          :class:`Y2`          Second y value for ranges          :ref:`gallery_line_with_ci`
longitude   :class:`Longitude`   Longitude for geo charts           :ref:`gallery_airports`
latitude    :class:`Latitude`    Latitude for geo charts            :ref:`gallery_airports`
longitude2  :class:`Longitude2`  Second longitude value for ranges  N/A
latitude2   :class:`Latitude2`   Second latitude value for ranges   N/A
xerror      :class:`XError`      The x-axis error value             N/A
yerror      :class:`YError`      The y-axis error value             N/A
xerror2     :class:`XError2`     The second x-axis error value      N/A
yerror2     :class:`YError2`     The second y-axis error value      N/A
==========  ===================  =================================  ===================================

Mark Property Channels:

=======  ================  ========================  =========================================
Channel  Altair Class      Description               Example
=======  ================  ========================  =========================================
color    :class:`Color`    The color of the mark     :ref:`gallery_simple_heatmap`
fill     :class:`Fill`     The fill for the mark     N/A
opacity  :class:`Opacity`  The opacity of the mark   :ref:`gallery_horizon_graph`
shape    :class:`Shape`    The shape of the mark     N/A
size     :class:`Size`     The size of the mark      :ref:`gallery_table_bubble_plot_github`
stroke   :class:`Stroke`   The stroke of the mark    N/A
=======  ================  ========================  =========================================

Text and Tooltip Channels:

=======  ================  ========================  =========================================
Channel  Altair Class      Description               Example
=======  ================  ========================  =========================================
text     :class:`Text`     Text to use for the mark  :ref:`gallery_scatter_with_labels`
key      :class:`Key`      --                        N/A
tooltip  :class:`Tooltip`  The tooltip value         :ref:`gallery_scatter_tooltips`
=======  ================  ========================  =========================================

Hyperlink Channel:

=======  ================  ========================  =========================================
Channel  Altair Class      Description               Example<commit_msg>DOC: update encoding tables<commit_after>.. currentmodule:: altair

.. _user-guide-encoding:

Encodings
---------

The key to creating meaningful visualizations is to map *properties of the data*
to *visual properties* in order to effectively communicate information.
In Altair, this mapping of visual properties to data columns is referred to
as an **encoding**, and is most often expressed through the :meth:`Chart.encode`
method.

For example, here we will visualize the cars dataset using four of the available
encodings: ``x`` (the x-axis value), ``y`` (the y-axis value),
``color`` (the color of the marker), and ``shape`` (the shape of the point marker):

.. altair-plot::

   import altair as alt
   from vega_datasets import data
   cars = data.cars()

   alt.Chart(cars).mark_point().encode(
       x='Horsepower',
       y='Miles_per_Gallon',
       color='Origin',
       shape='Origin'
   )

For data specified as a DataFrame, Altair can automatically determine the
correct data type for each encoding, and creates appropriate scales and
legends to represent the data.

.. _encoding-channels:

Encoding Channels
~~~~~~~~~~~~~~~~~

Altair provides a number of encoding channels that can be useful in different
circumstances; the following table summarizes them:

Position Channels:

==========  ===================  =================================  ===================================
Channel     Altair Class         Description                        Example
==========  ===================  =================================  ===================================
x           :class:`X`           The x-axis value                   :ref:`gallery_simple_scatter`
y           :class:`Y`           The y-axis value                   :ref:`gallery_simple_scatter`
x2          :class:`X2`          Second x value for ranges          :ref:`gallery_error_bars_with_ci`
y2          :class:`Y2`          Second y value for ranges          :ref:`gallery_line_with_ci`
longitude   :class:`Longitude`   Longitude for geo charts           :ref:`gallery_airports`
latitude    :class:`Latitude`    Latitude for geo charts            :ref:`gallery_airports`
longitude2  :class:`Longitude2`  Second longitude value for ranges  N/A
latitude2   :class:`Latitude2`   Second latitude value for ranges   N/A
xerror      :class:`XError`      The x-axis error value             N/A
yerror      :class:`YError`      The y-axis error value             N/A
xerror2     :class:`XError2`     The second x-axis error value      N/A
yerror2     :class:`YError2`     The second y-axis error value      N/A
==========  ===================  =================================  ===================================

Mark Property Channels:

=============  ======================  ==============================  =========================================
Channel        Altair Class            Description                     Example
=============  ======================  ==============================  =========================================
color          :class:`Color`          The color of the mark           :ref:`gallery_simple_heatmap`
fill           :class:`Fill`           The fill for the mark           N/A
fillopacity    :class:`FillOpacity`    The opacity of the mark's fill  N/A
opacity        :class:`Opacity`        The opacity of the mark         :ref:`gallery_horizon_graph`
shape          :class:`Shape`          The shape of the mark           N/A
size           :class:`Size`           The size of the mark            :ref:`gallery_table_bubble_plot_github`
stroke         :class:`Stroke`         The stroke of the mark          N/A
strokeopacity  :class:`StrokeOpacity`  The opacity of the line         N/A
strokewidth    :class:`StrokeWidth`    The width of the line           N/A
=============  ======================  ==============================  =========================================

Text and Tooltip Channels:

=======  ================  ========================  =========================================
Channel  Altair Class      Description               Example
=======  ================  ========================  =========================================
text     :class:`Text`     Text to use for the mark  :ref:`gallery_scatter_with_labels`
key      :class:`Key`      --                        N/A
tooltip  :class:`Tooltip`  The tooltip value         :ref:`gallery_scatter_tooltips`
=======  ================  ========================  =========================================

Hyperlink Channel:

=======  ================  ========================  =========================================
Channel  Altair Class      Description               Example
{'fraction_non_alphanumeric': 0.2732356559668941, 'fraction_numerical': 0.0026842635052007607, 'mean_word_length': 3.1961520412951665, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '92302', 'n_tokens_mistral': 2265, 'n_tokens_neox': 2062, 'n_words': 705}