.. _faq_plotting:

Plotting FAQs
=============

This page gathers frequently asked questions regarding the dantro plotting interface.

.. contents::
   :local:
   :depth: 2

Aside from these FAQs, make sure to have a look :doc:`at other plotting-related documentation pages <../index>`.

.. note::

    If you would like to add a question here, we are happy about contributions!
    Please visit the `project page <https://gitlab.com/utopia-project/dantro>`_ to open an issue or get more information about contributing.

----

General :py:class:`~dantro.plot_mngr.PlotManager` FAQs
------------------------------------------------------

Can I create plots in a specific directory?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes.

To write plots to a custom output directory (other than the associated output directory of the :py:class:`~dantro.plot_mngr.PlotManager`), simply specify the ``out_dir`` argument in the plot configuration.

The file extension of the plot can also be specified there, using the ``file_ext`` key.
Example:

.. code-block:: yaml

    my_plot:
      out_dir: ~/my/custom/output/directory

      # ... the rest of the plot configuration

.. note::

    You can only specify a *directory* here, not a full path; the full file path will be generated by the plot manager by adding the name of the plot and potentially existing sweep configurations to it.

    If a *relative* path is given for ``out_dir``, it will be relative to the output directory of the associated :py:class:`~dantro.data_mngr.DataManager`.


How can I specify a file extension?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The file extension used in generating the output path can be adjusted for all plots associated with a plot creator or for a single plot, using its plot configuration.

To set a default extension, use the ``default_ext`` argument to :py:class:`~dantro.plot.creators.base.BasePlotCreator` or derived classes.
To specify it for a single plot, use the ``file_ext`` argument, directly in its plot configuration:

.. code-block:: yaml

    my_plot:
      file_ext: pdf

      # ... the rest of the plot configuration

Also have a look at :doc:`plot_cfg_ref`.


.. _faq_plotting_overwrite:

Can I allow plots to be overwritten instead of raising an error?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes.

Follow these steps to achieve overwriting of existing plot output:

- **Tell the plot creator that it should not raise an error if a file already exists** at the generated output path:

    - Pass ``exist_ok=True`` in the plot configuration
    - Pass ``exist_ok=True`` to the plot creator during initialization

    .. note::

        If you always desire this behavior for a specific plot creator, set the :py:const:`~dantro.plot.creators.base.BasePlotCreator.OUT_PATH_EXIST_OK` class variable to ``True``.
        That variable defines the default behavior.
        It is overwritten by the ``exist_ok`` argument passed during initialization of a :py:class:`~dantro.plot.creators.base.BasePlotCreator` (or derived creator) and by the value given in the plot configuration.

- **Tell the plot manager to overwrite existing plot configuration files** that are stored alongside each plot; otherwise, this would also create conflict.
  To do so, pass ``cfg_exists_action='overwrite'`` during the initialization of the :py:class:`~dantro.plot_mngr.PlotManager`.
  To suppress a warning, use ``overwrite_nowarn``.



Can plots be skipped?
^^^^^^^^^^^^^^^^^^^^^
Yes. See :ref:`plot_mngr_skipping_plots` for more information.



:py:class:`~dantro.plot.plot_helper.PlotHelper` FAQs
--------------------------------------------------------------

Can I assign a custom figure to the PlotHelper?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes.

When using the :py:class:`~dantro.plot.plot_helper.PlotHelper`, it automatically sets up a figure instance and an axis initially, even before the plot function is called.
However, they can be replaced using the :py:meth:`~dantro.plot.plot_helper.PlotHelper.attach_figure_and_axes` method.


Can I let the plot function decide whether to perform an animation?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes. See :ref:`pcr_pyplot_animation_mode_switching` for more information.