nltools 0.6.0.dev0__py3-none-any.whl

nltools/algorithms/outliers.py

@@ -0,0 +1,308 @@
+"""Outlier detection, robust statistics, and data normalization."""
+
+import numpy as np
+import polars as pl
+import nibabel as nib
+
+
+def zscore(data):
+    """Z-score every column of a Polars or pandas DataFrame/Series.
+
+    Pandas inputs are converted to Polars; the result is always Polars (a
+    DataFrame for DataFrame input, a Series for Series input).
+
+    Args:
+        data (pl.DataFrame | pl.Series | pd.DataFrame | pd.Series): Data to z-score.
+
+    Returns:
+        pl.DataFrame | pl.Series: Same shape as the input, each column z-scored
+            with the sample standard deviation (ddof=1).
+    """
+    import pandas as pd
+
+    return_series = False
+    if isinstance(data, pd.DataFrame):
+        df = pl.from_pandas(data)
+    elif isinstance(data, pd.Series):
+        df = pl.DataFrame({data.name or "0": data})
+        return_series = True
+    elif isinstance(data, pl.DataFrame):
+        df = data
+    elif isinstance(data, pl.Series):
+        df = pl.DataFrame({data.name or "0": data})
+        return_series = True
+    else:
+        raise ValueError("Data must be a Polars or pandas DataFrame or Series")
+
+    result = df.select(
+        [
+            ((pl.col(c) - pl.col(c).mean()) / pl.col(c).std()).alias(c)
+            for c in df.columns
+        ]
+    )
+
+    if return_series:
+        return result.to_series(0)
+    return result
+
+
+def winsorize(data, cutoff=None, replace_with_cutoff=True):
+    """Winsorize a Polars DataFrame/Series with the largest/lowest value not considered outlier.
+
+    Args:
+        data (pl.DataFrame | pl.Series): Data to winsorize.
+        cutoff (dict): A dictionary with keys `{'std': [low, high]}` or
+            `{'quantile': [low, high]}`.
+        replace_with_cutoff (bool): If True, replace outliers with the cutoff
+            value; if False, replace them with the closest existing values
+            (default: True).
+
+    Returns:
+        pl.DataFrame | pl.Series: Winsorized data, the same type as the input.
+    """
+    return _transform_outliers(
+        data, cutoff, replace_with_cutoff=replace_with_cutoff, method="winsorize"
+    )
+
+
+def trim(data, cutoff=None):
+    """Trim a Polars DataFrame/Series by replacing outlier values with NaNs.
+
+    Args:
+        data (pl.DataFrame | pl.Series): Data to trim.
+        cutoff (dict): A dictionary with keys `{'std': [low, high]}` or
+            `{'quantile': [low, high]}`.
+
+    Returns:
+        pl.DataFrame | pl.Series: Trimmed data (outliers replaced with NaN), the
+            same type as the input.
+    """
+    return _transform_outliers(data, cutoff, replace_with_cutoff=None, method="trim")
+
+
+def _transform_outliers(data, cutoff, replace_with_cutoff, method):
+    """Winsorize or trim outliers in a Polars DataFrame/Series (shared by `trim` and `winsorize`).
+
+    Args:
+        data (pl.DataFrame | pl.Series): Data to transform.
+        cutoff (dict): A dictionary with keys `{'std': [low, high]}` or
+            `{'quantile': [low, high]}`.
+        replace_with_cutoff (bool | None): For winsorizing, replace outliers with
+            the cutoff value (True) or with the closest existing value (False).
+            Ignored when trimming.
+        method (str): 'winsorize' or 'trim'.
+
+    Returns:
+        pl.DataFrame | pl.Series: Transformed data, the same type as the input.
+    """
+    return_series = False
+    if isinstance(data, pl.DataFrame):
+        df = data.clone()
+    elif isinstance(data, pl.Series):
+        df = pl.DataFrame({data.name or "0": data})
+        return_series = True
+    else:
+        raise ValueError("Data must be a Polars DataFrame or Series")
+
+    # Transform each column if a DataFrame, if Series just transform data
+    transformed_cols = []
+    for col in df.columns:
+        # Get the series for calculations
+        series = df[col]
+
+        # Calculate cutoff values
+        if isinstance(cutoff, dict):
+            if "quantile" in cutoff:
+                quantiles = cutoff["quantile"]
+                # Use numpy quantile to match pandas interpolation behavior
+                series_array = series.to_numpy()
+                lower_q = float(np.quantile(series_array, quantiles[0]))
+                upper_q = (
+                    float(np.quantile(series_array, quantiles[1]))
+                    if len(quantiles) > 1
+                    else lower_q
+                )
+            elif "std" in cutoff:
+                mean_val = series.mean()
+                std_val = series.std()
+                lower_q = mean_val - std_val * cutoff["std"][0]
+                upper_q = mean_val + std_val * cutoff["std"][1]
+            else:
+                raise ValueError(
+                    "cutoff must be a dictionary with quantile or std keys."
+                )
+
+            # If replace_with_cutoff is false, replace with true existing values closest to cutoff
+            if method == "winsorize" and not replace_with_cutoff:
+                filtered_lower = series.filter(series > lower_q)
+                filtered_upper = series.filter(series < upper_q)
+                if len(filtered_lower) > 0:
+                    lower_q = filtered_lower.min()
+                if len(filtered_upper) > 0:
+                    upper_q = filtered_upper.max()
+
+            # Apply transformation using Polars expressions with column reference
+            if method == "trim":
+                # Replace outliers with null (NaN)
+                transformed_expr = (
+                    pl.when(pl.col(col) < lower_q)
+                    .then(None)
+                    .when(pl.col(col) > upper_q)
+                    .then(None)
+                    .otherwise(pl.col(col))
+                )
+            elif method == "winsorize":
+                # Replace outliers with cutoff values
+                transformed_expr = (
+                    pl.when(pl.col(col) < lower_q)
+                    .then(lower_q)
+                    .when(pl.col(col) > upper_q)
+                    .then(upper_q)
+                    .otherwise(pl.col(col))
+                )
+            else:
+                raise ValueError(f"Unknown method: {method}")
+
+            transformed_cols.append(transformed_expr.alias(col))
+        else:
+            raise ValueError("cutoff must be a dictionary with quantile or std keys.")
+
+    # Use with_columns to update all columns at once
+    result_df = df.with_columns(transformed_cols)
+
+    # Return Series if input was Series, otherwise DataFrame
+    if return_series:
+        return result_df.to_series(0)
+    return result_df
+
+
+def find_spikes(
+    data,
+    global_spike_cutoff=3,
+    diff_spike_cutoff=3,
+    *,
+    TR: float | None = None,
+    sampling_freq: float | None = None,
+):
+    """Identify spikes (motion artifacts, intensity outliers) in 4D fMRI data.
+
+    Args:
+        data (BrainData | nib.Nifti1Image): 4D functional data.
+        global_spike_cutoff (float | None): Cutoff in standard deviations for
+            spikes in the per-TR global mean signal; None skips this detector.
+            Defaults to 3.
+        diff_spike_cutoff (float | None): Cutoff in standard deviations for
+            spikes in the per-TR mean absolute frame-to-frame difference; None
+            skips this detector. Defaults to 3.
+        TR (float | None): Repetition time in seconds; sets the returned
+            DesignMatrix's `sampling_freq` for downstream `.append()` /
+            `.convolve()`. Pass at most one of `TR` and `sampling_freq`.
+        sampling_freq (float | None): Sampling frequency in Hz (1 / TR). See `TR`.
+
+    Returns:
+        DesignMatrix: One indicator column per detected spike TR, named
+            `.nl_global_spike{n}` / `.nl_diff_spike{n}` in the reserved namespace
+            for generated columns (see `RESERVED_PREFIX`) and pre-marked as
+            confounds. Row position is the time axis. A volume flagged by both
+            detectors yields identical one-hot columns, so only the
+            `.nl_global_spike*` one is kept. Without `TR` / `sampling_freq` the
+            result has `sampling_freq=None` and can still be appended to a
+            DesignMatrix that has one.
+    """
+
+    from nltools.data import BrainData
+
+    if (global_spike_cutoff is None) & (diff_spike_cutoff is None):
+        raise ValueError("Did not input any cutoffs to identify spikes in this data.")
+
+    if isinstance(data, BrainData):
+        # Avoid deepcopy overhead - just copy the data array
+        data_array = data.data.copy()
+        global_mn = np.mean(data_array, axis=1)
+        frame_diff = np.mean(np.abs(np.diff(data_array, axis=0)), axis=1)
+    elif isinstance(data, nib.Nifti1Image):
+        # Avoid deepcopy overhead - just copy the data array
+        data_array = data.get_fdata().copy()
+        if len(data_array.shape) > 3:
+            data_array = np.squeeze(data_array)
+        elif len(data_array.shape) < 3:
+            raise ValueError("nibabel instance does not appear to be 4D data.")
+        global_mn = np.mean(data_array, axis=(0, 1, 2))
+        frame_diff = np.mean(np.abs(np.diff(data_array, axis=3)), axis=(0, 1, 2))
+    else:
+        raise ValueError(
+            "Currently this function can only accomodate BrainData and nibabel instances"
+        )
+
+    if global_spike_cutoff is not None:
+        # Vectorize outlier detection - avoid np.append in loops
+        global_mean = np.mean(global_mn)
+        global_std = np.std(global_mn)
+        upper_threshold = global_mean + global_std * global_spike_cutoff
+        lower_threshold = global_mean - global_std * global_spike_cutoff
+        global_outliers = np.where(
+            (global_mn > upper_threshold) | (global_mn < lower_threshold)
+        )[0]
+
+    if diff_spike_cutoff is not None:
+        # Vectorize outlier detection - avoid np.append in loops
+        diff_mean = np.mean(frame_diff)
+        diff_std = np.std(frame_diff)
+        upper_threshold = diff_mean + diff_std * diff_spike_cutoff
+        lower_threshold = diff_mean - diff_std * diff_spike_cutoff
+        frame_outliers = np.where(
+            (frame_diff > upper_threshold) | (frame_diff < lower_threshold)
+        )[0]
+    # Build spike regressors using Polars. Row position is the time axis;
+    # no separate "TR" index column (pandas-era artifact, dropped in v0.6.0).
+    outlier_data: dict[str, list[int]] = {}
+
+    if global_spike_cutoff is not None:
+        for i, loc in enumerate(global_outliers):
+            col_name = f"global_spike{i + 1}"
+            col_values = [0] * len(global_mn)
+            col_values[int(loc)] = 1
+            outlier_data[col_name] = col_values
+
+    if diff_spike_cutoff is not None:
+        for i, loc in enumerate(frame_outliers):
+            col_name = f"diff_spike{i + 1}"
+            col_values = [0] * len(global_mn)
+            col_values[int(loc)] = 1
+            outlier_data[col_name] = col_values
+
+    # Two detectors, one timeline: the same TR can be flagged by both, and a
+    # one-hot column per detection would then be literally duplicated —
+    # straight duplicate columns, which .append(axis=1) refuses. Deduplicate
+    # on the flagged position, keeping the global detection so the tie-break
+    # is deterministic rather than insertion-ordered. (Only the name is at
+    # stake: the colliding columns are bitwise identical.)
+    global_prefix = "global_spike"
+    seen: dict[int, str] = {}
+    for name in [c for c in outlier_data if c.startswith(global_prefix)] + [
+        c for c in outlier_data if not c.startswith(global_prefix)
+    ]:
+        loc = outlier_data[name].index(1)
+        if loc in seen:
+            del outlier_data[name]
+        else:
+            seen[loc] = name
+
+    if TR is not None and sampling_freq is not None:
+        raise ValueError(
+            "find_spikes: pass exactly one of `TR` or `sampling_freq`, not both."
+        )
+    if TR is not None:
+        sampling_freq = 1.0 / TR
+
+    from nltools.data.designmatrix.utils import _design_from_generated
+
+    # No spikes is a normal outcome, not an error. Polars cannot express
+    # "n rows, 0 columns", so hand the row count over explicitly — otherwise
+    # the result reports 0 rows and downstream `.append()` rejects it for not
+    # matching the rest of the design.
+    return _design_from_generated(
+        pl.DataFrame(outlier_data),
+        sampling_freq=sampling_freq,
+        n_rows=None if outlier_data else len(global_mn),
+    )

