spacr.sp_stats
==============

.. py:module:: spacr.sp_stats




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

.. py:function:: choose_p_adjust_method(num_groups, num_data_points)

   Recommend a multiple-comparison correction method for the given design.

   :param num_groups: Number of unique groups being compared.
   :param num_data_points: Number of data points per group (balanced groups assumed).
   :returns: One of ``'holm'``, ``'fdr_bh'``, ``'sidak'``, or ``'bonferroni'``.


.. py:function:: perform_normality_tests(df, grouping_column, data_columns)

   Run per-group normality tests for each requested data column.

   Uses D'Agostino-Pearson when n>=8, Shapiro-Wilk otherwise, and skips groups
   with fewer than three observations.

   :param df: Input DataFrame containing the grouping and value columns.
   :param grouping_column: Column name identifying the group of each row.
   :param data_columns: Iterable of numeric column names to test.
   :returns: Tuple ``(is_normal, results)`` where ``is_normal`` is True when all
       p-values for the last examined column exceed 0.05 and ``results`` is a
       list of per-test dicts.


.. py:function:: perform_levene_test(df, grouping_column, data_column)

   Perform Levene's test for equal variance across the groups in ``df``.

   :param df: Input DataFrame containing the grouping and value columns.
   :param grouping_column: Column name identifying the group of each row.
   :param data_column: Numeric column to test.
   :returns: Tuple ``(statistic, p_value)`` returned by ``scipy.stats.levene``.


.. py:function:: perform_statistical_tests(df, grouping_column, data_columns, paired=False)

   Run an appropriate group-comparison test per data column.

   Picks T-test vs Mann-Whitney U for two groups (based on a normality check)
   and ANOVA vs Kruskal-Wallis for three or more.

   :param df: Input DataFrame containing the grouping and value columns.
   :param grouping_column: Column name identifying the group of each row.
   :param data_columns: Iterable of numeric column names to test.
   :param paired: When True, paired-sample analysis is requested (not implemented).
   :returns: List of per-column result dicts with test name, statistic, and p-value.


.. py:function:: perform_posthoc_tests(df, grouping_column, data_column, is_normal)

   Run pairwise post-hoc tests across groups with p-value adjustment.

   Uses Tukey HSD when data is normal, Dunn's test otherwise with a correction
   method chosen by :func:`choose_p_adjust_method`.

   :param df: Input DataFrame containing the grouping and value columns.
   :param grouping_column: Column name identifying the group of each row.
   :param data_column: Numeric column to compare across groups.
   :param is_normal: Whether the data satisfy the normality assumption.
   :returns: List of dicts with pairwise comparison metadata and p-values.


.. py:function:: chi_pairwise(raw_counts, verbose=False)

   Run pairwise chi-square (or Fisher's exact) tests across group pairs.

   Uses Fisher's exact for 2x2 contingency tables and chi-square otherwise,
   then applies a multiple-comparison correction selected via
   :func:`choose_p_adjust_method`.

   :param raw_counts: Contingency-table DataFrame indexed by group.
   :param verbose: When True, print the resulting DataFrame.
   :returns: DataFrame of pairwise results including raw and adjusted p-values
       and the correction method used.


