Pingouin

-----------------------

This is a minor release with several bugfixes, and major updates to the internal structure and sphinx documentation.

See the full `changelog for 0.5.5 <https://github.com/raphaelvallat/pingouin/releases/tag/v0.5.5>`_.

---------------------

This is a minor release with several bugfixes and no new features. The new version is tested for Python 3.8-3.11 (but should also work with Python 3.12). See the full `changelog for 0.5.4 <https://github.com/raphaelvallat/pingouin/releases/tag/v0.5.4>`_.

This release requires pandas≥1.5. We recommend scipy≥1.11.0.

*************

----------------------

**Bugfixes**

- Fixed a bug where the boolean value returned by :py:func:`pingouin.anderson` was inverted. It returned True when the data was NOT coming from the tested distribution, and vice versa. `PR 308 <https://github.com/raphaelvallat/pingouin/pull/308>`_.
- Fixed misleading documentation and ``input_type`` in the :py:func:`pingouin.convert_effsize` function. When converting from a Cohen's d effect size to a correlation coefficient, the resulting correlation is **not** a Pearson correlation but instead a `point-biserial correlation <https://en.wikipedia.org/wiki/Point-biserial_correlation_coefficient>`_. To avoid any confusion, ``input_type='r'`` has been deprecated and replaced with ``input_type='pointbiserialr'``. For more details, see `issue 302 <https://github.com/raphaelvallat/pingouin/issues/302>`_.

**New function**

We have added the :py:func:`pingouin.ptests` function to calculate a T-test (T- and p-values) between all pairs of columns in a given dataframe. This is the T-test equivalent of :py:func:`pingouin.rcorr`. It can only be used as a :py:class:`pandas.DataFrame` method, not as a standalone function. The output is a square dataframe with the T-values on the lower triangle and the p-values on the upper triangle.

.. code-block:: python

>>> import pingouin as pg
>>> df = pg.read_dataset('pairwise_corr').iloc[:30, 1:]
>>> df.columns = ["N", "E", "O", "A", "C"]
>>> df.ptests()
N E O A C
N - *** *** *** ***
E -8.397 - ***
O -8.585 -0.483 - ***
A -9.026 0.278 0.786 - ***
C -4.759 3.753 4.128 3.802 -

**Improvements**

- Effect sizes are now calculated using an exact method instead of an approximation based on T-values in :py:func:`pingouin.pairwise_tukey` and :py:func:`pingouin.pairwise_gameshowell`. `PR 328 <https://github.com/raphaelvallat/pingouin/pull/328>`_.
- :py:func:`pingouin.normality` does not raise an AssertionError anymore if one of the groups in ``group`` has ≤ 3 samples. `PR 324 <https://github.com/raphaelvallat/pingouin/pull/324>`_.
- 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 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 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>`_.

*************

------------------

**Bugfixes**

a. The eta-squared (``n2``) effect size was not properly calculated in one-way and two-way repeated measures ANOVAs. Specifically, Pingouin followed the same behavior as JASP, i.e. the eta-squared was the same as the partial eta-squared. However, as explained in `issue 251 <https://github.com/raphaelvallat/pingouin/issues/251>`_, this behavior is not valid. In one-way ANOVA design, the eta-squared should be equal to the generalized eta-squared. Note that, as of March 2022, this bug is also present in JASP. We have therefore updated the unit tests to use JAMOVI instead.

.. warning:: Please double check any effect sizes previously obtained with the :py:func:`pingouin.rm_anova` function.

b. Fixed invalid resampling behavior for bivariate functions in :py:func:`pingouin.compute_bootci` when x and y were not paired. `PR 281 <https://github.com/raphaelvallat/pingouin/pull/281>`_.
c. Fixed bug where ``confidence`` (previously ``ci``) was ignored when calculating the bootstrapped confidence intervals in :py:func:`pingouin.plot_shift`. `PR 282 <https://github.com/raphaelvallat/pingouin/pull/282>`_.

**Enhancements**

a. The :py:func:`pingouin.pairwise_ttests` has been renamed to :py:func:`pingouin.pairwise_tests`. Non-parametric tests are also supported in this function with the `parametric=False` argument, and thus the name "ttests" was misleading (see `issue 209 <https://github.com/raphaelvallat/pingouin/issues/209>`_).
b. Allow :py:func:`pingouin.bayesfactor_binom` to take Beta alternative model. `PR 252 <https://github.com/raphaelvallat/pingouin/pull/252>`_.
c. Allow keyword arguments for logistic regression in :py:func:`pingouin.mediation_analysis`. `PR 245 <https://github.com/raphaelvallat/pingouin/pull/245>`_.
d. Speed improvements for the Holm and FDR correction in :py:func:`pingouin.multicomp`. `PR 271 <https://github.com/raphaelvallat/pingouin/pull/271>`_.
e. Speed improvements univariate functions in :py:func:`pingouin.compute_bootci` (e.g. ``func="mean"`` is now vectorized).
f. Rename ``eta`` to ``eta_squared`` in :py:func:`pingouin.power_anova` and :py:func:`pingouin.power_rm_anova` to avoid any confusion. `PR 280 <https://github.com/raphaelvallat/pingouin/pull/280>`_.
g. Use `black <https://black.readthedocs.io/en/stable/>`_ code formatting.
h. Add support for `DataMatrix <https://pydatamatrix.eu/>`_ objects. `PR 286 <https://github.com/raphaelvallat/pingouin/pull/286>`_.

