ADA-SVR (2/4) add comments and documentation of the functions and test

doc_conf/references.bib

@@ -177,4 +177,21 @@ @article{liuFastPowerfulConditional2021
   archiveprefix = {arxiv},
   keywords = {Statistics - Methodology},
   file = {/home/ahmad/Zotero/storage/8HRQZX3H/Liu et al. - 2021 - Fast and Powerful Conditional Randomization Testin.pdf;/home/ahmad/Zotero/storage/YFNDKN2B/2006.html}
+}
+
+@article{gaonkar_deriving_2012,
+	title = {Deriving statistical significance maps for {SVM} based image classification and group comparisons},
+	volume = {15},
+	url = {https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3703958/},
+	abstract = {Population based pattern analysis and classification for quantifying structural and functional differences between diverse groups has been shown to be a powerful tool for the study of a number of diseases, and is quite commonly used especially in neuroimaging. The alternative to these pattern analysis methods, namely mass univariate methods such as voxel based analysis and all related methods, cannot detect multivariate patterns associated with group differences, and are not particularly suitable for developing individual-based diagnostic and prognostic biomarkers. A commonly used pattern analysis tool is the support vector machine ({SVM}). Unlike univariate statistical frameworks for morphometry, analytical tools for statistical inference are unavailable for the {SVM}. In this paper, we show that null distributions ordinarily obtained by permutation tests using {SVMs} can be analytically approximated from the data. The analytical computation takes a small fraction of the time it takes to do an actual permutation test, thereby rendering it possible to quickly create statistical significance maps derived from {SVMs}. Such maps are critical for understanding imaging patterns of group differences and interpreting which anatomical regions are important in determining the classifier's decision.},
+	pages = {723--730},
+	number = {0},
+	journaltitle = {Medical image computing and computer-assisted intervention : {MICCAI} ... International Conference on Medical Image Computing and Computer-Assisted Intervention},
+	journal = {Med Image Comput Comput Assist Interv},
+	author = {Gaonkar, Bilwaj and Davatzikos, Christos},
+	urldate = {2024-12-16},
+	year = {2012},
+	pmid = {23285616},
+	pmcid = {PMC3703958},
+	file = {PubMed Central Full Text PDF:/home/likusch/Zotero/storage/DX8QQAF5/Gaonkar and Davatzikos - 2012 - Deriving statistical significance maps for SVM based image classification and group comparisons.pdf:application/pdf},
 }

examples/plot_fmri_data_example.py

@@ -54,7 +54,7 @@
 from sklearn.linear_model import Ridge
 from sklearn.utils import Bunch
 
-from hidimstat.adaptive_permutation_threshold import ada_svr
+from hidimstat.ada_svr import ada_svr
 from hidimstat.clustered_inference import clustered_inference
 from hidimstat.ensemble_clustered_inference import ensemble_clustered_inference
 from hidimstat.permutation_test import permutation_test, permutation_test_cv

hidimstat/__init__.py

@@ -1,4 +1,4 @@
-from .adaptive_permutation_threshold import ada_svr
+from .ada_svr import ada_svr
 from .clustered_inference import clustered_inference, hd_inference
 from .desparsified_lasso import desparsified_group_lasso, desparsified_lasso
 from .Dnn_learner_single import DnnLearnerSingle

hidimstat/adaptive_permutation_threshold.py → hidimstat/ada_svr.py

@@ -2,7 +2,10 @@
 
 
 def ada_svr(X, y, rcond=1e-3):
-    """Statistical inference procedure presented in Gaonkar et al. [1]_.
+    """
+    ADA-SVR: Adaptive Permutation Threshold Support Vector Regression
+
+    Statistical inference procedure presented in :footcite:t:`gaonkar_deriving_2012`.
 
     Parameters
     -----------
@@ -15,6 +18,7 @@ def ada_svr(X, y, rcond=1e-3):
     rcond : float, optional (default=1e-3)
         Cutoff for small singular values. Singular values smaller
         than `rcond` * largest_singular_value are set to zero.
+        Deafult value is 1e-3.
 
     Returns
     -------
@@ -26,23 +30,22 @@ def ada_svr(X, y, rcond=1e-3):
 
     References
     ----------
-    .. [1] Gaonkar, B., & Davatzikos, C. (2012, October). Deriving statistical
-           significance maps for SVM based image classification and group
-           comparisons. In International Conference on Medical Image Computing
-           and Computer-Assisted Intervention (pp. 723-730). Springer, Berlin,
-           Heidelberg.
-    """
+    .. footbibliography::
 
+    """
     X = np.asarray(X)
 
-    K = np.linalg.pinv(np.dot(X, X.T), rcond=rcond)
-    sum_K = np.sum(K)
-
-    L = -np.outer(np.sum(K, axis=0), np.sum(K, axis=1)) / sum_K
-    C = np.dot(X.T, K + L)
+    ## compute matrix C, (see eq.6 of [1])
+    # invert matrix X*X'
+    XXT_inv = np.linalg.pinv(np.dot(X, X.T), rcond=rcond)
+    # partial computation of the 2nd term of the equation
+    sum_XXT_inv = np.sum(XXT_inv)
+    L = -np.outer(np.sum(XXT_inv, axis=0), np.sum(XXT_inv, axis=1)) / sum_XXT_inv
+    C = np.dot(X.T, XXT_inv + L)
 
+    ## compute vector W, (see eq.4 of [1])
     beta_hat = np.dot(C, y)
-
+    ## compute standard deviation of the distribution of W, (see eq.12 of [1])
     scale = np.sqrt(np.sum(C**2, axis=1))
 
     return beta_hat, scale

hidimstat/test/test_adaptive_permutation_threshold.py

@@ -5,7 +5,7 @@
 import numpy as np
 from numpy.testing import assert_almost_equal
 
-from hidimstat.adaptive_permutation_threshold import ada_svr
+from hidimstat.ada_svr import ada_svr
 from hidimstat.scenario import multivariate_1D_simulation
 from hidimstat.stat_tools import pval_from_scale