# algorithms.statistics.mixed_effects_stat

## Module: `algorithms.statistics.mixed_effects_stat`

Inheritance diagram for `nipy.algorithms.statistics.mixed_effects_stat`:

Module for computation of mixed effects statistics with an EM algorithm. i.e. solves problems of the form y = X beta + e1 + e2, where X and Y are known, e1 and e2 are centered with diagonal covariance. V1 = var(e1) is known, and V2 = var(e2) = lambda identity. the code estimates beta and lambda using an EM algorithm. Likelihood ratio tests can then be used to test the columns of beta.

Author: Bertrand Thirion, 2012.

    >>> N, P = 15, 500
    >>> V1 = np.random.randn(N, P) ** 2
    >>> effects = np.ones(P)
    >>> Y = generate_data(np.ones(N), effects, .25, V1)
    >>> T1 = one_sample_ttest(Y, V1, n_iter=5)
    >>> T2 = t_stat(Y)
    >>> assert(T1.std() < T2.std())

## Class

## `MixedEffectsModel`

class nipy.algorithms.statistics.mixed_effects_stat.MixedEffectsModel(X, n_iter=5, verbose=False)

  Bases: `object`

  Class to handle multiple one-sample mixed effects models

  __init__(X, n_iter=5, verbose=False)

    Set the effects and first-level variance, and initialize related quantities

    Parameters:
      X: array of shape(n_samples, n_effects),

        the design matrix

      n_iter: int, optional,

        number of iterations of the EM algorithm

      verbose: bool, optional, verbosity mode
  fit(Y, V1)

    Launches the EM algorithm to estimate self

    Parameters:
      Y, array of shape (n_samples, n_tests) or (n_samples)

        the estimated effects

      V1, array of shape (n_samples, n_tests) or (n_samples)

        first-level variance

    Returns:
      self
  log_like(Y, V1)

    Compute the log-likelihood of (Y, V1) under the model

    Parameters:
      Y, array of shape (n_samples, n_tests) or (n_samples)

        the estimated effects

      V1, array of shape (n_samples, n_tests) or (n_samples)

        first-level variance

    Returns:
      logl: array of shape self.n_tests,

        the log-likelihood of the model

  predict(Y, V1)

    Return the log_likelihood of the data.See the log_like method

  score(Y, V1)

    Return the log_likelihood of the data. See the log_like method

## Functions

nipy.algorithms.statistics.mixed_effects_stat.check_arrays(Y, V1)

  Check that the given data can be used for the models

  Parameters:
    Y: array of shape (n_samples, n_tests) or (n_samples)

      the estimated effects

    V1: array of shape (n_samples, n_tests) or (n_samples)

      first-level variance

nipy.algorithms.statistics.mixed_effects_stat.generate_data(X, beta, V2, V1)

  Generate a group of individuals from the provided parameters

  Parameters:
    X: array of shape (n_samples, n_reg),

      the design matrix of the model

    beta: float or array of shape (n_reg, n_tests),

      the associated effects

    V2: float or array of shape (n_tests),

      group variance

    V1: array of shape(n_samples, n_tests),

      the individual variances

  Returns:
    Y: array of shape(n_samples, n_tests)

      the individual data related to the two-level normal model

nipy.algorithms.statistics.mixed_effects_stat.mfx_stat(Y, V1, X, column, n_iter=5, return_t=True, return_f=False, return_effect=False, return_var=False, verbose=False)

  Run a mixed-effects model test on the column of the design matrix

  Parameters:
    Y: array of shape (n_samples, n_tests)

      the data

    V1: array of shape (n_samples, n_tests)

      first-level variance associated with the data

    X: array of shape(n_samples, n_regressors)

      the design matrix of the model

    column: int,

      index of the column of X to be tested

    n_iter: int, optional,

      number of iterations of the EM algorithm

    return_t: bool, optional,

      should one return the t test (True by default)

    return_f: bool, optional,

      should one return the F test (False by default)

    return_effect: bool, optional,

      should one return the effect estimate (False by default)

    return_var: bool, optional,

      should one return the variance estimate (False by default)

    verbose: bool, optional, verbosity mode
  Returns:
    (tstat, fstat, effect, var): tuple of arrays of shape (n_tests),

      those required by the input return booleans

nipy.algorithms.statistics.mixed_effects_stat.one_sample_ftest(Y, V1, n_iter=5, verbose=False)

  Returns the mixed effects F-stat for each row of the X (one sample test) This uses the Formula in Roche et al., NeuroImage 2007

  Parameters:
    Y: array of shape (n_samples, n_tests)

      the data

    V1: array of shape (n_samples, n_tests)

      first-level variance ssociated with the data

    n_iter: int, optional,

      number of iterations of the EM algorithm

    verbose: bool, optional, verbosity mode
  Returns:
    fstat, array of shape (n_tests),

      statistical values obtained from the likelihood ratio test

    sign, array of shape (n_tests),

      sign of the mean for each test (allow for post-hoc signed tests)

nipy.algorithms.statistics.mixed_effects_stat.one_sample_ttest(Y, V1, n_iter=5, verbose=False)

  Returns the mixed effects t-stat for each row of the X (one sample test) This uses the Formula in Roche et al., NeuroImage 2007

  Parameters:
    Y: array of shape (n_samples, n_tests)

      the observations

    V1: array of shape (n_samples, n_tests)

      first-level variance associated with the observations

    n_iter: int, optional,

      number of iterations of the EM algorithm

    verbose: bool, optional, verbosity mode
  Returns:
    tstat: array of shape (n_tests),

      statistical values obtained from the likelihood ratio test

nipy.algorithms.statistics.mixed_effects_stat.t_stat(Y)

  Returns the t stat of the sample on each row of the matrix

  Parameters:
    Y, array of shape (n_samples, n_tests)
  Returns:
    t_variates, array of shape (n_tests)

nipy.algorithms.statistics.mixed_effects_stat.two_sample_ftest(Y, V1, group, n_iter=5, verbose=False)

  Returns the mixed effects t-stat for each row of the X (one sample test) This uses the Formula in Roche et al., NeuroImage 2007

  Parameters:
    Y: array of shape (n_samples, n_tests)

      the data

    V1: array of shape (n_samples, n_tests)

      first-level variance associated with the data

    group: array of shape (n_samples)

      a vector of indicators yielding the samples membership

    n_iter: int, optional,

      number of iterations of the EM algorithm

    verbose: bool, optional, verbosity mode
  Returns:
    tstat: array of shape (n_tests),

      statistical values obtained from the likelihood ratio test

nipy.algorithms.statistics.mixed_effects_stat.two_sample_ttest(Y, V1, group, n_iter=5, verbose=False)

  Returns the mixed effects t-stat for each row of the X (one sample test) This uses the Formula in Roche et al., NeuroImage 2007

  Parameters:
    Y: array of shape (n_samples, n_tests)

      the data

    V1: array of shape (n_samples, n_tests)

      first-level variance associated with the data

    group: array of shape (n_samples)

      a vector of indicators yielding the samples membership

    n_iter: int, optional,

      number of iterations of the EM algorithm

    verbose: bool, optional, verbosity mode
  Returns:
    tstat: array of shape (n_tests),

      statistical values obtained from the likelihood ratio test