plspy

plspy is a Partial Least Squares package developed at the Institute for Neuroscience and Neurotechnology at Simon Fraser University.

In addition to core PLS functionality, this package also contains the following modules:

class_functions

core PLS functions, such as mean-centring, calling SVD/GSVD, etc.

pls_classes

Source code for each PLS version

resample

Functions used for resampling in permutation and bootstrap

bootstrap_permutation

Houses the bootstrap and permutation object (called by PLS)

split_half_resampling

Functions used for split-half and split-half test-train resampling

visualize

Functions for plotting key outputs from PLS analyses

exceptions

Houses custom exceptions used within PLS

Usage Examples

All methods require:

1. X: 2D data matrix. Rows should be ordered as subject within condition within group.

2. groups: list with the number of subjects per group (e.g., [10, 10])

3. num_conditions: integer specifying the number of conditions

Example arguments are used below.

Mean-Centred Task PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, mctype=0, num_perm=500, num_boot=500, num_split=500, lv=1, CI=0.95, pls_method="mct")

Behavioural PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, Y=Y, pls_method="rb")

Contrast Task PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, contrasts=C, pls_method="cst")

Contrast Behavioural PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, Y=Y, contrasts=C, pls_method="csb")

Multiblock PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, Y=Y, mctype=0, bscan=[1,2], pls_method="mb")

Contrast Multiblock PLS

>>> result = plspy.PLS(X, [10, 10], num_conditions=3, Y=Y, mctype=0, bscan=[1,2], pls_method="cmb")

To get help documentation on a particular version of PLS, type the following in a Python interpreter after loading the module:

>>> import plspy
>>> help(plspy.methods["<methodname>"])

Where <method> is the string of one of the PLS versions shown below.

Available methods:

“mct” - Mean-Centred Task PLS

“rb” - Regular Behaviour PLS

“cst” - Contrast Task PLS

“csb” - Contrast Behaviour PLS

“mb” - Multiblock PLS

“cmb” - Contrast Multiblock PLS

Note: calling

>>> help(plspy.PLS)

will show you this same help page.

Submodules

Core PLS

plspy.pls

plspy.pls_classes

Options

• Mean-Centred Task PLS

• Behavioural PLS

• Contrast Task PLS

• Contrast Behavioural PLS

• Multiblock PLS

• Contrast Multiblock PLS

class plspy.pls_classes._MeanCentreTaskPLS(X: array, groups_sizes: tuple, num_conditions: int, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 1000, num_boot: int = 1000, mctype: int = 0, CI: float = 0.95, **kwargs: str)

Bases: PLSBase

Driver class for Mean-Centred Task PLS.

Classed called for Mean-Centred Task PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (None) – Not used in Mean-Centred Task PLS.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

• mctype (int, optional) –

  mctype options:

  0 - within each group remove group means from condition means (default)

  1 - remove grand condition means from each group condition mean

  2 - remove grand mean (over all subjects and conditions)

  3 - remove all main effects - subtract condition and group means (group by condition)

X

Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

X_latent

Latent variables of input X; dot-product of X_mc and V.

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

static _get_groups_info(groups_tuple)

Returns tuple of groups tuple passed into class and number of groups.

static _get_cond_order(X_shape, groups_tuple, num_conditions)

Returns a list of lists. Each sub-list contains the number of subjects per condition for each group. Length of each sub-list is num_conditions and length of returned list is len(groups_tuple).

_abc_impl = <_abc_data object>

class plspy.pls_classes._RegularBehaviourPLS(X: array, groups_sizes: tuple, num_conditions: int, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 0, num_boot: int = 0, CI: float = 0.95, **kwargs)

Bases: _MeanCentreTaskPLS

Driver class for Behavioural PLS.

Class called for Behavioural PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (np.array) – Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

X

Input neural matrix/matrices for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

Y

Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

Y_latent

Latent variables for contrasts.

Type:

np.array

X_latent

Latent variables of input X; dot-product of X_mc and V.

Type:

np.array

lvcorrs

Computed latent variable correlations

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

_abc_impl = <_abc_data object>

