<commit_before>
.. highlight:: python
   :linenothreshold: 10

*********************
Containers and Layout
*********************

Chaco containers
================

It is quite common to need to display multiple data side by side.
In order to arrange  plots and other components (e.g., colorbars, legends)
in a single panel,
Chaco uses *containers* to organize the layout.

Chaco implements 4 different containers:
:ref:`hv-plot-container`,
:ref:`grid-plot-container`, and :ref:`overlay-plot-container`.

All containers are derived from the base class
:class:`~chaco.base_plot_container.​BasePlotContainer`, and share
a common interface:

* ``__init__(*components, **parameters)`` (constructor of the container object):
  The constructor of a plot container takes a sequence of
  components, which are added to the container itself,
  and a set of keyword arguments, which are used to initialize the
  parameters of the container. For example::

      container = HPlotContainer(scatter_plot, line_plot, spacing=100)

  creates a container with horizontal layout containing two plots
  (``scatter_plot`` and ``line_plot``), with a spacing of 100 pixels between
  them.

* ``add(*components)``: Append ore or more plots to the ones already present in the
  container. For example, this is equivalent to the code above::

      container = HPlotContainer(spacing=100)
      container.add(line_plot, scatter_plot)

* ``remove(self, *components)``: Remove a sequence of components from the
  container

* ``insert(index, component)``: Inserts a component at a specific position
  in the components list

.. note::

    **Each plot can have only one container**, so adding the same plot to
    a second container will remove it from the first one. In the same way,
    adding the same plot multiple times will not have create multiple
    copies. Instead, one should create multiple plots objects.

    E.g., this code::

            # Create a vertical container containing two horizontal containers
            h_container1 = HPlotContainer()
            h_container2 = HPlotContainer()
            outer_container = VPlotContainer(h_container1, h_container2,
                                             stack_order="top_to_bottom")

            # Add the two plots to the first container
            h_container1.add(scatter_plot, line_plot1, line_plot2)

            # Now add the first line plot to the second container => it is removed
            # from the first, as each plot can only have one container
            h_container2.add(line_plot1)

    results in this layout:

      .. image:: images/user_guide/one_container_per_plot.png
          :height: 200pt



.. _hv-plot-container:

HPlotContainer and VPlotContainer
---------------------------------

:class:`~chaco.plot_containers.HPlotContainer` and
:class:`~chaco.plot_containers.VPlotContainer` display a set of components
in an horizontal and vertical stack, respectively, as shown in these simple
examples:

.. image:: images/hplotcontainer.png
    :height: 200pt

.. image:: images/vplotcontainer.png
    :height: 200pt

In both cases, a series of line plots and scatter plots is added to an<commit_msg>Changed two to three in the first example code.<commit_after>.. highlight:: python
   :linenothreshold: 10

*********************
Containers and Layout
*********************

Chaco containers
================

It is quite common to need to display multiple data side by side.
In order to arrange  plots and other components (e.g., colorbars, legends)
in a single panel,
Chaco uses *containers* to organize the layout.

Chaco implements 4 different containers:
:ref:`hv-plot-container`,
:ref:`grid-plot-container`, and :ref:`overlay-plot-container`.

All containers are derived from the base class
:class:`~chaco.base_plot_container.​BasePlotContainer`, and share
a common interface:

* ``__init__(*components, **parameters)`` (constructor of the container object):
  The constructor of a plot container takes a sequence of
  components, which are added to the container itself,
  and a set of keyword arguments, which are used to initialize the
  parameters of the container. For example::

      container = HPlotContainer(scatter_plot, line_plot, spacing=100)

  creates a container with horizontal layout containing two plots
  (``scatter_plot`` and ``line_plot``), with a spacing of 100 pixels between
  them.

* ``add(*components)``: Append ore or more plots to the ones already present in the
  container. For example, this is equivalent to the code above::

      container = HPlotContainer(spacing=100)
      container.add(line_plot, scatter_plot)

* ``remove(self, *components)``: Remove a sequence of components from the
  container

* ``insert(index, component)``: Inserts a component at a specific position
  in the components list

.. note::

    **Each plot can have only one container**, so adding the same plot to
    a second container will remove it from the first one. In the same way,
    adding the same plot multiple times will not have create multiple
    copies. Instead, one should create multiple plots objects.

    E.g., this code::

            # Create a vertical container containing two horizontal containers
            h_container1 = HPlotContainer()
            h_container2 = HPlotContainer()
            outer_container = VPlotContainer(h_container1, h_container2,
                                             stack_order="top_to_bottom")

            # Add the three plots to the first container
            h_container1.add(scatter_plot, line_plot1, line_plot2)

            # Now add the first line plot to the second container => it is removed
            # from the first, as each plot can only have one container
            h_container2.add(line_plot1)

    results in this layout:

      .. image:: images/user_guide/one_container_per_plot.png
          :height: 200pt



.. _hv-plot-container:

HPlotContainer and VPlotContainer
---------------------------------

:class:`~chaco.plot_containers.HPlotContainer` and
:class:`~chaco.plot_containers.VPlotContainer` display a set of components
in an horizontal and vertical stack, respectively, as shown in these simple
examples:

.. image:: images/hplotcontainer.png
    :height: 200pt

.. image:: images/vplotcontainer.png
    :height: 200pt

In both cases, a series of line plots and scatter plots is added to an
{'fraction_non_alphanumeric': 0.09985891205518106, 'fraction_numerical': 0.009405862987929142, 'mean_word_length': 3.4091223220456115, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6525113', 'n_tokens_mistral': 1728, 'n_tokens_neox': 1619, 'n_words': 693}