Plotting seaborn.FacetGrid compatibility (#314)

* remove all fig and dpi arguments, instead generate default axis if no ax passed

* set equal aspect manually in docstring demos for qqplot and circmean

* rm qqplot title

* move scatter_kws keyword to kwargs and color LOA span to match scatter

* add qqplot kwargs for scatter

* remove all fig and dpi arguments, instead generate default axis if no ax passed

* set equal aspect manually in docstring demos for qqplot and circmean

* rm qqplot title

* move scatter_kws keyword to kwargs and color LOA span to match scatter

* add qqplot kwargs for scatter

* Added square keyword argument to qqplot and plot_circmean

* updated changelog

* Updated plotting tests

* update docstring for lint passing

* update kwargs using .update instead of | for prior Python compatibility

* Conform kwargs updating to match other pinguoin functions

* add scatter kwargs to unittests

* Minor documentation update

:py:method: not working + add ptests to API

Co-authored-by: Raphael Vallat <raphaelvallat9@gmail.com>

Author: remrama

docs/api.rst

@@ -24,6 +24,7 @@ ANOVA and T-test
     welch_anova
     tost
     ttest
+    ptests
 
 Bayesian
 --------
@@ -125,6 +126,7 @@ Multiple comparisons and post-hoc tests
     pairwise_tests
     pairwise_tukey
     pairwise_gameshowell
+    ptests
     multicomp
 
 Multivariate tests

docs/changelog.rst

@@ -28,6 +28,7 @@ We have added the :py:func:`pingouin.ptests` function to calculate a T-test (T-
 **Improvements**
 
 - Added customization options to :py:func:`pingouin.plot_rm_corr`, which now takes optional keyword arguments to pass through to :py:func:`seaborn.regplot` and :py:func:`seaborn.scatterplot`. `PR 312 <https://github.com/raphaelvallat/pingouin/pull/312>`_.
+- Changed some plotting functions to increase compatibility with :py:class:`seaborn.FacetGrid`. As explained in `issue 306 <https://github.com/raphaelvallat/pingouin/issues/306>`_, the major change is to generate :py:class:`matplotlib.axes` using default parameters instead of accepting ``fig`` and ``dpi`` keyword arguments. This change applies to :py:func:`pingouin.plot_blandaltman`, :py:func:`pingouin.plot_paired`, :py:func:`pingouin.plot_circmean`, and :py:func:`pingouin.qqplot`. In the future, open a :py:class:`matplotlib.axes` and pass it through using the ``ax`` parameter to use custom figure settings with these functions. Other minor changes include the addition of the ``square`` keyword argument to :py:func`pingouin.plot_circmean` and :py:func`pingouin.qqplot` to ensure equal aspect ratios, and the removal of ``scatter_kws`` as a keyword argument in :py:func:`pingouin.plot_blandaltmann` (now alter the scatter parameters using general ``**kwargs``). `PR 314 <https://github.com/raphaelvallat/pingouin/pull/314>`_.
 
 *************
 

docs/index.rst

@@ -470,7 +470,7 @@ Plot the curve of achieved power given the effect size (Cohen d) and the sample
     import pingouin as pg
     import numpy as np
     df = pg.read_dataset('mixed_anova').query("Group == 'Meditation' and Time != 'January'")
-    ax = pg.plot_paired(data=df, dv='Scores', within='Time', subject='Subject', dpi=150)
+    ax = pg.plot_paired(data=df, dv='Scores', within='Time', subject='Subject')
     ax.set_title("Effect of meditation on school performance")
 
 Integration with Pandas

pingouin/plotting.py

@@ -26,16 +26,7 @@
 
 
 def plot_blandaltman(
-    x,
-    y,
-    agreement=1.96,
-    xaxis="mean",
-    confidence=0.95,
-    annotate=True,
-    scatter_kws=dict(color="tab:blue", alpha=0.8),
-    figsize=(4.5, 4.5),
-    dpi=100,
-    ax=None,
+    x, y, agreement=1.96, xaxis="mean", confidence=0.95, annotate=True, ax=None, **kwargs
 ):
     """
     Generate a Bland-Altman plot to compare two sets of measurements.
@@ -61,15 +52,10 @@ def plot_blandaltman(
     annotate : bool
         If True (default), annotate the values for the mean difference
         and agreement limits.
-    scatter_kws : dict
-        Additional keyword arguments passed to
-        :py:func:`matplotlib.pyplot.scatter`.
-    figsize : tuple
-        Figsize in inches
-    dpi : int
-        Resolution of the figure in dots per inches.
     ax : matplotlib axes
         Axis on which to draw the plot.
+    **kwargs : optional
+        Optional argument(s) passed to :py:func:`matplotlib.pyplot.scatter`.
 
     Returns
     -------
@@ -137,6 +123,10 @@ def plot_blandaltman(
     assert not np.isnan(x).any(), "Missing values in x or y are not supported."
     assert not np.isnan(y).any(), "Missing values in x or y are not supported."
 
+    # Update default kwargs with specified inputs
+    _scatter_kwargs = {"color": "tab:blue", "alpha": 0.8}
+    _scatter_kwargs.update(kwargs)
+
     # Calculate mean, STD and SEM of x - y
     n = x.size
     dof = n - 1
@@ -162,10 +152,10 @@ def plot_blandaltman(
 
     # Start the plot
     if ax is None:
-        fig, ax = plt.subplots(1, 1, figsize=figsize, dpi=dpi)
+        ax = plt.gca()
 
     # Plot the mean diff, limits of agreement and scatter
-    ax.scatter(xval, diff, **scatter_kws)
+    ax.scatter(xval, diff, **_scatter_kwargs)
     ax.axhline(mean_diff, color="k", linestyle="-", lw=2)
     ax.axhline(high, color="k", linestyle=":", lw=1.5)
     ax.axhline(low, color="k", linestyle=":", lw=1.5)
@@ -193,10 +183,10 @@ def plot_blandaltman(
         ci["high"] = stats.t.interval(confidence, dof, loc=high, scale=high_low_se)
         ci["low"] = stats.t.interval(confidence, dof, loc=low, scale=high_low_se)
         ax.axhspan(ci["mean"][0], ci["mean"][1], facecolor="tab:grey", alpha=0.2)
-        ax.axhspan(ci["high"][0], ci["high"][1], facecolor="tab:blue", alpha=0.2)
-        ax.axhspan(ci["low"][0], ci["low"][1], facecolor="tab:blue", alpha=0.2)
+        ax.axhspan(ci["high"][0], ci["high"][1], facecolor=_scatter_kwargs["color"], alpha=0.2)
+        ax.axhspan(ci["low"][0], ci["low"][1], facecolor=_scatter_kwargs["color"], alpha=0.2)
 
-    # Labels and title
+    # Labels
     ax.set_ylabel(f"{xname} - {yname}")
     ax.set_xlabel(xlabel)
     sns.despine(ax=ax)
@@ -226,7 +216,7 @@ def _ppoints(n, a=0.5):
     return (np.arange(n) + 1 - a) / (n + 1 - 2 * a)
 
 
-def qqplot(x, dist="norm", sparams=(), confidence=0.95, figsize=(5, 4), ax=None):
+def qqplot(x, dist="norm", sparams=(), confidence=0.95, square=True, ax=None, **kwargs):
     """Quantile-Quantile plot.
 
     Parameters
@@ -242,10 +232,12 @@ def qqplot(x, dist="norm", sparams=(), confidence=0.95, figsize=(5, 4), ax=None)
     confidence : float
         Confidence level (.95 = 95%) for point-wise confidence envelope.
         Can be disabled by passing False.
-    figsize : tuple
-        Figsize in inches
+    square: bool
+        If True (default), ensure equal aspect ratio between X and Y axes.
     ax : matplotlib axes
         Axis on which to draw the plot
+    **kwargs : optional
+        Optional argument(s) passed to :py:func:`matplotlib.pyplot.scatter`.
 
     Returns
     -------
@@ -336,6 +328,10 @@ def qqplot(x, dist="norm", sparams=(), confidence=0.95, figsize=(5, 4), ax=None)
         >>> sns.set_style('darkgrid')
         >>> ax = pg.qqplot(x, dist='norm', sparams=(mean, std))
     """
+    # Update default kwargs with specified inputs
+    _scatter_kwargs = {"marker": "o", "color": "blue"}
+    _scatter_kwargs.update(kwargs)
+
     if isinstance(dist, str):
         dist = getattr(stats, dist)
 
@@ -370,13 +366,12 @@ def qqplot(x, dist="norm", sparams=(), confidence=0.95, figsize=(5, 4), ax=None)
 
     # Start the plot
     if ax is None:
-        fig, ax = plt.subplots(1, 1, figsize=figsize)
+        ax = plt.gca()
 
-    ax.plot(theor, observed, "bo")
+    ax.scatter(theor, observed, **_scatter_kwargs)
 
     ax.set_xlabel("Theoretical quantiles")
     ax.set_ylabel("Ordered quantiles")
-    ax.set_title("Q-Q Plot")
 
     # Add diagonal line
     end_pts = [ax.get_xlim(), ax.get_ylim()]
@@ -405,6 +400,10 @@ def qqplot(x, dist="norm", sparams=(), confidence=0.95, figsize=(5, 4), ax=None)
         ax.plot(theor, upper, "r--", lw=1.25)
         ax.plot(theor, lower, "r--", lw=1.25)
 
+    # Make square
+    if square:
+        ax.set_aspect("equal")
+
     return ax
 
 
@@ -417,8 +416,6 @@ def plot_paired(
     boxplot=True,
     boxplot_in_front=False,
     orient="v",
-    figsize=(4, 4),
-    dpi=100,
     ax=None,
     colors=["green", "grey", "indianred"],
     pointplot_kwargs={"scale": 0.6, "marker": "."},
@@ -455,10 +452,6 @@ def plot_paired(
         by 90 degrees.
 
         .. versionadded:: 0.3.9
-    figsize : tuple
-        Figsize in inches
-    dpi : int
-        Resolution of the figure in dots per inches.
     ax : matplotlib axes
         Axis on which to draw the plot.
     colors : list of str
@@ -491,8 +484,7 @@ def plot_paired(
         >>> import pingouin as pg
         >>> df = pg.read_dataset('mixed_anova').query("Time != 'January'")
         >>> df = df.query("Group == 'Meditation' and Subject > 40")
-        >>> ax = pg.plot_paired(data=df, dv='Scores', within='Time',
-        ...                     subject='Subject', dpi=150)
+        >>> ax = pg.plot_paired(data=df, dv='Scores', within='Time', subject='Subject')
 
     Paired plot on an existing axis (no boxplot and uniform color):
 
@@ -583,7 +575,7 @@ def plot_paired(
 
     # Start the plot
     if ax is None:
-        fig, ax = plt.subplots(1, 1, figsize=figsize, dpi=dpi)
+        ax = plt.gca()
 
     # Set x and y depending on orientation using the num. replacement within
     _x = "wthn" if orient == "v" else dv
@@ -1028,8 +1020,7 @@ def plot_rm_corr(
 
 def plot_circmean(
     angles,
-    figsize=(4, 4),
-    dpi=None,
+    square=True,
     ax=None,
     kwargs_markers=dict(color="tab:blue", marker="o", mfc="none", ms=10),
     kwargs_arrow=dict(width=0.01, head_width=0.1, head_length=0.1, fc="tab:red", ec="tab:red"),
@@ -1043,10 +1034,8 @@ def plot_circmean(
     ----------
     angles : array or list
         Angles (expressed in radians). Only 1D array are supported here.
-    figsize : tuple
-        Figsize in inches. Default is (4, 4).
-    dpi : int
-        Resolution of the figure in dots per inches.
+    square: bool
+        If True (default), ensure equal aspect ratio between X and Y axes.
     ax : matplotlib axes
         Axis on which to draw the plot.
     kwargs_markers : dict
@@ -1077,9 +1066,11 @@ def plot_circmean(
     .. plot::
 
         >>> import pingouin as pg
+        >>> import matplotlib.pyplot as plt
+        >>> _, ax = plt.subplots(1, 1, figsize=(3, 3))
         >>> ax = pg.plot_circmean([0.05, -0.8, 1.2, 0.8, 0.5, -0.3, 0.3, 0.7],
         ...                       kwargs_markers=dict(color='k', mfc='k'),
-        ...                       kwargs_arrow=dict(ec='k', fc='k'))
+        ...                       kwargs_arrow=dict(ec='k', fc='k'), ax=ax)
 
     .. plot::
 
@@ -1128,7 +1119,8 @@ def plot_circmean(
     zm = r * np.exp(1j * phi)
 
     # Plot unit circle
-    fig, ax = plt.subplots(figsize=figsize, dpi=dpi)
+    if ax is None:
+        ax = plt.gca()
     circle = Circle((0, 0), 1, edgecolor="k", facecolor="none", linewidth=2)
     ax.add_patch(circle)
     ax.axvline(0, lw=1, ls=":", color="slategrey")
@@ -1149,4 +1141,8 @@ def plot_circmean(
     ax.text(-1.3, 0, r"$\pi$", verticalalignment="center")
     ax.text(0, 1.2, r"$+\pi/2$", horizontalalignment="center")
     ax.text(0, -1.3, r"$-\pi/2$", horizontalalignment="center")
+
+    # Make square
+    if square:
+        ax.set_aspect("equal")
     return ax

pingouin/tests/test_plotting.py

@@ -34,15 +34,15 @@ def test_plot_blandaltman(self):
         assert isinstance(ax, matplotlib.axes.Axes)
         _, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4))
         plot_blandaltman(x, y, agreement=2, confidence=None, ax=ax1)
-        plot_blandaltman(x, y, agreement=2, confidence=0.68, dpi=200, ax=ax2)
+        plot_blandaltman(x, y, agreement=2, confidence=0.68, ax=ax2)
         plt.close("all")
         # With Pingouin's dataset
         df_ba = read_dataset("blandaltman")
         x, y = df_ba["A"], df_ba["B"]
         plot_blandaltman(x, y)
         plot_blandaltman(x, y, annotate=False)
         plot_blandaltman(x, y, xaxis="x", confidence=None)
-        plot_blandaltman(x, y, xaxis="y")
+        plot_blandaltman(x, y, xaxis="y", color="green", s=10)
         plt.close("all")
 
     def test_ppoints(self):
@@ -78,7 +78,7 @@ def test_qqplot(self):
         ax = qqplot(x, dist="norm")
         assert isinstance(ax, matplotlib.axes.Axes)
         _, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4))
-        qqplot(x_exp, dist="expon", ax=ax2)
+        qqplot(x_exp, dist="expon", ax=ax2, color="black", marker="+")
         mean, std = 0, 0.8
         qqplot(x, dist=stats.norm, sparams=(mean, std), confidence=False)
         # For lognormal distribution, the shape parameter must be specified
@@ -164,6 +164,6 @@ def test_plot_circmean(self):
         angles = np.array([0.02, 0.07, -0.12, 0.14, 1.2, -1.3])
         ax = plot_circmean(angles)
         assert isinstance(ax, matplotlib.axes.Axes)
-        ax = plot_circmean(angles, figsize=(5, 5), dpi=100, kwargs_markers={}, kwargs_arrow={})
+        ax = plot_circmean(angles, kwargs_markers={}, kwargs_arrow={})
         assert isinstance(ax, matplotlib.axes.Axes)
         plt.close("all")