drippy.univariate
=================

.. py:module:: drippy.univariate

.. autoapi-nested-parse::

   Plotting functions for univariate models (y = c + e).



Attributes
----------

.. autoapisummary::

   drippy.univariate._ORDERED_VALUES


Functions
---------

.. autoapisummary::

   drippy.univariate.run_sequence_plot
   drippy.univariate.lag_plot
   drippy.univariate.histogram
   drippy.univariate.normal_probability_plot
   drippy.univariate.four_plot
   drippy.univariate.ppcc_plot
   drippy.univariate.weibull_plot
   drippy.univariate.probability_plot
   drippy.univariate.box_cox_normality_plot
   drippy.univariate.bootstrap_plot
   drippy.univariate.box_cox_linearity_plot


Module Contents
---------------

.. py:data:: _ORDERED_VALUES
   :value: 'Ordered Values'


.. py:function:: run_sequence_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a run sequence plot of y vs index or continuous index t.

   :param data: EDAData container. Uses t as x-axis if present, else index.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.

   :returns: The figure and axes containing the plot.


.. py:function:: lag_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, lag: int = 1) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a lag plot of the data.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param lag: Number of lags. Must be positive and less than len(y).

   :returns: The figure and axes containing the plot.


.. py:function:: histogram(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, bins: int | str = 'auto') -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a histogram of the data.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param bins: Number of bins or bin strategy.

   :returns: The figure and axes containing the plot.


.. py:function:: normal_probability_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, *, return_rsquared: bool = False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes, float | None]

   Creates a normal probability plot.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param return_rsquared: If True, includes R-squared as the third element.

   :returns: (fig, ax, r_squared) where r_squared is None if return_rsquared
             is False.


.. py:function:: four_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, axes: numpy.ndarray | None = None) -> tuple[matplotlib.figure.Figure, numpy.ndarray]

   Creates a 4-plot (run sequence, lag, histogram, normal probability).

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param axes: ndarray of Axes with shape (2, 2). If None, creates new axes.

   :returns: (fig, axes_flat) where axes_flat has shape (4,).


.. py:function:: ppcc_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: numpy.ndarray | None = None, rough_range: tuple[float, float] = (-2, 2), n_rough: int = 50, n_fine: int = 100) -> tuple[matplotlib.figure.Figure, numpy.ndarray]

   Creates a PPCC plot (rough + fine) for distribution shape estimation.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: ndarray of Axes with shape (2,). If None, creates new axes.
   :param rough_range: (min, max) range for rough search.
   :param n_rough: Points in rough plot.
   :param n_fine: Points in fine plot.

   :returns: (fig, axes) where axes has shape (2,).


.. py:function:: weibull_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a Weibull probability plot.

   :param data: EDAData container. Requires y > 0.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.

   :returns: The figure and axes containing the plot.


.. py:function:: probability_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, distribution: str = 'norm') -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a probability plot for a specified distribution.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param distribution: scipy.stats distribution name.

   :returns: The figure and axes containing the plot.


.. py:function:: box_cox_normality_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, axes: numpy.ndarray | None = None) -> tuple[matplotlib.figure.Figure, numpy.ndarray]

   Creates a Box-Cox normality plot (2x2 grid).

   Shows: original histogram, Box-Cox normality curve, transformed
   histogram, normal probability plot of transformed data.

   :param data: EDAData container. Requires y > 0.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param axes: ndarray of Axes with shape (2, 2). If None, creates new.

   :returns: (fig, axes) where axes has shape (2, 2).


.. py:function:: bootstrap_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, statistic: collections.abc.Callable = np.mean, n_bootstrap: int = 10000) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a bootstrap distribution plot.

   :param data: EDAData container. Requires y.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param statistic: Callable to bootstrap. Must be callable.
   :param n_bootstrap: Number of bootstrap resamples.

   :returns: The figure and axes containing the plot.


.. py:function:: box_cox_linearity_plot(data: drippy.data.EDAData, fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes.Axes | None = None, lmbda_range: tuple[float, float] = (-2, 2), n: int = 100) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

   Creates a Box-Cox linearity plot.

   Plots ``abs(corr(Y, X^λ))`` across a range of λ values to find the
   power transformation of X that maximises linearity with Y.

   :param data: EDAData container. Requires x > 0.
   :param fig: Matplotlib figure. If None, creates new figure.
   :param ax: Matplotlib axes. If None, creates new axes.
   :param lmbda_range: (min, max) range of λ to evaluate.
   :param n: Number of λ values to evaluate.

   :returns: The figure and axes containing the plot.