class plspy.pls_classes._ContrastTaskPLS(X: array, groups_sizes: tuple, num_conditions: int, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 1000, num_boot: int = 1000, mctype: int = 0, contrasts: Optional[list] = None, CI: float = 0.95, **kwargs)

Bases: _MeanCentreTaskPLS

Driver class for Contrast Task PLS.

Class called for Contrast Task PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (None) – Not used in Contrast Task PLS.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

• mctype (int, optional) –

  mctype options:

  0 - within each group remove group means from condition means (default)

  1 - remove grand condition means from each group condition mean

  2 - remove grand mean (over all subjects and conditions)

  3 - remove all main effects - subtract condition and group means (group by condition)

• contrasts (np.array) – contrast matrix for use in Contrast Task PLS. Used to create different methods of comparison.

X

Input neural matrix/matrices for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

Y

Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

Y_latent

Latent variables for contrasts.

Type:

np.array

X_latent

Latent variables of input X; dot-product of X_mc and V.

Type:

np.array

lvintercorrs

U.T * U.

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

_abc_impl = <_abc_data object>

class plspy.pls_classes._ContrastBehaviourPLS(X: array, groups_sizes: tuple, num_conditions: int, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 1000, num_boot: int = 1000, contrasts: Optional[list] = None, CI: float = 0.95, **kwargs)

Bases: _ContrastTaskPLS

Driver class for Contrast Behaviour PLS.

Class called for Contrast Behaviour PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (np.array) – Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

• contrasts (np.array) – contrast matrix for use in Contrast Task PLS. Used to create different methods of comparison.

X

Input neural matrix/matrices for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

Y

Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

Y_latent

Latent variables for contrasts.

Type:

np.array

X_latent

Latent variables of input X; dot-product of X_mc and V.

Type:

np.array

lvintercorrs

U.T * U.

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

_abc_impl = <_abc_data object>

class plspy.pls_classes._MultiblockPLS(X: array, groups_sizes: tuple, num_conditions: int, mctype: int = 0, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 1000, num_boot: int = 1000, CI: float = 0.95, **kwargs)

Bases: _RegularBehaviourPLS

Driver class for Multiblock PLS.

Class called for Multiblock PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (np.array) – Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

X

Input neural matrix/matrices for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

Y

Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

bscan

List/array specifying the subset of conditions to be used. E.g., [1 3] for conditions 1 and 3. The conditions should be listed in ascending order. Default bscan is all conditions i.e., [1 2 3 4] for 4 conditions.

Type:

array-like

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

Y_latent

Latent variables for contrasts.

Type:

np.array

X_latent

Type:

np.array

lvcorrs

Computed latent variable correlations

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

_abc_impl = <_abc_data object>

class plspy.pls_classes._ContrastMultiblockPLS(X: array, groups_sizes: tuple, num_conditions: int, mctype: int = 0, Y: Optional[list] = None, cond_order: Optional[list] = None, num_perm: int = 1000, num_boot: int = 1000, contrasts: Optional[list] = None, CI: float = 0.95, **kwargs)

Bases: _MultiblockPLS

Driver class for Multiblock PLS.

Class called for Multiblock PLS. TODO: add more here.

Parameters:

• X (np.array) – Input neural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• groups_sizes (tuple) – Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

• num_conditions (int) – Number of conditions in each matrix.

• Y (np.array) – Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

• num_perm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

• num_boot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

• num_split (int, optional) – Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

• CI (float, optional) – Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

• lv (int, optional) – Optional value specifying the largest number of LV to be evaluated in the reproducibility tests. For example, lv=3 means 1,2,3 are assessed.

X

Input neural matrix/matrices for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

Y

Input behavioural matrix for use with PLS. Each participant’s data must be flattened and concatenated to form a single 2-dimensional matrix, separated by condition, for each group.

Type:

np.array

groups_sizes

Tuple containing sizes of conditions, where each entry in the tuple corresponds to a group and each value in the entry corresponds to the number of participants in that group. E.g. in (7,6,5), group 1 would have 7 participants and group 3 would have 5 participants.

Type:

tuple

num_groups

Value specifying the number of groups in the input data.

Type:

int

