refactor: Compute the sklearn Ridge decoder in factorized form

README.md

@@ -49,27 +49,36 @@ $ python predict_feature_fastl2lir.py config/deeprecon_pyfastl2lir_alpha100_vgg1
 $ python evaluation.py config/deeprecon_pyfastl2lir_alpha100_vgg19_allunits.yaml
 ```
 
-### Decoding with generic regression models
+### Decoding with scikit-learn Ridge regression
 
-- Training: `train_decoder_sklearn_ridge.py` (example for scikit-learn Ridge regression)
+- Training: `train_decoder_sklearn_ridge.py`
 - Test (prediction): `predict_feature.py`
 - Evaluation: `evaluation.py`
 - Example config file: [deeprecon_sklearn_ridge_alpha100_vgg19_allunits](config/deeprecon_sklearn_ridge_alpha100_vgg19_allunits.yaml)
 
 ```shell
 # Training of decoding models
-$ python train_decoder_sklearn_ridge.py config/deeprecon_pyfastl2lir_alpha100_vgg19_allunits.yaml
+$ python train_decoder_sklearn_ridge.py config/deeprecon_sklearn_ridge_alpha100_vgg19_allunits.yaml
 
 # Prediction of DNN features
-$ python predict_feature.py config/deeprecon_pyfastl2lir_alpha100_vgg19_allunits.yaml
+$ python predict_feature.py config/deeprecon_sklearn_ridge_alpha100_vgg19_allunits.yaml
 
 # Evaluation
-$ python evaluation.py config/deeprecon_pyfastl2lir_alpha100_vgg19_allunits.yaml
+$ python evaluation.py config/deeprecon_sklearn_ridge_alpha100_vgg19_allunits.yaml
 ```
 
+The scikit-learn Ridge decoder is trained and stored in a factorized form: the
+model maps brain activity onto the training stimulus basis, and prediction
+combines its coefficients with the training features. This is mathematically
+identical to regressing the features directly, but the stored decoder is much
+smaller and training does not scale with the feature dimension.
+`predict_feature.py` therefore reads the training features
+(`decoder.features.paths`, already set in the example config). See
+`ridge_factorization.py` for the details.
+
 ### Cross-validation feature decoding
 
-- Training: `cv_train_decoder_fastl2lir.py` (example for scikit-learn Ridge regression)
+- Training: `cv_train_decoder_fastl2lir.py`
 - Test (prediction): `cv_predict_feature_fastl2lir.py`
 - Evaluation: `cv_evaluation.py`
 - Example config file: [deeprecon_cv_pyfastl2lir_alpha100_vgg19_allunits](config/deeprecon_cv_pyfastl2lir_alpha100_vgg19_allunits.yaml)

config/README.md

@@ -17,7 +17,7 @@ These settings are used by the decoder training script (e.g., `train_decoder_fas
   - `decoder.path`: Defines the path where the decoder data is located. The path can include placeholders like `${decoder.name}` and `${decoder.features.name}` to dynamically set paths based on the feature name.
   - `decoder.parameters`:
     - `alpha`: A regularization parameter set to 100.
-    - `chunk_axis`: Indicates that chunking is done along axis 1.
+    - `chunk_axis`: Indicates that chunking is done along axis 1. For the sklearn Ridge decoder it applies to the prediction step only.
 2. fMRI data
   - This specifies fMRI data used for the decoder training.
   - `decoder.fmri.name`: Refers to the dataset name, here "ImageNetTraining_fmriprep_volume_native".
@@ -27,7 +27,7 @@ These settings are used by the decoder training script (e.g., `train_decoder_fas
 3. Features
   - This specifies features used for the decoder training.
   - `decoder.features.name`: Refers to the pre-trained DNN model used.
-  - `decoder.features.paths`: Provides the path to the feature data.
+  - `decoder.features.paths`: Provides the path to the feature data. The factorized sklearn Ridge decoder reads these at prediction time as well, as the features of the training stimuli.
   - `decoder.features.layers`: Specifies the layers of the DNN from which features will be extracted.
 
 ## Decoded features

config/deeprecon_sklearn_ridge_alpha100_vgg19_allunits.yaml

@@ -5,6 +5,7 @@ decoder:
   path: ./data/feature_decoders/ImageNetTraining/${decoder.name}/${decoder.features.name}
   parameters:
     alpha: 100
+    # Axis along which the feature combination is blocked at prediction time.
     chunk_axis: 1
 
   fmri:
@@ -34,6 +35,7 @@ decoder:
 
   features:
     name: caffe/VGG19
+    # Features of the training stimuli; also read by `predict_feature.py`.
     paths:
       - ./data/features/ImageNetTraining/${decoder.features.name}
     layers: