<commit_before>.. _configuring-altair:

Configuring Plots
-----------------

.. todo

*Coming soon*<commit_msg>DOC: add info on axis limits<commit_after>.. currentmodule:: altair

.. _configuring-altair:

Configuring Altair Visualizations
=================================

Altair's goal is to automatically choose useful plot settings and configurations
so that the user is free to think about the data rather than the plotting
machinery. That said, once you have a useful visualization, you will often want
to adjust certain aspects of it. This section of the documentation outlines
some of these adjustments.

.. note::

   This section is currently not complete; for more information on the adjustments
   available, see Vega-Lite's `Configuration Documentation <https://vega.github.io/vega-lite/docs/config.html>`_


Adjusting Axis Limits
---------------------
Axis limits can be adjusted using the :class:`Scale` property of the axis
encodings. For example, consider the following plot:

.. altair-setup::
    :show:

    from altair import Chart, load_dataset, X, Y, Scale
    data = load_dataset('cars', url_only=True)

.. altair-plot::

    Chart(data).mark_point().encode(
        x='Acceleration:Q',
        y='Horsepower:Q'
    )


Suppose you would like to adjust the limits of the x-axis. You can do this by
adding a :class:`Scale` property to the :class:`X` encoding that specifies
these limits:

.. altair-plot::

    Chart(data).mark_point().encode(
        X('Acceleration:Q', scale=Scale(domain=(5, 15))),
        y='Horsepower:Q'
    )

The problem is that the data still exists beyond the scale, and we need to tell
Altair what to do with this data. One option is to "clamp" the data; that is,
to adjust it so that data beyond the limits are moved to the limit:

.. altair-plot::

    Chart(data).mark_point().encode(
        X('Acceleration:Q', scale=Scale(domain=(5, 15), clamp=True)),
        y='Horsepower:Q'
    )

Another option is to *filter* the data, using the :meth:`Chart.transform_data`
method, to remove these values from the dataset:

.. altair-plot::

    Chart(data).mark_point().encode(
        X('Acceleration:Q', scale=Scale(domain=(5, 15))),
        y='Horsepower:Q'
    ).transform_data(filter='datum.Acceleration < 15')

Some combination of filtering and clamping is usually suitable for adjusting
of axis limits.
{'fraction_non_alphanumeric': 0.12775891341256368, 'fraction_numerical': 0.00466893039049236, 'mean_word_length': 3.648915187376726, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 4, 'https://': 1, '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': '637705', 'n_tokens_mistral': 706, 'n_tokens_neox': 670, 'n_words': 258}