num_conditions

Number of conditions in each matrix.

Type:

int

cond_order

List/array where each entry holds the number of subjects per condition for each group in the input matrix.

Type:

array-like

num_perm

Optional value specifying the number of iterations for the permutation test. Defaults to 0, meaning no permutation test will be run unless otherwise specified by the user.

Type:

int

num_boot

Optional value specifying the number of iterations for the bootstrap test. Defaults to 0, meaning no bootstrap test will be run unless otherwise specified by the user.

Type:

int

num_split

Optional value specifying the number of splits for the resproducibilty tests. Defaults to 0, meaning no reproducibilty test will be run unless otherwise specified by the user.

Type:

int

CI

Confidence level (e.g., 0.95) used when computing bootstrap confidence intervals for singular vectors and for split-half reproducibility tests.

Type:

float

lv

Optional value specifying the largest number of LV to be evaluated in the reproducibility tests.

Type:

int

X_means

Mean-values of X array on axis-0 (column-wise).

Type:

np.array

X_mc

Mean-centred values corresponding to input matrix X.

Type:

np.array

U

Eigenvectors of matrix `X_mc`*`X_mc`^T; left singular vectors.

Type:

np.array

s

Vector containing diagonal of the singular values.

Type:

np.array

V

Eigenvectors of matrix X_mc`^T*`X_mc; right singular vectors.

Type:

np.array

Y_latent

Latent variables for contrasts.

Type:

np.array

X_latent

Latent variables of input X; dot-product of X_mc and V.

Type:

np.array

lvcorrs

Computed latent variable correlations

Type:

np.array

lvintercorrs

U.T * U.

Type:

np.array

resample_tests

Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.

Type:

class

pls_repro_sh

Dictionary containing results for split-half reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

pls_repro_tt

Dictionary containing results for split-half test-train reproducibility tests. See documentation on Reproducibility Tests for more information.

Type:

dict

_abc_impl = <_abc_data object>

Resampling

plspy.bootstrap_permutation

class plspy.bootstrap_permutation._ResampleTestPLS(X, Y, U, s, V, cond_order, mctype, contrast=None, preprocess=None, nperm=1000, nboot=1000, bscan=None, Xbscan=None, Ybscan=None, lvcorrs_orig=None, Tvsc_orig=None, CI=0.95)

Bases: ResampleTest

Class that runs permutation and bootstrap tests for PLS. When run, this class generates fields for permutation test information (permutation ratio, etc.) and for bootstrap test information (confidence intervals, standard errors, bootstrap ratios, etc.).

Parameters:

• X (np.array) – Input neural matrix/matrices for use with PLS. This matrix is passed in from the PLS class.

• U (np.array) – Left singular vectors of X.

• s (np.array) – Singular values for X. Used to compute permutation ratio.

• V (np.array) – Right singular vectors of X.

• cond_order (array-like) – Order vector(s) for conditions in X.

• preprocess (function, optional) – Preprocessing function used prior to running GSVD on X in PLS class. Used to preprocess resampled matrices in boostrap/ permutation tests.

• nperm (int, optional) – Optional value specifying the number of iterations for the permutation test. Defaults to 1000.

• nboot (int, optional) – Optional value specifying the number of iterations for the bootstrap test. Defaults to 1000.

• dist (2-tuple of floats, deprecated) – Distribution values used for calculating the confidence interval in the bootstrap test. Defaults to (0.05, 0.95).

• CI (float) – Confidence level used to derive the z-score threshold for bootstrap confidence intervals. Defaults to 0.95. Note: The percentile-based CI approach is deprecated and not supported; code remains commented out and requires manual changes to use.

dist

Distribution values used for calculating the confidence interval in the bootstrap test. Defaults to (0.05, 0.95).

Type:

2-tuple of floats, deprecated

permute_ratio

Ratio of resampled values greater than observed values, divided by the number of iterations in the permutation test. A higher ratio indicates a higher level of randomness.

Type:

float

stepdown_ratio

Ratio of resampled cumulative covariances for each LV and the remaining LVs that exceed the observed cumulative covariance, divided by the number of iterations in the permutation test. Provides a more stringent assessment than permute_ratio.

