Lesion-Behavior Mapping using Causal Feature Learning

Overview

Causal Feature Learning (CFL) is an unsupervised algorithm designed to construct macro-variables from low-level data, preserving the causal relationships present in the data. In this repository, CFL is applied to human brain lesion data and corresponding responses to language, visuospatial, and depression assessments (as described in the associated preprint) in order to identify 1) categories of lesions that are unique in their effects on test responses and 2) categories of test responses that are unique in their likelihoods of occurring given any lesion. This code depends on the CFL software package which can be installed via pip.

Installation

Clone this repository: git clone https://github.com/iwahle/cfl_lbm.git. This shouldn't take more than a minute on a standard laptop.

Environment setup

The included code has been tested on macOS 12.6.1. A conda environment with all necessary dependencies and dependency versions is specified in cfl-lbm-env.yml. To construct an environment with the specified dependencies, navigate to the repository and run:

conda env create -f cfl-lbm-env.yml
conda activate cfl-lbm
pip install -e .

Running the code

1. Once you have set up your conda environment and activated it, run the example code in examples/example0.ipynb with the provided simulated dataset.

2. To use this code with your own data, add a new directory within data that contains the following files:

   • X.npy: an n_samples x n_voxels array of vectorized lesion masks
   • Y.npy: an n_samples x n_items array of behavioral test responses
   • dems.npy : optional, an n_samples x n_demographics array of demographic measures to include when running CFL.

3. Parameters to run CFL with can be modified in cfl_params.py. Consult the CFL software package documentation for details on setting parameters. Examples of how to set parameters for hyperparameter tuning are included in this file as well.

4. Modify util.load_scale_data to properly preprocess your specific dataset.

5. run_cfl.py and most files in extended_analyses take the following arguments:

   • analysis: the name of the directory within data where your data is stored
   • include_dem: if 1, will include the demographic quantities specified in dems.npy; if 0, will not.

Set these with flags as needed when running scripts from the command line.

Included analyses

• source/run_cfl.py: fits a CFL model provided cause and effect variable data
• source/extended_analyses/cluster_questions.py: clusters question-wise responses based on their contributions to defining the effect partition found by CFL
• source/extended_analyses/compare_aggregates.py: evaluates candidate aggregate BDI quantities based on ability to predict categories found by CFL
• source/extended_analyses/compare_cca.py: compares CFL results to CCA results
• source/extended_analyses/compare_mbdi.py compares CFL results found when the effect is given as responses to the 21 BDI questions versus the mean score across questions
• source/extended_analyses/compare_naive.py: compares CFL results to those found when lesion masks are clustered without regard to the effect

License and Citations

If you use cfl_lbm in published research work, we encourage you to cite this repository:

Lesion-Behavior Mapping using Causal Feature Learning (2023). https://github.com/iwahle/cfl_lbm

or use the BibTex reference:

@misc{cfl_lbm2023,
    title     = "Lesion-Behavior Mapping using Causal Feature Learning",
    year      = "2023",
    publisher = "GitHub",
    url       = "https://github.com/iwahle/cfl_lbm"}

Contact

Please reach out to Iman Wahle (imanwahle@gmail.com) with any questions.