plspy package
Module contents
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.
- gsvd
Implementation of GSVD that uses NumPy’s Fortran SVD function
- resample
Functions used for resampling in permutation and bootstrap
- bootstrap_permutation
Houses the bootstrap and permutation object (called by PLS)
- pls_classes
Source code for each PLS version
- exceptions
Houses custom exceptions used within PLS
Basic usage examples:
Note: There are 3 required arguments, used in the following order:
X - 2-d task matrix
a list containing the number of subjects in each group
argument 3 is an int indicating the number of conditions
Example arguments are used below.
Mean-Centred Task PLS:
>>> result = plspy.PLS(X, [10, 10], 3, num_perm=500, num_boot=500, pls_method="mct")Behavioural PLS:
>>> result = plspy.PLS(X, [10, 10], 3, Y=Y, pls_method="rb")Contrast Task PLS:
>>> result = plspy.PLS(X, [10, 10], 3, contrasts=C, pls_method="cst")Contrast Behavioural PLS:
>>> result = plspy.PLS(X, [10, 10], 3, Y=Y, contrasts=C, pls_method="csb")Multiblock PLS:
>>> result = plspy.PLS(X, [10, 10], 3, Y=Y, pls_method="mb")
To see documentation on additional arguments and fields available, call help on a specific PLS method (see below for details).
Documentation is available both in help() form and will also be available in website form. More information on how to access online documentation is forthcoming. Information on how to use help() is below.
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 (under construction)
- Note: calling
>>> help(plspy.PLS)
will show you this same help page.
Author: Noah Frazier-Logue
Submodules
plspy.bootstrap_permutation module
- class plspy.bootstrap_permutation._ResampleTestTaskPLS(X, Y, U, s, V, cond_order, contrast=None, preprocess=None, nperm=1000, nboot=1000, dist=(0.05, 0.95), rotate_method=0, mctype=0)
Bases:
ResampleTestClass that runs permutation and bootstrap tests for Task PLS. When run, this class generates fields for permutation test information (permutation ratio, etc.) and for bootstrap test informtaion (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.
nonrotated (boolean, optional) – Not implememted yet.
dist (2-tuple of floats, optional) – Distribution values used for calculating the confidence interval in the bootstrap test. Defaults to (0.05, 0.95).
- dist
Distribution values used for calculating the confidence interval in the bootstrap test. Defaults to (0.05, 0.95).
- Type
2-tuple of floats, optional
- 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
- 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
- _abc_impl = <_abc_data object>
- static _bootstrap_test(X, Y, U, s, V, cond_order, niter, pls_alg, preprocess=None, rotate_method=0, mctype=0, dist=(0.05, 0.95), contrast=None)
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.
- static _permutation_test(X, Y, U, s, V, cond_order, niter, pls_alg, preprocess=None, contrast=None, rotate_method=0, mctype=0, threshold=1e-12)
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.
plspy.check_inputs module
plspy.decorators module
plspy.exceptions module
plspy.gsvd module
plspy.pls module
plspy.pls_classes module
- 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, rotate_method: int = 0, contrasts: Optional[list] = None, **kwargs)
Bases:
_ContrastTaskPLSDriver 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
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.
rotate_method (int, optional) –
Optional value specifying whether or not full GSVD should be used during bootstrap and permutation tests (“rotated” method). rotate_method options:
0 - compute s using SVD/GSVD
1 - compute s using Procrustes rotation
2 - compute s by derivation
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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
- 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
- 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
- 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. Optionally normed if rotate in [1,2].
- Type
np.array
- resample_tests
Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.
- Type
class
- _abc_impl = <_abc_data object>
- class plspy.pls_classes._ContrastMultiblockPLS(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, rotate_method: int = 0, contrasts: Optional[list] = None, **kwargs)
Bases:
_MultiblockPLSDriver 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
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.
rotate_method (int, optional) –
Optional value specifying whether or not full GSVD should be used during bootstrap and permutation tests (“rotated” method). rotate_method options:
0 - compute s using SVD/GSVD
1 - compute s using Procrustes rotation
2 - compute s by derivation
- 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
- 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
- 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
- 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. Optionally normed if rotate in [1,2].
- Type
np.array
- resample_tests
Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.
- Type
class
- _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, rotate_method: int = 0, mctype: int = 0, contrasts: Optional[list] = None, **kwargs)
Bases:
_MeanCentreTaskPLSDriver 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
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.
rotate_method (int, optional) –
Optional value specifying whether or not full GSVD should be used during bootstrap and permutation tests (“rotated” method). rotate_method options:
0 - compute s using SVD/GSVD
1 - compute s using Procrustes rotation
2 - compute s by derivation
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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
- 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
- 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
- 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. Optionally normed if rotate in [1,2].
- Type
np.array
- resample_tests
Class containing results for permutation and bootstrap tests. See documentation on Resample Tests for more information.
- Type
class
- _abc_impl = <_abc_data object>
- class plspy.pls_classes._MultiblockPLS(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, rotate_method: int = 0, **kwargs)
Bases:
_RegularBehaviourPLSDriver 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
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.
rotate_method (int, optional) –
Optional value specifying whether or not full GSVD should be used during bootstrap and permutation tests (“rotated” method). rotate_method options:
0 - compute s using SVD/GSVD
1 - compute s using Procrustes rotation
2 - compute s by derivation
- 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
- 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
- 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
- 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
- _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 = 1000, num_boot: int = 1000, rotate_method: int = 0, **kwargs)
Bases:
_MeanCentreTaskPLSDriver 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
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.
rotate_method (int, optional) –
Optional value specifying whether or not full GSVD should be used during bootstrap and permutation tests (“rotated” method). rotate_method options:
0 - compute s using SVD/GSVD
1 - compute s using Procrustes rotation
2 - compute s by derivation
- 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. For example, if input matrix X contained 7 participants and 3 conditions, it would be of length 21.
- 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
- 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
- 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
- _abc_impl = <_abc_data object>