fitgrid.utils.lmer module

User functions to streamline working with selected pymer4 LMER fit attributes from lme4::lmer and lmerTest for fitgrid.lmer grids.

fitgrid.utils.lmer.get_lmer_dfbetas(epochs, factor, **kwargs)[source]

Fit lmers leaving out factor levels one by one, compute DBETAS.

Parameters

  • epochs (Epochs) – Epochs object

  • factor (str) – column name of the factor of interest

  • **kwargs – keyword arguments to pass on to fitgrid.lmer, like RHS

Returns

dfbetas – dataframe containing DFBETAS values

Return type

pandas.DataFrame

Examples

Example calculation showing how to pass in model fitting parameters:

dfbetas = fitgrid.utils.lmer.get_lmer_dfbetas(
    epochs=epochs,
    factor='subject_id',
    RHS='x + (x|a)
)

Notes

DFBETAS is computed according to the following formula [NieGroPel2012]:

\[DFBETAS_{ij} = \frac{\hat{\gamma}_i - \hat{\gamma}_{i(-j)}}{se\left(\hat{\gamma}_{i(-j)}\right)}\]

for parameter \(i\) and level \(j\) of factor.

fitgrid.utils.lmer.get_lmer_warnings(lmer_grid)[source]

grid the LMERFitGrid lme4::lmer4 warnings by type

lmer warnings are a mishmash of characters, punctuation, and digits, some with numerical values specific to the message, for instance,

Model failed to converge with max|grad| = 0.00222262 (tol = 0.002, component 1)
unable to evaluate scaled gradient
boundary (singular) fit: see ?isSingular
np.nan

The warning strings are returned as-is except for stripping leading and trailing whitespace and the “= N.NNNNNNNN” portion of the max |grad| convergence failure.

Parameters

lmer_grid (fitgrid.LMERFitGrid) – as returned by fitgrid.lmer(), shape = time x channel

Returns

warning_grids – A dictionary, the keys are lmer warning strings, each value is a pandas.DataFrame indicator grid where grid.loc[time, channel] == 1 if the lmer warning == key, otherwise 0.

Return type

dict

fitgrid.utils.lmer.plot_lmer_warnings(lmer_grid, which='each', verbose=True)[source]

Raster plot lme4::lmer warning grids

Parameters

  • lmer_grid (fitgrid.LMERFitGrid) – as returned by fitgrid.lmer(), shape = time x channel

  • which ({“each”, “all”, or list of str}) – select the types of warnings to plot. each (default) plots each type of warning separately. all plots one grid showing where any type of warning occurred. A list of strings searches the lmer warnings and plots those that match.

  • verbose (bool, default=True) – If True warn of failed matches for warnings keywords.

Examples

default, plot each warning grid separately

>>> plot_lmer_warnings(lmer_grid)

one plot shows everywhere there is a warning

>>> plot_lmer_warnings(lmer_grid, which="all")

plot just warnings that match these strings

>>> plot_lmer_warnings(lmer_grid, which=["converge", "singular"])