Type:

float

conf_ints

Upper and lower element-wise confidence intervals for the resampled left singular vectors in a tuple.

Type:

2-tuple of np.arrays

std_errs

Element-wise standard errors for the resampled right singular vectors.

Type:

np.array

boot_ratios

NumPy array containing element-wise ratios of

Type:

np.array

CI

Confidence level used to derive the z-score threshold for bootstrap confidence intervals. Defaults to 0.95.

Type:

float

LVcorr

Bootstrap distribution of LV correlations across iterations for behavioural or multi-block PLS.

Type:

np.array

_abc_impl = <_abc_data object>

static _permutation_test(X, Y, U, s, V, cond_order, mctype, niter, pls_alg, preprocess=None, contrast=None, threshold=1e-12, bscan=None, Xbscan=None, Ybscan=None)

Run permutation test on X. Resamples X (without replacement) based on condition order, runs PLS on resampled matrix, and computes the element-wise permutation ratio ((number of times permutation > observation)/niter.

static _bootstrap_test(X, Y, U, s, V, cond_order, mctype, niter, pls_alg, preprocess=None, dist=(0.05, 0.95), contrast=None, bscan=None, Xbscan=None, Ybscan=None, lvcorrs_orig=None, Tvsc_orig=None, CI=0.95)

Runs a bootstrap estimation on X matrix. Resamples X with replacement according to the condition order, runs PLS on the resampled X matrices, and computes conf_int, std_errs, and boot_ratios.

plspy.resample

plspy.resample.resample_with_replacement(matrix, cond_order, C=None, group_num=0, return_indices=False)

Resamples input matrix with replacement. This implementation uses condition array C to shuffle the rows of matrix within conditions, with replacement. Returns resampled as shuffled matrix. Optionally returns shuffled indices (shuf_indices).

Parameters:

• matrix (array-like) – Input matrix of arbitrary dimension and type. Will be cast to numpy array.

• C (array-like, optional) – Condition matrix used to shuffle rows of matrix according to condition. Should be in list form or a ndarray of shape (n,) where n > = 1. Initializes to np.ones(matrix.shape[0]) by default.

• group_num (int, optional) – Group number of input matrix. Used to select corresponding condition matrix. Defaults to group 1.

• return_indices (boolean, optional) – Whether or not to return the shuffled indices corresponding to the shuffle in the returned matrix. Defaults to False.

Returns:

• resampled (numpy_array) – Resampled array, with replacement, of same shape as matrix.

• return_indices (boolean, optional) – If set to True, returns the ordering of the shuffled conditions list.

plspy.resample.resample_without_replacement(matrix, cond_order, C=None, group_num=0, return_indices=False, pls_alg='mct')

Resamples input matrix without replacement. This implementation uses condition array C to shuffle the rows of matrix within conditions, without replacement. Returns resampled as shuffled matrix. Optionally returns shuffled indices (shuf_indices).

Parameters:

• matrix (array-like) – Input matrix of arbitrary dimension and type. Will be cast to numpy array.

• C (array-like, optional) – Condition matrix used to shuffle rows of matrix according to condition. Should be in list form or a ndarray of shape (n,) where n > = 1. Initializes to np.ones(matrix.shape[0]) by default.

• group_num (int, optional) – Group number of input matrix. Used to select corresponding condition matrix. Defaults to group 1.

• return_indices (boolean, optional) – Whether or not to return the shuffled indices corresponding to the shuffle in the returned matrix. Defaults to False.

Returns:

• resampled (numpy_array) – Resampled array, without replacement, of same shape as matrix.

• return_indices (boolean, optional) – If set to True, returns the ordering of the shuffled conditions list.

plspy.split_half_resampling

plspy.split_half_resampling.split_half(pls_alg, matrix, Y, cond_order, num_split, mctype=None, contrasts=None, bscan=None, Xbscan=None, Ybscan=None, lv=1, CI=0.95)

Perform split-half reproducibility test.

Parameters:

• pls_alg (str) – Name of the PLS variant.

• matrix (np.ndarray) – Input data matrix with dimensions (subjects x features).

• Y (np.ndarray, optional) – Input behavioral matrix.

• cond_order (array-like) – List/array where each entry holds the number of subjects per condition for each group in the input matrix.

• num_split (int) – Number of split-half samples.

• mctype (int, optional) – Method for mean-centering the data.

• contrasts (np.ndarray, optional) – Contrast matrix for use in Contrast Task PLS. Used to create different methods of comparison.

• lv (int) – Number of LVs to evaluate. If the specified value exceeds the maximum possible number of LVs, it is automatically set to the maximum.

• CI (float) – Confidence interval percentile. Defaults to 0.95.

Returns:

pls_repro_sh

Return type:

Dictionary containing split-half reproducibility results.

Keys

pls_rep_mean_ulist[float]

Average of cosines for u distribution from split-half.

pls_rep_mean_vlist[float]

Average of cosines for v distribution from split-half.

pls_rep_z_ulist[float]

Z-value for u distribution (mean_u/std_u)

pls_rep_z_vlist[float]

Z-value for v distribution (mean_v/std_v)

pls_rep_ul_ulist[float]

Upper bound of the u distribution.

pls_rep_ll_ulist[float]

Lower bound of the u distribution.

pls_rep_ul_vlist[float]

Upper bound of the v distribution.

pls_rep_ll_vlist[float]

Lower bound of the v distribution.

pls_null_mean_ulist[float]

Average of null u distribution created by permutation.

pls_null_mean_vlist[float]

Average of null v distribution.

pls_null_z_ulist[float]

Z-value for null u distribution.

pls_null_z_vlist[float]

Z-value for null v distribution.

pls_null_ul_ulist[float]

Upper bound of null u distribution.

pls_null_ll_ulist[float]

Lower bound of null u distribution.

pls_null_ul_vlist[float]

Upper bound of null v distribution.

pls_null_ll_vlist[float]

Lower bound of null v distribution.

pls_dist_unp.ndarray

Full distribution of u cosines.

pls_dist_vnp.ndarray

Full distribution of v cosines.

pls_dist_null_unp.ndarray

Full distribution of null u cosines.

pls_dist_null_vnp.ndarray

Full distribution of null v cosines.

plspy.split_half_resampling.split_half_test_train(pls_alg, matrix, Y, cond_order, num_split, mctype=None, contrasts=None, bscan=None, Xbscan=None, Ybscan=None)

Perform split-half test-train PLS reproducibility test.

Parameters:

• pls_alg (str) – Name of the PLS variant.

• matrix (np.ndarray) – Input data matrix with dimensions (subjects x features).

• Y (np.ndarray, optional) – Input behavioral matrix.

• cond_order (array-like) – List/array where each entry holds the number of subjects per condition for each group in the input matrix.

• num_split (int) – Number of split-half samples.

• mctype (int, optional) – Method for mean-centering the data

• contrasts (np.ndarray, optional) – Contrast matrix for use in Contrast Task PLS. Used to create different methods of comparison.

Returns:

pls_repro_tt

Return type:

Dictionary containing split-half test-train reproducibility results.

Keys

pls_s_trainnp.ndarray

Distribution of singular values from training samples.

pls_s_testnp.ndarray

Distribution of singular values from corresponding test samples.

znp.ndarray

Z-values for each test singular value, computed as mean(pls_s_test)/std(pls_s_test).

pls_s_train_nullnp.ndarray

Distribution singular values from training sample where rows for one data block are permuted.

pls_s_test_nullnp.ndarray

Distribution singular values from test sample where rows for one data block are permuted.

z_nullnp.ndarray

Z-values for null test singular values (mean(pls_s_test_null)/std(pls_s_test_null)).

Visualization

Provides classes to visualize PLS results.

Available plot types:

• Singular Values Plot

• Permuted Singular Values Plot

• Design LV Plot

• Design Scores Plot

• Task PLS Brain Score Plot

• Correlation Plot

• Behaviour LV Plot

• Brain Scores vs Behaviour Plot

Utilities

plspy.check_inputs

plspy.decorators

plspy.exceptions