.. include:: ./substitutions.rst

Plotting - matplotlib
=====================

A collection of functions for plotting results using matplotlib_ as the backend.


Wrappers
--------

These functions provide a high-level API for visualizing various objects/results (e.g., :class:`~pyimpspec.data.DataSet`).

.. automodule:: pyimpspec.mpl
   :members: plot_circuit, plot_data, plot_drt, plot_fit, plot_kramers_kronig_tests, plot_log_F_ext



Primitives
----------

These functions are used by the wrapper functions to make a more complex figure with multiple subplots.

.. automodule:: pyimpspec.mpl
   :members: plot_bht_scores, plot_bode, plot_real_imaginary, plot_gamma, plot_imaginary, plot_magnitude, plot_pseudo_chisqr, plot_num_RC_suggestion, plot_num_RC_suggestion_method, plot_nyquist, plot_phase, plot_real, plot_residuals


Examples
--------

Below are some examples of plots created using the plotting functions listed above.
The circuit and the data set are based on test circuit 1 (TC-1) from this 1995 article by `Bernard Boukamp`_.

Legends are disabled and colored axes are used instead in the figures generated by the wrapper functions (i.e., the first figure in each series).
This has been done due to the small size of the figures in this documentation.
However, the figures generated by the individual primitive functions are also included with the legends enabled and without colored axes.

The default color scheme is based on the *Vibrant qualitative* color scheme presented in `Paul Tol`_'s blog.
Colors and markers can be defined when calling any of the functions.

.. _Bernard Boukamp: https://doi.org/10.1149/1.2044210
.. _Paul Tol: https://personal.sron.nl/~pault/

plot_circuit
~~~~~~~~~~~~
:func:`~pyimpspec.mpl.plot_circuit`

* :func:`~pyimpspec.mpl.plot_nyquist`
* :func:`~pyimpspec.mpl.plot_bode`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  from numpy import logspace, log10 as log

  circuit = pyimpspec.generate_mock_circuits("CIRCUIT_1")[0]
  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  f = data.get_frequencies()
  figure, axes = mpl.plot_circuit(circuit, frequencies=f, label="TC-1", title="", legend=False, colored_axes=True)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_nyquist(data, line=True)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_bode(data, line=True)
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage


plot_data
~~~~~~~~~
:func:`~pyimpspec.mpl.plot_data`

* :func:`~pyimpspec.mpl.plot_nyquist`
* :func:`~pyimpspec.mpl.plot_bode`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  import pyimpspec.plot.colors as colors

  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  figure, axes = mpl.plot_data(data, legend=False, colored_axes=True)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_nyquist(data)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_bode(data)
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage


plot_drt
~~~~~~~~
:func:`~pyimpspec.mpl.plot_drt`

* :func:`~pyimpspec.mpl.plot_real_imaginary`
* :func:`~pyimpspec.mpl.plot_gamma`
* :func:`~pyimpspec.mpl.plot_residuals`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  import pyimpspec.plot.colors as colors

  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  drt = pyimpspec.analysis.drt.calculate_drt_tr_nnls(data)
  figure, axes = mpl.plot_drt(
    drt,
    data,
    legend=False,
    colored_axes=True,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_real_imaginary(
    data,
    colors={
      "real": colors.COLOR_BLACK,
      "imaginary": colors.COLOR_BLACK,
    },
    legend=False,
  )
  _ = mpl.plot_real_imaginary(
    drt,
    line=True,
    figure=figure,
    axes=axes,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_gamma(drt)
  figure.tight_layout()
  mpl.show()


  figure, axes = mpl.plot_residuals(drt)
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage


plot_fit
~~~~~~~~
:func:`~pyimpspec.mpl.plot_fit`

* :func:`~pyimpspec.mpl.plot_nyquist`
* :func:`~pyimpspec.mpl.plot_bode`
* :func:`~pyimpspec.mpl.plot_residuals`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  import pyimpspec.plot.colors as colors

  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  circuit = pyimpspec.parse_cdc("R(RC)(RW)")
  fit = pyimpspec.fit_circuit(circuit, data=data)

  figure, axes = mpl.plot_fit(
    fit,
    data,
    legend=False,
    colored_axes=True,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_nyquist(
    data,
    colors={"impedance": colors.COLOR_BLACK},
    legend=False,
  )
  _ = mpl.plot_nyquist(
    fit,
    line=True,
    figure=figure,
    axes=axes,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_bode(
    data,
    colors={
      "magnitude": colors.COLOR_BLACK,
      "phase": colors.COLOR_BLACK,
    },
    legend=False,
  )
  _ = mpl.plot_bode(
    fit,
    line=True,
    figure=figure,
    axes=axes,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_residuals(fit)
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage


plot_kramers_kronig_tests
~~~~~~~~~~~~~~~~~~~~~~~~~
:func:`~pyimpspec.mpl.plot_kramers_kronig_tests`

* :func:`~pyimpspec.mpl.plot_pseudo_chisqr`
* :func:`~pyimpspec.mpl.plot_num_RC_suggestion`
* :func:`~pyimpspec.mpl.plot_residuals`
* :func:`~pyimpspec.mpl.plot_nyquist`
* :func:`~pyimpspec.mpl.plot_bode`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  import pyimpspec.plot.colors as colors

  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  tests = pyimpspec.analysis.kramers_kronig.evaluate_log_F_ext(data)[0][1]

  suggestion = pyimpspec.analysis.kramers_kronig.suggest_num_RC(tests)
  test, scores, lower_limit, upper_limit = suggestion
  figure, axes = mpl.plot_kramers_kronig_tests(
    tests,
    suggestion,
    data,
    legend=False,
    colored_axes=True,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_pseudo_chisqr(tests, lower_limit=lower_limit, upper_limit=upper_limit)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_num_RC_suggestion(suggestion)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_residuals(test)
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_nyquist(
    data,
    colors={"impedance": colors.COLOR_BLACK},
    legend=False,
  )
  _ = mpl.plot_nyquist(
    test,
    line=True,
    figure=figure,
    axes=axes,
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_bode(
    data,
    colors={
      "magnitude": colors.COLOR_BLACK,
      "phase": colors.COLOR_BLACK,
    },
    legend=False,
  )
  _ = mpl.plot_bode(
    test,
    line=True,
    figure=figure,
    axes=axes,
  )
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage


plot_log_F_ext
~~~~~~~~~~~~~~
:func:`~pyimpspec.mpl.plot_log_F_ext`

.. plot::

  import pyimpspec
  from pyimpspec import mpl
  import pyimpspec.plot.colors as colors

  data = pyimpspec.generate_mock_data("CIRCUIT_1", noise=5e-2, seed=42)[0]
  evaluations = pyimpspec.analysis.kramers_kronig.evaluate_log_F_ext(data)

  figure, axes = mpl.plot_log_F_ext(
    evaluations,
    projection="3d",
  )
  figure.tight_layout()
  mpl.show()

  figure, axes = mpl.plot_log_F_ext(
    evaluations,
    projection="2d",
  )
  figure.tight_layout()
  mpl.show()

.. raw:: latex

    \clearpage