osl_dynamics.glm

General Linear Model (GLM) and permutation testing.

Modules

• base — DesignConfig for specifying regressors/contrasts and GLM for fitting the model.

• ols — Ordinary least squares implementation.

• permutation — MaxStatPermutation for non-parametric group-level inference with family-wise error correction.

Tutorials

• Group Contrast

• Network Response

Python example scripts

• Statistics

Classes

DesignConfig	Configuration class for Design.
GLM	Base class for GLM objects.
MaxStatPermutation	Max statistic permutation test.

Functions

plot_design_matrix(design[, show_contrasts, cmap, ax, ...])

Plot a GLM design matrix.

Package Contents

class osl_dynamics.glm.DesignConfig

Configuration class for Design.

Parameters:

• features (List[Dict]) –

  List of dictionaries containing feature information. Each dictionary should contain the following keys:

  • name: str

    Feature name.

  • values: np.ndarray or list

    Feature values. Must be 1D.

  • feature_type: str

    Feature type. Must be ‘constant’, ‘continuous’, or ‘categorical’.

• contrasts (List[Dict]) –

  List of dictionaries containing contrast information. Each dictionary should contain the following keys:

  • name: str

    Contrast name.

  • values: np.ndarray or list

    Contrast values. Must be 1D.

• standardize_features (bool) – Whether to standardize continuous features. Default is True.

features: List[Dict] = None

contrasts: List[Dict] = None

standardize_features: bool = True

create_design()

Create a Design object from the configuration.

Returns:

design – Design object.

Return type:

osl_dynamics.glm.base.Design

class osl_dynamics.glm.GLM(design)

Base class for GLM objects.

Parameters:

design (osl_dynamics.glm.base.Design) – Design object.

design

X

c

n_targets = None

target_dims = None

fit(y)

Fit the GLM model.

Parameters:

y (np.ndarray or list) – Target values. Shape is (n_samples, *target_dims).

Return type:

None

get_tstats(copes=None, varcopes=None)

Get t-statistics.

Parameters:

• copes (np.ndarray) – Contrast parameter estimates. Shape is (n_contrasts, *target_dims).

• varcopes (np.ndarray) – Variance of contrast parameter estimates. Shape is (n_contrasts, *target_dims).

Returns:

tstats – t-statistics. Shape is (n_contrasts, *target_dims).

Return type:

np.ndarray

property n_samples: int | None

Return type:

Optional[int]

property n_features: int | None

Return type:

Optional[int]

property feature_names: List[str]

Return type:

List[str]

property feature_types: List[str]

Return type:

List[str]

property n_contrasts: int

Return type:

int

property contrast_names: List[str]

Return type:

List[str]

property contrast_types: List[str]

Return type:

List[str]

property dof: int

Return type:

int

property tstats: numpy.ndarray

Return type:

numpy.ndarray

summary()

Get a summary of the GLM.

Return type:

Dict

class osl_dynamics.glm.MaxStatPermutation(design, contrast_indx, n_perm, perm_type=None, n_jobs=1)

Bases: Permutation

Max statistic permutation test.

Parameters:

• design (osl_dynamics.glm.base.Design) – Design object.

• contrast_indx (int) – Index of the contrast of interest.

• n_perm (int) – Number of permutations.

• perm_type (str, optional) – Type of permutation. Options are ‘sign_flip’ and ‘row_shuffle’. If None, it will be determined based on the feature types and contrast type.

• n_jobs (int, optional) – Number of jobs to run in parallel.

fit(y)

Fit the GLM with unpermuted data and run permutations.

Parameters:

y (np.ndarray) – Target variable. Shape is (n_samples, *target_dims).

Return type:

None

get_pvalues(metric='copes')

Get p-values.

Parameters:

metric (str, optional) – Metric to compute p-values. Options are ‘copes’ and ‘tstats’.

Returns:

pvalues – P-values. Shape is (*target_dims).

Return type:

np.ndarray

osl_dynamics.glm.plot_design_matrix(design, show_contrasts=True, cmap='coolwarm', ax=None, filename=None)

Plot a GLM design matrix.

Displays the design matrix as a heatmap with feature names as column labels and a diverging colormap centred at zero.

Parameters:

• design (osl_dynamics.glm.base.Design) – Design object.

• show_contrasts (bool, optional) – If True, display the contrast matrix below the design matrix.

• cmap (str, optional) – Matplotlib colormap name.

• ax (plt.Axes, optional) – Axis to plot on. If None, a new figure is created. Cannot be used with show_contrasts=True.

• filename (str, optional) – Output filename. If None, the figure and axes are returned.

Returns:

• fig (plt.Figure) – Matplotlib figure. Only returned if ax=None and filename=None.

• axes (plt.Axes or np.ndarray of plt.Axes) – Matplotlib axes. Only returned if ax=None and filename=None.