<jupyter_start><jupyter_text>Minimal examples of how to use MSA  Background MSA stands for **"Multiperturbation Shapley value Analysis"** and as the name suggests, it's comprised of "multiple perturbations" and "Shapley value". Fundamentally, it uses a dataset of multi-element perturbation to estimate Shapley values of each element with respect to a global function. I'll refer you to these papers for technical and conceptual details:- <NAME>, <NAME>, <NAME>, and <NAME>. 2004. “Causal Localization of Neural Function: The Shapley Value Method.” Neurocomputing 58-60 (June): 215–22.- <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>. 2004. “Fair Attribution of Functional Contribution in Artificial and Biological Networks.” Neural Computation 16 (9): 1887–1915.- <NAME>. 2007. “Shapley Ratings in Brain Networks.” Frontiers in Neuroinformatics 1 (NOV): 1–9.- Toba, <NAME>., <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, and <NAME>. 2020. “Game Theoretical Mapping of White Matter Contributions to Visuospatial Attention in Stroke Patients with Hemineglect.” Human Brain Mapping, no. February: 1–25.- Zavaglia, Melissa, and <NAME>. 2016. “Causal Functional Contributions and Interactions in the Attention Network of the Brain: An Objective Multi-Perturbation Analysis.” Brain Structure & Function 221 (5): 2553–68.The toolbox is designed to handle a large variety of systems. All it needs is a list of elements, let's say node labels, node indices, tuples (connections between nodes for examples), but I didn't really test things that are not networks! For example, if you're interested in explainable machine learning there's already a very versatile toolbox called SHAP that calculates the Shapley values of model's input features. MSA is traditionally used as a brain-mapping tool (I mean, just look at those papers) and I'm also a neuroscientist so there's a bias towards networks and lesion-mapping conceptualization. These said, let's see how MSA works using some small networks.  Defining the network and the game<jupyter_code># Uncomment the line below if you don't have them.
# !pip install networkx matplotlib seaborn
# Imports n stuff
import matplotlib as mpl
import matplotlib.pyplot as plt
import networkx as nx
import numpy as np
import seaborn as sns
#---------
from msapy import msa, utils as ut, plottings as pl
#---------
mpl.rcParams['font.family'] = 'sans-serif'
mpl.rcParams['font.sans-serif'] = 'GothamSSm'  # Will skip if you don't have Gotham typeface family
mpl.rcParams['pdf.fonttype'] = 42
mpl.rcParams['font.size'] = 10
CM = 1 / 2.54
SEED = 111
FIGPATH = "figures/minimal/"<jupyter_output><empty_output><jupyter_text>As mentioned, all MSA needs is a list of elements, that's not quite true tho it needs a game. Players (elements) should play the game and well, the game can be anything and in a way, that's the beauty of it. Here, I will define a game called "ge" that stands for "average global efficiency" (yeah it should be "age" but that would be weird!), which is a graph metric. See **[this page](https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.efficiency_measures.global_efficiency.htmlnetworkx.algorithms.efficiency_measures.global_efficiency)** for more detail.So you need to define a game, a function that encapsulates the procedure you care about while the system is being lesioned. For example, if you're using MSA in the classic sense of brain mapping, the game function is where you perform the "cognitive experiment". Keep in mind a few things:1. Take care of the edge-cases. MSA goes through all the possible ways you can lesion your system so if you're interested in the contribution (shapley value) of each node to information flow in a network, then in some of these combinations of lesions the network might end up with just a bunch of isolated nodes. Like define conditions, if len(x) < y return 0. 2. Copy your stuff before feeding it to the toolbox. Otherwise (depending on how you're lesioning the system) it might leak to the next step and messes with everything.3. The result should be "one value", a global measure that describes the system with one value.<jupyter_code>def ge(complements, graph):
    if len(complements) < 0:
        # grand coalition is in, nothing to lesion so work with the intact network.
        return nx.global_efficiency(graph)
    
    elif len(complements) == len(graph):
        # everything is gone, why calling nx.global_efficiency?
        return 0.0

    else:
        # lesion the system, calculate global efficiency
        lesioned = graph.copy()
        lesioned.remove_nodes_from(complements)
        return nx.global_efficiency(lesioned)<jupyter_output><empty_output><jupyter_text>Next, I'll make a graph with an intuitive topology, i.e., a balanced tree. Intuitively, the farther we go from the root, the smaller shapley values we will have. It's possible that the outer branch ends with negative shapley values since removing them shortenes the overal paths and improves global efficiency.<jupyter_code>G = nx.balanced_tree(3,3)
fig,ax = plt.subplots()
fig.set_dpi(150)
fig.set_size_inches((12*CM,12*CM))

ax = nx.draw(G,with_labels=True,node_color='#FFE48D',font_size=8)
plt.savefig(f"{FIGPATH}balanced_tree.pdf",dpi=300,bbox_inches='tight')<jupyter_output><empty_output><jupyter_text>MSA in actionBriefly, we'll estimate shapley values by first permuting the elements N times, then producing an instruction for which combinations to lesion.<jupyter_code>node_perms = msa.make_permutation_space(elements=list(G.nodes), n_permutations=1_000,random_seed=SEED)
print(np.shape(node_perms))
print(f'Nodes: {list(G.nodes)}\n')
print(f'Permuted nodes: {node_perms[0]}')
node_combs_template = msa.make_combination_space(permutation_space=node_perms)
node_compl_template = msa.make_complement_space(combination_space=node_combs_template, elements=list(G.nodes))
print(f'Number of lesion combinations: {len(node_combs_template)}')<jupyter_output>Number of lesion combinations: 36080<jupyter_text>Here we use the parallelized_take_contributions to actually play games and fill the values. We then use this multi-site perturbation dataset to calculate shapley values and sort them.<jupyter_code>global_eff,_ = ut.parallelized_take_contributions(complement_space=node_compl_template,
                                                  combination_space=node_combs_template,
                                                  objective_function=ge,
                                                  objective_function_params={'graph': G})
global_eff_shapley = msa.make_shapley_values(contributions=global_eff, permutation_space=node_perms)
global_eff_shapley = ut.sorter(global_eff_shapley)
global_eff_shapley.head()
intact_global_eff = nx.global_efficiency(G)
d_global_eff = ut.distribution_of_processing(shapley_vector=global_eff_shapley.mean())

par = {"ci": 95, "orient": "v", "errcolor": "k"}
colors = pl.color_code(shapley_table=global_eff_shapley)
fig,ax = plt.subplots()
ax = pl.plot_shapley_ranks(shapley_table=global_eff_shapley,colors=colors,ax=ax,barplot_params=par)

fig.set_dpi(150)
fig.set_size_inches((21*CM,5*CM))
plt.text(0.5, 0.04,f'Intact global efficiency: {intact_global_eff:.2f}')
plt.text(0.5, 0.03,f'Distribution of process: {d_global_eff:.4f}')
plt.xticks(fontsize=8)
plt.title("Contribution of each node to the Global efficiency")
plt.savefig(f"{FIGPATH}global_efficiency.pdf",dpi=300,bbox_inches='tight')<jupyter_output><empty_output><jupyter_text>Voila! Minimal example.p.s: Sum of all the shapley values will add up to the value you get if you run the analysis on the intact network (grand coalition). It's a nice sanity check. Here:<jupyter_code>print(intact_global_eff-global_eff_shapley.mean().sum())<jupyter_output>0.0<jupyter_text>Of course this might not be the case if there are stochasticity in the results. But in that case too, it should not be very far. Anyways, here's the same graph but each node is now colored by its contribution to the global efficiency.<jupyter_code>fig,ax = plt.subplots()
fig.set_dpi(150)
fig.set_size_inches((12*CM,12*CM))
colors.reverse()
ax = nx.draw(G,with_labels=True,node_color=colors,font_size=8)
plt.savefig(f"{FIGPATH}balanced_tree_colorcoded.pdf",dpi=300,bbox_inches='tight')<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.09084354722422494, 'fraction_numerical': 0.016342225426580148, 'mean_word_length': 5.178916109873794, 'pattern_counts': {'":': 3, '<': 50, '<?xml version=': 0, '>': 48, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '7', 'dir': 'jupyter-structured-clean-dedup', 'id': '447231', 'license': 'MIT', 'n_tokens_mistral': 2673, 'n_tokens_neox': 2450, 'n_words': 894, 'path': 'examples/minimal.ipynb', 'repo_name': 'ShreyDixit/msa', 'size': '8505'}