
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorials/intermediate/autoscale.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_tutorials_intermediate_autoscale.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorials_intermediate_autoscale.py:


Autoscaling
===========

The limits on an axis can be set manually (e.g. ``ax.set_xlim(xmin, xmax)``)
or Matplotlib can set them automatically based on the data already on the axes.
There are a number of options to this autoscaling behaviour, discussed below.

.. GENERATED FROM PYTHON SOURCE LINES 11-13

We will start with a simple line plot showing that autoscaling
extends the axis limits 5% beyond the data limits (-2π, 2π).

.. GENERATED FROM PYTHON SOURCE LINES 13-24

.. code-block:: default


    import numpy as np
    import matplotlib as mpl
    import matplotlib.pyplot as plt

    x = np.linspace(-2 * np.pi, 2 * np.pi, 100)
    y = np.sinc(x)

    fig, ax = plt.subplots()
    ax.plot(x, y)




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_001.png
   :alt: autoscale
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_001.png, /tutorials/intermediate/images/sphx_glr_autoscale_001_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    [<matplotlib.lines.Line2D object at 0x7f3fca30aec0>]



.. GENERATED FROM PYTHON SOURCE LINES 25-28

Margins
-------
The default margin around the data limits is 5%:

.. GENERATED FROM PYTHON SOURCE LINES 28-31

.. code-block:: default


    ax.margins()





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    (0.05, 0.05)



.. GENERATED FROM PYTHON SOURCE LINES 32-33

The margins can be made larger using `~matplotlib.axes.Axes.margins`:

.. GENERATED FROM PYTHON SOURCE LINES 33-38

.. code-block:: default


    fig, ax = plt.subplots()
    ax.plot(x, y)
    ax.margins(0.2, 0.2)




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_002.png
   :alt: autoscale
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_002.png, /tutorials/intermediate/images/sphx_glr_autoscale_002_2_0x.png 2.0x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 39-44

In general, margins can be in the range (-0.5, ∞), where negative margins set
the axes limits to a subrange of the data range, i.e. they clip data.
Using a single number for margins affects both axes, a single margin can be
customized using keyword arguments ``x`` or ``y``, but positional and keyword
interface cannot be combined.

.. GENERATED FROM PYTHON SOURCE LINES 44-49

.. code-block:: default


    fig, ax = plt.subplots()
    ax.plot(x, y)
    ax.margins(y=-0.2)




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_003.png
   :alt: autoscale
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_003.png, /tutorials/intermediate/images/sphx_glr_autoscale_003_2_0x.png 2.0x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 50-56

Sticky edges
------------
There are plot elements (`.Artist`\s) that are usually used without margins.
For example false-color images (e.g. created with `.Axes.imshow`) are not
considered in the margins calculation.


.. GENERATED FROM PYTHON SOURCE LINES 56-67

.. code-block:: default


    xx, yy = np.meshgrid(x, x)
    zz = np.sinc(np.sqrt((xx - 1)**2 + (yy - 1)**2))

    fig, ax = plt.subplots(ncols=2, figsize=(12, 8))
    ax[0].imshow(zz)
    ax[0].set_title("default margins")
    ax[1].imshow(zz)
    ax[1].margins(0.2)
    ax[1].set_title("margins(0.2)")




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_004.png
   :alt: default margins, margins(0.2)
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_004.png, /tutorials/intermediate/images/sphx_glr_autoscale_004_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Text(0.5, 1.0, 'margins(0.2)')



.. GENERATED FROM PYTHON SOURCE LINES 68-77

This override of margins is determined by "sticky edges", a
property of `.Artist` class that can suppress adding margins to axis
limits. The effect of sticky edges can be disabled on an Axes by changing
`~matplotlib.axes.Axes.use_sticky_edges`.
Artists have a property `.Artist.sticky_edges`, and the values of
sticky edges can be changed by writing to ``Artist.sticky_edges.x`` or
``Artist.sticky_edges.y``.

The following example shows how overriding works and when it is needed.

.. GENERATED FROM PYTHON SOURCE LINES 77-90

.. code-block:: default


    fig, ax = plt.subplots(ncols=3, figsize=(16, 10))
    ax[0].imshow(zz)
    ax[0].margins(0.2)
    ax[0].set_title("default use_sticky_edges\nmargins(0.2)")
    ax[1].imshow(zz)
    ax[1].margins(0.2)
    ax[1].use_sticky_edges = False
    ax[1].set_title("use_sticky_edges=False\nmargins(0.2)")
    ax[2].imshow(zz)
    ax[2].margins(-0.2)
    ax[2].set_title("default use_sticky_edges\nmargins(-0.2)")




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_005.png
   :alt: default use_sticky_edges margins(0.2), use_sticky_edges=False margins(0.2), default use_sticky_edges margins(-0.2)
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_005.png, /tutorials/intermediate/images/sphx_glr_autoscale_005_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Text(0.5, 1.0, 'default use_sticky_edges\nmargins(-0.2)')



.. GENERATED FROM PYTHON SOURCE LINES 91-103

We can see that setting ``use_sticky_edges`` to *False* renders the image
with requested margins.