nltools/algorithms/regression.py

@@ -0,0 +1,83 @@
+"""Ordinary least squares on plain numpy arrays.
+
+`regress` fits `Y ~ X` and returns coefficients, standard errors,
+t-statistics, p-values, degrees of freedom, and residuals as arrays. Use it for
+quick regressions on tabular or behavioral data; for voxel-wise models on
+imaging data use `BrainData.fit(model='glm')`, which adds masking, run
+handling, and the modeling helpers.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import t as t_dist
+
+
+def regress(X, Y, *, stats: str = "full", tail: int | str = 2):
+    """Fit an OLS regression of `Y` on `X`.
+
+    Does not add an intercept; include one in `X` explicitly. If `Y` is 2D, a
+    separate regression is fit to each column.
+
+    Args:
+        X (np.ndarray): Design matrix, shape (n_samples, n_regressors).
+        Y (np.ndarray): Response, shape (n_samples,) or (n_samples, n_targets).
+        stats (str): 'full' returns the 6-tuple below, 'betas' returns just `b`,
+            'tstats' returns `(b, t)`. Defaults to 'full'.
+        tail (int | str): 2 or 'two' for two-tailed p-values (default); 1 or
+            'one' for a one-tailed test of beta > 0 (negate a regressor for the
+            other direction).
+
+    Returns:
+        tuple: `(b, se, t, p, df, res)` when `stats='full'`: coefficients,
+            standard errors, t-statistics, p-values (per `tail`), residual
+            degrees of freedom, and residuals. `stats='betas'` returns just `b`;
+            `stats='tstats'` returns `(b, t)`.
+    """
+    from .validation import _validate_tail_parameter
+
+    if stats not in ("full", "betas", "tstats"):
+        raise ValueError("stats must be one of 'full', 'betas', 'tstats'")
+    tail_internal = _validate_tail_parameter(tail)
+
+    X = np.asarray(X)
+    Y = np.asarray(Y)
+    y_was_1d = Y.ndim == 1
+    if y_was_1d:
+        Y = Y[:, np.newaxis]
+
+    b = np.linalg.pinv(X) @ Y  # (n_regressors, n_targets)
+    if stats == "betas":
+        return b.squeeze()
+
+    res = Y - X @ b
+    df_scalar = X.shape[0] - X.shape[1]
+    # Unbiased residual SE from *uncentered* RSS: sqrt(RSS / (n - p)). Correct for
+    # both intercept and intercept-free models. np.std(res, ddof=p) would center
+    # the residuals, underestimating RSS when X has no intercept (a supported
+    # usage — see the docstring). Matches stats/correlation.py; see GH #287.
+    sigma = np.sqrt((res**2).sum(axis=0) / df_scalar)  # (n_targets,)
+    xtx_inv_diag = np.diag(np.linalg.pinv(X.T @ X))  # (n_regressors,)
+    se = np.sqrt(xtx_inv_diag)[:, np.newaxis] * sigma[np.newaxis, :]
+
+    t = np.zeros_like(b)
+    mask = se > 1e-6
+    t[mask] = b[mask] / se[mask]
+
+    if stats == "tstats":
+        return b.squeeze(), t.squeeze()
+
+    df = np.full(t.shape[1], df_scalar)
+    if tail_internal == "upper":
+        p = 1 - t_dist.cdf(t, df)
+    else:
+        p = 2 * (1 - t_dist.cdf(np.abs(t), df))
+
+    return (
+        b.squeeze(),
+        se.squeeze(),
+        t.squeeze(),
+        p.squeeze(),
+        df.squeeze(),
+        res.squeeze(),
+    )

nltools/algorithms/signal.py

@@ -0,0 +1,303 @@
+"""Temporal signal processing — resampling, filtering, and basis functions."""
+
+import numpy as np
+import polars as pl
+from scipy.interpolate import interp1d
+from scipy.signal import butter, filtfilt
+
+
+def calc_bpm(beat_interval, sampling_freq):
+    """Calculate instantaneous BPM from beat to beat interval.
+
+    Args:
+        beat_interval (int): Number of samples between beats (typically the R-R interval).
+        sampling_freq (float): Sampling frequency in Hz.
+
+    Returns:
+        float: Beats per minute for the time interval.
+    """
+    return 60 * sampling_freq * (1 / (beat_interval))
+
+
+def downsample(
+    data, *, sampling_freq=None, target=None, target_type="samples", method="mean"
+):
+    """Downsample a Polars DataFrame/Series to a new target frequency or number of samples using averaging.
+
+    Args:
+        data (pl.DataFrame | pl.Series): Data to downsample.
+        sampling_freq (float): Sampling frequency of the data in Hz.
+        target (float): Downsampling target.
+        target_type (str): Unit of `target`, one of 'samples', 'seconds', or 'hz'.
+            Defaults to 'samples'.
+        method (str): Aggregation within each bin, 'mean' or 'median'. Defaults to 'mean'.
+
+    Returns:
+        pl.DataFrame | pl.Series: Downsampled data (same type as input).
+    """
+    if isinstance(data, pl.DataFrame):
+        df = data.clone()
+        return_series = False
+    elif isinstance(data, pl.Series):
+        df = pl.DataFrame({data.name or "0": data})
+        return_series = True
+    else:
+        raise ValueError("Data must be a Polars DataFrame or Series instance.")
+
+    if method not in ("mean", "median"):
+        raise ValueError("Metric must be either 'mean' or 'median'")
+
+    if target_type == "samples":
+        n_samples = target
+    elif target_type == "seconds":
+        n_samples = target * sampling_freq
+    elif target_type == "hz":
+        n_samples = sampling_freq / target
+    else:
+        raise ValueError('Make sure target_type is "samples", "seconds",  or "hz".')
+
+    # Calculate grouping indices more efficiently (matches design_matrix.py pattern)
+    n_groups = int(np.ceil(df.shape[0] / n_samples))
+    idx = pl.Series(np.repeat(np.arange(n_groups), int(n_samples))[: df.shape[0]])
+
+    # Handle remainder samples (last incomplete group)
+    if df.shape[0] > len(idx):
+        remainder = pl.Series(np.repeat(idx[-1] + 1, df.shape[0] - len(idx)))
+        idx = pl.concat([idx, remainder])
+
+    # Add grouping index to dataframe
+    df_with_idx = df.with_columns(idx.alias("_group_idx"))
+
+    # Group by index and aggregate using Polars group_by
+    if method == "mean":
+        downsampled_df = (
+            df_with_idx.group_by("_group_idx", maintain_order=True)
+            .agg([pl.col(col).mean() for col in df.columns])
+            .drop("_group_idx")
+        )
+    else:  # median
+        downsampled_df = (
+            df_with_idx.group_by("_group_idx", maintain_order=True)
+            .agg([pl.col(col).median() for col in df.columns])
+            .drop("_group_idx")
+        )
+
+    # Return Series if input was Series, otherwise DataFrame
+    if return_series:
+        return downsampled_df.to_series(0)
+    return downsampled_df
+
+
+def upsample(
+    data, *, sampling_freq=None, target=None, target_type="samples", method="linear"
+):
+    """Upsample a Polars DataFrame/Series to a new target frequency or number of samples using interpolation.
+
+    Args:
+        data (pl.DataFrame | pl.Series): Data to upsample. Non-numeric columns
+            are dropped from a DataFrame.
+        sampling_freq (float): Sampling frequency of the data in Hz.
+        target (float): Upsampling target.
+        target_type (str): Unit of `target`, one of 'samples', 'seconds', or 'hz'.
+        method (str): Interpolation method, one of 'linear', 'nearest', 'zero',
+            'slinear', 'quadratic', or 'cubic'; 'zero', 'slinear', 'quadratic'
+            and 'cubic' refer to spline interpolation of zeroth, first, second
+            or third order (default: 'linear').
+
+    Returns:
+        pl.DataFrame | pl.Series: Upsampled data, the same type as the input.
+    """
+    if isinstance(data, pl.DataFrame):
+        df = data.clone()
+        return_series = False
+    elif isinstance(data, pl.Series):
+        df = pl.DataFrame({data.name or "0": data})
+        return_series = True
+    else:
+        raise ValueError("Data must be a Polars DataFrame or Series instance.")
+
+    methods = ["linear", "nearest", "zero", "slinear", "quadratic", "cubic"]
+    if method not in methods:
+        raise ValueError(
+            "Method must be 'linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic'"
+        )
+
+    if target_type == "samples":
+        n_samples = target
+    elif target_type == "seconds":
+        n_samples = target * sampling_freq
+    elif target_type == "hz":
+        n_samples = float(sampling_freq) / float(target)
+    else:
+        raise ValueError('Make sure target_type is "samples", "seconds", or "hz".')
+
+    orig_spacing = np.arange(0, df.shape[0], 1)
+    new_spacing = np.arange(0, df.shape[0] - 1, n_samples)
+
+    # Interpolate each column using scipy (matches stats.upsample logic)
+    upsampled_data = {}
+    for col in df.columns:
+        col_data = df[col].to_numpy()
+
+        # Create interpolation function
+        interpolate = interp1d(orig_spacing, col_data, kind=method)
+
+        # Interpolate to new indices
+        upsampled_data[col] = interpolate(new_spacing)
+
+    # Create new Polars DataFrame
+    upsampled_df = pl.DataFrame(upsampled_data)
+
+    # Return Series if input was Series, otherwise DataFrame
+    if return_series:
+        return upsampled_df.to_series(0)
+    return upsampled_df
+
+
+def make_cosine_basis(nsamples, sampling_freq, filter_length, unit_scale=True, drop=0):
+    """Create basis functions for a discrete cosine transform.
+
+    Based on the implementation in ``spm_filter`` and ``spm_dctmtx`` because
+    scipy DCT can only apply transforms but not return the basis functions. Like
+    SPM, this does not add a constant (i.e. intercept), but does retain the first
+    basis (i.e. sigmoidal/linear drift).
+
+    Args:
+        nsamples (int): Number of observations (e.g. TRs).
+        sampling_freq (float): Sampling frequency in Hz (i.e. 1 / TR).
+        filter_length (int): Filter length in seconds.
+        unit_scale (bool): Scale the basis functions to the range [-1, 1]. Defaults to True.
+        drop (int): Number of leading (slowest) bases to drop after the constant is
+            removed; `drop=2` removes the first two. Defaults to 0, which keeps
+            the linear/sigmoidal drift basis that SPM discards.
+
+    Returns:
+        np.ndarray: Basis matrix of shape (nsamples, n_bases).
+    """
+
+    # Figure out number of basis functions to create
+    order = int(np.trunc(2 * (nsamples * sampling_freq) / filter_length + 1))
+
+    n = np.arange(nsamples)
+
+    # Initialize basis function matrix
+    C = np.zeros((len(n), order))
+
+    # Add constant
+    C[:, 0] = np.ones(len(n)) / np.sqrt(nsamples)
+
+    # Insert higher order cosine basis functions (vectorized)
+    if order > 1:
+        # Vectorize: create index matrix for broadcasting
+        i_indices = np.arange(1, order)[:, np.newaxis]  # (order-1, 1)
+        n_indices = n[np.newaxis, :]  # (1, nsamples)
+        # Compute all cosine basis functions at once
+        C[:, 1:] = (
+            np.sqrt(2.0 / nsamples)
+            * np.cos(np.pi * (2 * n_indices + 1) * i_indices / (2 * nsamples))
+        ).T
+
+    # Drop intercept ala SPM
+    C = C[:, 1:]
+
+    if C.size == 0:
+        raise ValueError(
+            "Basis function creation failed! nsamples is too small for requested filter_length."
+        )
+
+    if unit_scale:
+        C *= 1.0 / C[0, 0]
+
+    C = C[:, drop:]
+
+    return C
+
+
+def _butter_bandpass_filter(data, low_cut, high_cut, fs, axis=0, order=5):
+    """Apply a bandpass butterworth filter with zero-phase filtering.
+
+    Args:
+        data (np.ndarray): Signal(s) to filter.
+        low_cut (float): Lower cutoff frequency (high-pass edge) in Hz.
+        high_cut (float): Upper cutoff frequency (low-pass edge) in Hz.
+        fs (float): Sampling frequency in Hz.
+        axis (int): Axis along which to filter. Defaults to 0.
+        order (int): Butterworth filter order. Defaults to 5.
+
+    Returns:
+        np.ndarray: Bandpass-filtered data with the same shape as `data`.
+    """
+    nyq = 0.5 * fs
+    b, a = butter(order, [low_cut / nyq, high_cut / nyq], btype="band")
+    return filtfilt(b, a, data, axis=axis)
+
+
+def _phase_mean_angle(phase_angles):
+    """Compute the circular mean of phase angles.
+
+    Follows Fisher, N. I. (1995), *Statistical Analysis of Circular Data*.
+
+    Args:
+        phase_angles (np.ndarray): A 1D array of angles, or a 2D array whose rows
+            are sets of angles (e.g. time points x subjects).
+
+    Returns:
+        np.ndarray: The mean angle; one value per row for 2D input.
+    """
+
+    axis = 0 if len(phase_angles.shape) == 1 else 1
+    return np.arctan2(
+        np.mean(np.sin(phase_angles), axis=axis),
+        np.mean(np.cos(phase_angles), axis=axis),
+    )
+
+
+def _phase_vector_length(phase_angles):
+    """Compute the mean resultant vector length of phase angles.
+
+    Follows Fisher, N. I. (1995), *Statistical Analysis of Circular Data*.
+
+    Args:
+        phase_angles (np.ndarray): A 1D array of angles, or a 2D array whose rows
+            are sets of angles (e.g. time points x subjects).
+
+    Returns:
+        np.ndarray: Vector length in [0, 1]; one value per row for 2D input.
+    """
+
+    axis = 0 if len(phase_angles.shape) == 1 else 1
+    return np.float32(
+        np.sqrt(
+            np.mean(np.cos(phase_angles), axis=axis) ** 2
+            + np.mean(np.sin(phase_angles), axis=axis) ** 2
+        )
+    )
+
+
+def _phase_rayleigh_p(phase_angles):
+    """Compute Rayleigh-test p-values for non-uniformity of phase angles.
+
+    Follows Fisher, N. I. (1995), *Statistical Analysis of Circular Data*.
+
+    Args:
+        phase_angles (np.ndarray): A 1D array of angles, or a 2D array whose rows
+            are sets of angles (e.g. time points x subjects).
+
+    Returns:
+        np.ndarray: Rayleigh p-values; one value per row for 2D input.
+
+    Note:
+        The test treats the angles in each set as independent, which
+        autocorrelated timeseries violate.
+    """
+
+    n = len(phase_angles) if len(phase_angles.shape) == 1 else phase_angles.shape[1]
+
+    Z = n * _phase_vector_length(phase_angles) ** 2
+    if n <= 50:
+        return np.exp(-1 * Z) * (
+            1
+            + (2 * Z - Z**2) / (4 * n)
+            - (24 * Z - 132 * Z**2 + 76 * Z**3 - 9 * Z**4) / (288 * n**2)
+        )
+    return np.exp(-1 * Z)