Getting Started¶

MSA (Multi-perturbation Shapley value Analysis) is a Game theoretical approach for calculating the contribution of each element of a system (here network models of the brain) to a system-wide description of the system. The classic neuroscience example: How much each brain region is causally relevant to an arbitrary cognitive function.

The following examples show some of msapy's capabilities and give you an idea of the API.

For more details on the API, see API Docs.

For specific purposes, refer to the following examples:

1. PyTorch and MSA
2. Time Series MSA
3. MSA 2D

To start the code examples, we load the library

In [1]:

import numpy as np

from msapy import msa

import numpy as np from msapy import msa

Lets assume for this example that we have a system of four elements: "A", "B", "C", "D". The system produces some activity that is equal to the sum of contributions of the individual elements. For the sake of this example, we take the contribution of each element to be 50, 100, 200 and -30 with some added noise. We can write:

• $ A \sim \mathcal{N}(50,\,1)\, $
• $ B \sim \mathcal{N}(100,\,1)\, $
• $ C \sim \mathcal{N}(200,\,1)\, $
• $ D \sim \mathcal{N}(-30,\,1)\, $

In [2]:

nodes = ['A', 'B', 'C', 'D']

nodes = ['A', 'B', 'C', 'D']

Now you need an objective function. An objective function returns the value that you want to know how it's affected by different elements of your system. For this example, it's the total activity of our system. The objective function should take an argument called complements which specifies the elements that are leasioned or removed.

In [3]:

def objective_function(complements):
    contributions = {"A": 50, "B": 100, "C": 200, "D": -30}
    activity = 0.0
    for k, v in contributions.items():
        if k not in complements:
            activity += np.random.normal(v, 1)
    return activity

def objective_function(complements): contributions = {"A": 50, "B": 100, "C": 200, "D": -30} activity = 0.0 for k, v in contributions.items(): if k not in complements: activity += np.random.normal(v, 1) return activity

Now that we have all the things to run MSA, we can just call a single function

In [4]:

shapley_table = msa.interface(multiprocessing_method='joblib',
                              elements=nodes,
                              n_permutations=1000,
                              objective_function=objective_function,
                              n_parallel_games=-1,
                              random_seed=1)

shapley_table = msa.interface(multiprocessing_method='joblib', elements=nodes, n_permutations=1000, objective_function=objective_function, n_parallel_games=-1, random_seed=1)

The shapley_table returned from msa.interface is a Pandas DataFrame with columns as the elements and the rows as permutations. We can take the mean of the rows to calculate the shapley values i.e. the contribution of each element.

In [5]:

shapley_table.head()

shapley_table.head()

Out[5]:

	A	B	C	D
0	50.839483	100.641381	200.096570	-29.600767
1	51.688566	99.761323	200.650561	-30.748772
2	53.423007	99.635949	198.951589	-34.134876
3	49.359333	101.446440	198.679690	-27.510115
4	51.727647	100.589809	201.427518	-28.892053

In [6]:

shapley_table.shapley_values

shapley_table.shapley_values

Out[6]:

A     50.451432
B     99.917185
C    199.603503
D    -30.127528
dtype: float64

The contributions from the MSA are very close to the real contributions.

This was just a very simple example for how to use MSA.