Randomization statistics utilities (spynal.randstats.utils)

Utility functions for randomization statistics

Function list

  • resamples_to_pvalue : Compute p value from observed and resampled statistic values

  • confint_to_indexes : Returns indexes into resampled stats corresponding to given confints

  • jackknife_to_pseudoval : Compute single-trial pseudovalues from leave-one-out jackknife estimates

Function reference

tail_to_compare(tail)

Convert string specifier for randomization test tail-type to callable function implementing it

Parameters:

tail ({'left','right','both'}, default: 'both') –

Type of statistical test (“tail”) to perform on x vs x_rsmp:

  • ’left’ : HO: x >= x_rsmp; H1: x < x_rsmp

  • ’right’ : HO: x <= x_rsmp; H1: x > x_rsmp

  • ’both’ : HO: x == x_rsmp; H1: x != x_rsmp

Returns:

  • compare_func (lambda, args:stat_obs,stat_resmp) – Lambda function that implements comparison to evaluate randomization statistical tests of given type

  • NOTE (The returned lambdas invert the logic of the given alternative hypothesis (H1),)

  • because they are used to count the number of resamples that *fail to meet this criterion.*

  • The proportion of such failed resamples is then taken as the p value (eg 5% of resamples

  • failing to meet criterion => p = 0.05).

resamples_to_pvalue(stat_obs, stat_resmp, axis=0, tail='both')

Compute p value with given tail from observed and resampled values of a statistic

Parameters:

  • stat_obs (ndarray, shape=(...,1,...)) – Statistic values for actual observed data

  • stat_resmp (ndarray, shape=(...,n_resamples,...)) – Statistic values for randomly resampled data

  • axis (int, default: 0) – Axis in stat_resmp corresponding to distinct resamples (should correspond to a length=1 axis in stat_obs)

  • tail ({'both','right','left'}, default: 'both' (2-tailed test)) –

    Specifies tail of test to perform:

    • ’both’ : 2-tail test – test for abs(stat_obs) > abs(stat_resmp)

    • ’right’ : right-sided 1-tail test – tests for stat_obs > stat_resmp

    • ’left’ : left-sided 1-tail test – tests for stat_obs < stat_resmp

Returns:

p – p values from resampling test. Same size as stat_obs.

Return type:

ndarray, shape=(…,1,…)

confint_to_indexes(confint, n_resamples)

Return indexes into set of resamples corresponding to given confidence interval

Typically used for bootstrap resampled confidence intervals. Could be used for jackknifes.

Parameters:

  • confint (float) – Desired confidence interval, in range 0-1. eg, for 99% confidence interval, input 0.99

  • n_resamples (int) – Number of resamples (eg bootstraps)

Returns:

conf_indexes – Indexes into sorted resamples corresponding to [lower,upper] confidence interval

Return type:

list[int], shape=(2,)

jackknife_to_pseudoval(x, xjack, n)

Compute single-trial pseudovalues from leave-one-out jackknife estimates

Parameters:

  • x (ndarray, shape=Any) – Statistic computed on full observed data. Any arbitrary shape.

  • xjack (ndarray, shape=Any) – Statistic computed on jackknife resampled data

  • n (int) – Number of observations (trials) used to compute x

Returns:

pseudo – Single-trial jackknifed pseudovalues. Same shape as xjack.

Return type:

ndarray, shape=Any