contrast_rsa_plan.md
In bbuchsbaum/rMVPA: Multivoxel Pattern Analysis in R

Contrast RSA Integration Plan for rMVPA

This document outlines the steps to integrate the Multi-Dimensional Signed Representational Voxel Encoding (MS-ReVE) approach into the rMVPA package, primarily through a new contrast_rsa_model.

Always check off the items that are done. Conceptual plan in in signed_rsa_proposal.md

[ ] Create msreve_design Object:
- [ ] Define a new S3/S4 class msreve_design.
- [ ] Include slots for the underlying mvpa_design object.
- [ ] Include a slot for the user-defined contrast_matrix (C, K x Q).
- [ ] Document the class and its purpose.
- [ ] (Optional) Add helper function orthogonalize_contrasts(C) for users.
[ ] Develop compute_crossvalidated_means_sl Helper Function:
- [ ] Input: mvpa_dataset subset for the searchlight (sl_data), mvpa_design, cv_spec, estimation_method parameter.
- [ ] The cv_spec object is generated by the user from functions in R/crossval.R (e.g., blocked_cross_validation(mvpa_design$block_var)), defining the specific CV strategy.
- [ ] Implement logic to compute K x V_sl matrix Û_sl based on cross-validation folds defined in cv_spec (using helpers like train_indices() and get_nfolds()).
- [ ] Support different estimation_methods (e.g., "average_betas", potentially others later).
- [ ] Add unit tests for this function.
[ ] Create contrast_rsa_model Specification:
- [ ] Define a new S3 class contrast_rsa_model (inheriting from mvpa_model_spec which itself inherits from model_spec).
- [ ] Write the constructor contrast_rsa_model(...).
  - [ ] Crucially, this constructor must use create_model_spec("contrast_rsa_model", ...) internally to properly instantiate the model object.
  - [ ] Takes mvpa_dataset.
  - [ ] Takes an msreve_design object.
  - [ ] Takes parameters: estimation_method, regression_type, output_metric.
- [ ] Add documentation and examples for the constructor.
[ ] Implement train_model.contrast_rsa_model Method:
- [ ] Input: obj (contrast_rsa_model), sl_data, sl_info (containing center voxel index/ID).
- [ ] Step 1: Call compute_crossvalidated_means_sl to get Û_sl.
- [ ] Step 2: Compute Ĝ_sl = Û_sl %*% t(Û_sl).
- [ ] Step 3: Prepare RSA regression inputs:
  - [ ] Vectorize Ĝ_sl (dvec_sl).
  - [ ] Create predictor matrix X_sl from obj$design$contrast_matrix. (Reuse/adapt rsa_model_mat logic). Handle block_var exclusions if necessary.
- [ ] Step 4: Run regression (using obj$regression_type) to get β_sl (Q-vector). Reuse run_lm, run_lm_constrained, etc.
- [ ] Step 5: Compute Δ_sl = t(Û_sl) %*% C (V_sl x Q matrix).
- [ ] Step 6: Extract center voxel's projection Δ_{v_c,sl} (Q-vector) using sl_info.
- [ ] Step 7: Calculate the final result_vector based on obj$output_metric (e.g., β_sl * Δ_{v_c,sl}).
- [ ] Step 8: Return the named result_vector (Q-dimensional).
- [ ] Add robust error handling within the function.
- [ ] Add unit tests for this method (mocking dependencies).

[ ] Update Searchlight Machinery:
- [ ] Ensure the searchlight generation code (volume and surface) makes the center voxel's index/ID available in the sl_info object passed to the iterator function.
[ ] Create Iterator Function msreve_iterate:
- [ ] Input: model_spec (contrast_rsa_model), slight (list of searchlights), cind (center indices).
- [ ] Iterate through searchlights.
- [ ] Extract data (sl_data) and center voxel info (sl_info) for each searchlight.
- [ ] Call train_model.contrast_rsa_model(model_spec, sl_data, sl_info, ...)
- [ ] Collect results (Q-vectors) and error status into a standard data frame format compatible with combiners.
[ ] Create Combiner Function combine_msreve_standard:
- [ ] Input: model_spec, good_results, bad_results.
- [ ] Extract center voxel IDs from good_results$id.
- [ ] Extract the list of Q-vectors from good_results$performance.
- [ ] Bind these vectors into an N_voxels x Q matrix.
- [ ] Create Q separate output maps (e.g., SparseNeuroVec or NeuroSurfaceVector), one per column (contrast). Name them appropriately.
- [ ] Ensure output maps (layers) are named based on contrast names.
- [ ] Return a result object (e.g., msreve_searchlight_result) containing the list of these Q maps.
[ ] Implement run_searchlight.contrast_rsa_model S3 Method:
- [ ] Define the method signature.
- [ ] Call run_searchlight_base internally.
- [ ] Pass mvpa_fun = msreve_iterate.
- [ ] Pass combiner = combine_msreve_standard.
- [ ] Handle method-specific arguments if necessary (e.g., currently only supporting "standard" method).

[ ] Add Vignette/Tutorial:
- [ ] Create a new vignette demonstrating how to use contrast_rsa_model.
- [ ] Include example data setup, model definition, execution, and interpretation of results.
[ ] Comprehensive Integration Tests:
- [ ] Write tests covering the end-to-end workflow for both volume and surface data.
[ ] Refine Documentation:
- [ ] Ensure all new functions and classes have clear Roxygen documentation.
- [ ] Update relevant sections of the package README or overview documentation.
[ ] (Optional) Implement run_regional.contrast_rsa_model:
- [ ] Wrap train_model.contrast_rsa_model for ROI-based analysis (analogous to other run_regional methods).
- [ ] Consider if a custom process_roi.contrast_rsa_model method is needed if whole-ROI processing differs significantly from searchlight processing beyond what train_model can handle.