Diagonale Analysis Decision Tree

How to choose analysis parameters in Diagonale.

Main Analysis Tree

DecisionTree cluster_permutation permutation parameters cluster_ols OLS parameters cluster_plssvd PLS-SVD parameters cluster_clustering clustering parameters cluster_global Global/Common analysis settings root Start global_seed di_cfg.analysis.randomSeed di_cfg.analysis.nIterations (required for all) root->global_seed perm di_cfg.analysis.objective = 'permutationH0testing' root->perm boot di_cfg.analysis.objective = 'bootstrapStability' root->boot perm_h0 di_cfg.analysis.permuteUnit = 'wholeObservation' | 'withinObservation' di_cfg.analysis.p_crit (default 0.05) perm->perm_h0 feat1 di_cfg.analysis. inferenceLevel = 'feature' perm->feat1 clus1 di_cfg.analysis. inferenceLevel = 'cluster' perm->clus1 late1 di_cfg.analysis. inferenceLevel = 'latent' perm->late1 feat2 di_cfg.analysis. inferenceLevel = 'feature' boot->feat2 late2 di_cfg.analysis. inferenceLevel = 'latent' boot->late2 feat1_test di_cfg.analysis. testingApproach = 'empirical' | 'parametric' feat1->feat1_test ols_ref di_cfg.analysis.OLS (see OLS tree below) feat1->ols_ref clus1_cluster di_cfg.analysis.clusterParams (see clusterParams tree below) clus1->clus1_cluster clus1_test di_cfg.analysis. testingApproach = 'parametric' clus1->clus1_test clus1->ols_ref late1_test di_cfg.analysis. testingApproach = 'empirical' late1->late1_test feat1_corr_fdr di_cfg.analysis. correction = 'FDR' feat1_test->feat1_corr_fdr feat1_corr_maxT di_cfg.analysis. correction = 'maxT' feat1_test->feat1_corr_maxT feat1_fdr di_cfg.analysis.FDR_dimensions (if correction='FDR') feat1_corr_fdr->feat1_fdr clus1_corr di_cfg.analysis. correction = 'maxT' clus1_test->clus1_corr late1_corr di_cfg.analysis. correction = 'maxT' late1_test->late1_corr plssvd_zsc di_cfg.analysis.plssvdParams .zscoringVec (default [true, false], index 1 = Y, index 2 = X) late1_corr->plssvd_zsc plssvd_sc di_cfg.analysis. subjectCentering = 'noCenter' | 'center' (latent + repeated only) plssvd_zsc->plssvd_sc feat2->ols_ref late2->plssvd_zsc

dataStruct Parameter

di_cfg.analysis.dataStruct is required for all analyses. It must be a MATLAB table variable that describes the structure of your data—specifically, what each row of your Y matrix represents. At minimum, it should include an ‘observationID’ column. The table can include additional columns for grouping variables, subject identifiers, or other design factors.

TO DO: show how to create a dataStruct table with an example.

clusterParams Sub-tree

ClusterParams root di_cfg.analysis.clusterParams (required for cluster inference) adjacency di_cfg.analysis.clusterParams .adjacencyMatrix (required) root->adjacency threshold di_cfg.analysis.clusterParams .clusterFormingPvalThreshold (default 0.05) root->threshold cont_idx di_cfg.analysis.clusterParams .distance_continuous_index (if continuous dims exist) root->cont_idx sph_rad di_cfg.analysis.clusterParams .distance_spherical_radians (if spherical dims exist) (default: 0.63 for 32ch, 0.36 for 128ch) root->sph_rad

OLS Sub-tree

OLS root di_cfg.analysis.OLS (optional for feature/cluster inference) variance di_cfg.analysis.OLS .varianceType = 'equal' | 'unequal' (default 'equal') root->variance standardize di_cfg.analysis.OLS .standardize = true | false (default false) (z-scores predictor & outcome) root->standardize ranked di_cfg.analysis.OLS .ranked = true | false (default false) (applies rank transform) root->ranked

Compatibility matrix

objective inferenceLevel supported testingApproach correction options
permutationH0testing feature yes empirical, parametric FDR, maxT
permutationH0testing cluster yes parametric maxT
permutationH0testing latent yes empirical maxT
bootstrapStability feature yes n/a n/a
bootstrapStability cluster no n/a n/a
bootstrapStability latent yes n/a n/a

General parameters

  1. di_cfg.analysis.objective
  • required for all analyses
  • allowed values: permutationH0testing, bootstrapStability
  1. di_cfg.analysis.inferenceLevel
  • required for all analyses
  • allowed values: feature, cluster, latent
  1. di_cfg.analysis.dataStruct
  • required for all analyses
  • must be a ‘table’ variable
  1. di_cfg.analysis.ignore_row
  • required for all analyses (default is to ignore nothing)
  • if provided: column vector with one value per row of Y
  1. di_cfg.analysis.ignore_col
  • optional for all analyses (default is to ignore nothing)
  • if provided: row vector with one value per column of Y
  1. di_cfg.analysis.randomSeed
  • required for all analyses (default is 42)
  • must be finite integer scalar
  1. di_cfg.analysis.nIterations
  • required for all analyses (default is 5000)
  1. di_cfg.analysis.verbose
  • optional for all analyses (default is false)
  • type: logical/boolean
  • controls whether debug/progress information is printed to console
  1. di_cfg.analysis.figFlag
  • optional for all analyses (default is false)
  • type: logical/boolean
  • controls whether figures/plots are generated during analysis

Permutation-only parameters

The following parameters must be set if di_cfg.analysis.objective = 'permutationH0testing'

  1. di_cfg.analysis.permuteUnit
  • required when di_cfg.analysis.objective = permutationH0testing
  • not used when di_cfg.analysis.objective = bootstrapStability
  • allowed values: wholeObservation, withinObservation
  • note: final validity depends on design code in di_validateH0
  1. di_cfg.analysis.p_crit
  • required when di_cfg.analysis.objective = permutationH0testing (default 0.05)
  • not used when di_cfg.analysis.objective = bootstrapStability
  1. di_cfg.analysis.testingApproach
  • required when di_cfg.analysis.objective = permutationH0testing
  • not allowed when di_cfg.analysis.objective = bootstrapStability
  • allowed values depend on di_cfg.analysis.inferenceLevel = ...:
    • 'feature': testing approach can be empirical or parametric
    • 'cluster': testing approach can be parametric only
    • 'latent': testing approach can be empirical only
  1. di_cfg.analysis.correction
  • required when di_cfg.analysis.objective = permutationH0testing
  • not allowed when di_cfg.analysis.objective = bootstrapStability
  • allowed values depend on inferenceLevel:
    • feature: FDR or maxT
    • cluster: maxT only
    • latent: maxT only
  1. di_cfg.analysis.FDR_dimensions
  • required only when:
    • di_cfg.analysis.objective = permutationH0testing
    • di_cfg.analysis.inferenceLevel = feature
    • di_cfg.analysis.correction = FDR
  • not allowed in all other cases

Cluster-specific parameters

  1. di_cfg.analysis.clusterParams
  • required when di_cfg.analysis.inferenceLevel = cluster
  • optional but ignored when inferenceLevel is not cluster
  1. di_cfg.analysis.clusterParams.adjacencyMatrix
  • required when di_cfg.analysis.inferenceLevel = cluster
  1. di_cfg.analysis.clusterParams.distance_continuous_index
  • required when:
    • di_cfg.analysis.inferenceLevel = cluster
    • at least one dimension is continuous
  1. di_cfg.analysis.clusterParams.distance_spherical_radians
  • required when:
    • di_cfg.analysis.inferenceLevel = cluster
    • at least one dimension is spherical
  1. di_cfg.analysis.clusterParams.clusterFormingPvalThreshold
  • required when di_cfg.analysis.inferenceLevel = cluster (default 0.05)

Latent (PLS-SVD) parameters

  1. di_cfg.analysis.plssvdParams
  • required when di_cfg.analysis.inferenceLevel = latent
  • ignored when di_cfg.analysis.inferenceLevel is not latent
  1. di_cfg.analysis.plssvdParams.zscoringVec
  • required when di_cfg.analysis.inferenceLevel = latent (default [true, false])
  • interpretation of elements:
    • index 1 controls z-scoring of Y
    • index 2 controls z-scoring of X
  • example: default [true, false] means Y is z-scored, while X is mean-centered only
  1. di_cfg.analysis.subjectCentering
  • optional, only valid when di_cfg.analysis.inferenceLevel = latent AND design has repeated measures
  • allowed values: center, noCenter (default is noCenter)
  • note: if set to center in OLS-based analyses (feature/cluster), causes validation error
  • repeated measures designs typically have subjects appearing in multiple conditions

OLS-specific parameters (feature/cluster inference)

The following parameters apply only when di_cfg.analysis.inferenceLevel = 'feature' or 'cluster', which are powered by OLS regression under the hood.

  1. di_cfg.analysis.OLS.varianceType
  • optional for OLS-based feature and cluster analyses
  • allowed values: equal, unequal (default is equal)
  • equal compares groups through standard Student’s t-test (homogeneous variance assumed)
  • unequal compares groups through Welch’s t-test (heterogeneous variance allowed)
  1. di_cfg.analysis.OLS.standardize
  • optional for OLS-based feature and cluster analyses
  • allowed values: true, false as logical/boolean (default is false)
  • when false, uses raw values
  • when true, z-scores both predictor and outcome variables (standardized slopes equal correlation coefficient)
  1. di_cfg.analysis.OLS.ranked
  • optional for OLS-based feature and cluster analyses
  • allowed values: true, false as logical/boolean (default is false)
  • when false, uses raw/standardized values (it yields Pearson correlation coefficients when used with di_cfg.analysis.OLS.standardize = true)
  • when true, rank transform both predictor and outcome variables (it yields Spearman correlation coefficients when used with di_cfg.analysis.OLS.standardize = true)