**Dependencies**

a. Force scikit-learn<1.1.0 to avoid bug in :py:func:`pingouin.logistic_regression`. `PR 272 <https://github.com/raphaelvallat/pingouin/issues/272>`_.

*************

----------------------

This is a minor release, with several bugfixes and improvements. This release is compatible with SciPy 1.8 and Pandas 1.4.

**Bugfixes**

a. Added support for SciPy 1.8 and Pandas 1.4. `PR 234 <https://github.com/raphaelvallat/pingouin/pull/234>`_.
b. Fixed bug where :py:func:`pingouin.rm_anova` and :py:func:`pingouin.mixed_anova` changed the dtypes of categorical columns in-place (`issue 224 <https://github.com/raphaelvallat/pingouin/issues/224>`_).

**Enhancements**

a. Faster implementation of :py:func:`pingouin.gzscore`, adding all options available in zscore: axis, ddof and nan_policy. Warning: this functions is deprecated and will be removed in pingouin 0.7.0 (use :py:func:`scipy.stats.gzscore` instead). `PR 210 <https://github.com/raphaelvallat/pingouin/pull/210>`_.
b. Replace use of statsmodels' studentized range distribution functions with more SciPy's more accurate :py:func:`scipy.stats.studentized_range`. `PR 229 <https://github.com/raphaelvallat/pingouin/pull/229>`_.
c. Add support for optional keywords argument in the :py:func:`pingouin.homoscedasticity` function (`issue 218 <https://github.com/raphaelvallat/pingouin/issues/218>`_).
d. Add support for the Jarque-Bera test in :py:func:`pingouin.normality` (`issue 216 <https://github.com/raphaelvallat/pingouin/issues/216>`_).

Lastly, we have also deprecated the Gitter forum in favor of `GitHub Discussions <https://github.com/raphaelvallat/pingouin/discussions>`_. Please use Discussions to ask questions, share ideas / tips and engage with the Pingouin community!

*************

---------------------

This is a MAJOR RELEASE with several important bugfixes. We recommend all users to upgrade to this new version.

**BUGFIX - Repeated measurements**

This release fixes several critical issues related to how Pingouin handles missing values in repeated measurements. The following functions have been corrected:

- :py:func:`pingouin.rm_anova`
- :py:func:`pingouin.mixed_anova`
- :py:func:`pingouin.pairwise_ttests`, only for mixed design or two-way repeated measures design.

A full description of the issue, with code and example, can be found at: https://github.com/raphaelvallat/pingouin/issues/206. In short, in Pingouin <0.5.0, listwise deletion of subjects (or rows) with missing values was not strictly enforced in repeated measures or mixed ANOVA, depending on the input data format (if missing values were explicit or implicit).
Pingouin 0.5.0 now uses a stricter complete-case analysis regardless of the input data format, which is the same behavior as JASP.

Furthermore, the :py:func:`pingouin.remove_rm_na` has been deprecated. Instead, listwise deletion of rows with missing values in repeated measurements is now performed using:

.. code-block:: python

>>> data_piv = data.pivot_table(index=subject, columns=within, values=dv)
>>> data_piv = data_piv.dropna() Listwise deletion
>>> data = data_piv.melt(ignore_index=False, value_name=dv).reset_index()

**BUGFIX - Strict listwise deletion in pairwise_ttests when repeated measures are present**

This is related to the previous issue. In mixed design, listwise deletion (complete-case analysis) was not strictly enforced in :py:func:`pingouin.pairwise_ttests` for the between-subject and interaction T-tests. In other words, the between-subject and interaction T-tests were calculated using a pairwise-deletion approach, even with ``nan_policy="pairwise"``.
The same issue occured in two-way repeated measures design, in which no strict listwise deletion was performed prior to calculating the T-tests, even with ``nan_policy="pairwise"``.

This has now been fixed such that Pingouin will always perform a strict listwise deletion whenever repeated measurements are present when ``nan_policy="listwise"`` (default). This complete-case analysis behavior can be disabled with ``nan_policy="pairwise"``, in which case missing values will be removed separately for each contrast. This may not be appropriate for post-hoc analysis following a repeated measures or mixed ANOVA, which is always conducted on complete-case data.

**BUGFIX - Homoscedasticity**

The :py:func:`pingouin.homoscedasticity` gave WRONG results for wide-format dataframes because the test was incorrectly calculated on the transposed data. See `issue 204 <https://github.com/raphaelvallat/pingouin/issues/204>`_.

**Enhancements**

a. Partial correlation functions (:py:func:`pingouin.pcorr` and :py:func:`pingouin.partial_corr`) now use :py:func:`numpy.linalg.pinv` with `hermitian=True`, which improves numerical stability. See `issue 198 <https://github.com/raphaelvallat/pingouin/issues/198>`_.
b. Added support for integer column names in most functions. Previously, Pingouin raised an error if the column names were integers. See `issue 201 <https://github.com/raphaelvallat/pingouin/issues/201>`_.
c. :py:func:`pingouin.pairwise_corr` now works when the column names of the dataframe are integer, and better support numpy.arrays in the ``columns`` argument.
d. Added support for wide-format dataframe in :py:func:`pingouin.friedman` and :py:func:`pingouin.cochran`

*************