While sticky edges don't increase the axis limits through extra margins,
negative margins are still taken into account. This can be seen in
the reduced limits of the third image.

Controlling autoscale
---------------------

By default, the limits are
recalculated every time you add a new curve to the plot:

.. GENERATED FROM PYTHON SOURCE LINES 103-111

.. code-block:: default


    fig, ax = plt.subplots(ncols=2, figsize=(12, 8))
    ax[0].plot(x, y)
    ax[0].set_title("Single curve")
    ax[1].plot(x, y)
    ax[1].plot(x * 2.0, y)
    ax[1].set_title("Two curves")




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_006.png
   :alt: Single curve, Two curves
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_006.png, /tutorials/intermediate/images/sphx_glr_autoscale_006_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Text(0.5, 1.0, 'Two curves')



.. GENERATED FROM PYTHON SOURCE LINES 112-120

However, there are cases when you don't want to automatically adjust the
viewport to new data.

One way to disable autoscaling is to manually set the
axis limit. Let's say that we want to see only a part of the data in
greater detail. Setting the ``xlim`` persists even if we add more curves to
the data. To recalculate the new limits  calling `.Axes.autoscale` will
toggle the functionality manually.

.. GENERATED FROM PYTHON SOURCE LINES 120-132

.. code-block:: default


    fig, ax = plt.subplots(ncols=2, figsize=(12, 8))
    ax[0].plot(x, y)
    ax[0].set_xlim(left=-1, right=1)
    ax[0].plot(x + np.pi * 0.5, y)
    ax[0].set_title("set_xlim(left=-1, right=1)\n")
    ax[1].plot(x, y)
    ax[1].set_xlim(left=-1, right=1)
    ax[1].plot(x + np.pi * 0.5, y)
    ax[1].autoscale()
    ax[1].set_title("set_xlim(left=-1, right=1)\nautoscale()")




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_007.png
   :alt: set_xlim(left=-1, right=1) , set_xlim(left=-1, right=1) autoscale()
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_007.png, /tutorials/intermediate/images/sphx_glr_autoscale_007_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Text(0.5, 1.0, 'set_xlim(left=-1, right=1)\nautoscale()')



.. GENERATED FROM PYTHON SOURCE LINES 133-135

We can check that the first plot has autoscale disabled and that the second
plot has it enabled again by using `.Axes.get_autoscale_on()`:

.. GENERATED FROM PYTHON SOURCE LINES 135-139

.. code-block:: default


    print(ax[0].get_autoscale_on())  # False means disabled
    print(ax[1].get_autoscale_on())  # True means enabled -> recalculated





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    False
    True




.. GENERATED FROM PYTHON SOURCE LINES 140-147

Arguments of the autoscale function give us precise control over the process
of autoscaling. A combination of arguments ``enable``, and ``axis`` sets the
autoscaling feature for the selected axis (or both). The argument ``tight``
sets the margin of the selected axis to zero. To preserve settings of either
``enable`` or ``tight`` you can set the opposite one to *None*, that way
it should not be modified. However, setting ``enable`` to *None* and tight
to *True* affects both axes regardless of the ``axis`` argument.

.. GENERATED FROM PYTHON SOURCE LINES 147-155

.. code-block:: default


    fig, ax = plt.subplots()
    ax.plot(x, y)
    ax.margins(0.2, 0.2)
    ax.autoscale(enable=None, axis="x", tight=True)

    print(ax.margins())




.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_008.png
   :alt: autoscale
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_008.png, /tutorials/intermediate/images/sphx_glr_autoscale_008_2_0x.png 2.0x
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    (0, 0)




.. GENERATED FROM PYTHON SOURCE LINES 156-164

Working with collections
------------------------

Autoscale works out of the box for all lines, patches, and images added to
the axes. One of the artists that it won't work with is a `.Collection`.
After adding a collection to the axes, one has to manually trigger the
`~matplotlib.axes.Axes.autoscale_view()` to recalculate
axes limits.

.. GENERATED FROM PYTHON SOURCE LINES 164-173

.. code-block:: default


    fig, ax = plt.subplots()
    collection = mpl.collections.StarPolygonCollection(
        5, 0, [250, ],  # five point star, zero angle, size 250px
        offsets=np.column_stack([x, y]),  # Set the positions
        transOffset=ax.transData,  # Propagate transformations of the Axes
    )
    ax.add_collection(collection)
    ax.autoscale_view()



.. image-sg:: /tutorials/intermediate/images/sphx_glr_autoscale_009.png
   :alt: autoscale
   :srcset: /tutorials/intermediate/images/sphx_glr_autoscale_009.png, /tutorials/intermediate/images/sphx_glr_autoscale_009_2_0x.png 2.0x
   :class: sphx-glr-single-img






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  2.068 seconds)


.. _sphx_glr_download_tutorials_intermediate_autoscale.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: autoscale.py <autoscale.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: autoscale.ipynb <autoscale.ipynb>`


.. only:: html

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

    Keywords: matplotlib code example, codex, python plot, pyplot
    `Gallery generated by Sphinx-Gallery
    <https://sphinx-gallery.readthedocs.io>`_
