Time-averaged simulations results for bi-phasic blood flow simulations in realistic microvascular networks for various single- and multi-capillary occlusion scenarios.

DOCUMENTATION - Time-averaged simulations results for bi-phasic blood flow simulations in realistic microvascular networks for various single- and multi-capillary occlusion scenarios.

Correspondence: fschmid@ethz.ch (Franca Schmid, ORCID: 0000-0002-0689-9366)

1. Related references:
The data set is published in context with the manuscript: 
[1] The severity of microstrokes depends on local vascular topology and baseline perfusion. 
F Schmid, G Conti, P Jenny and B Weber. eLife. 2021. Doi: 10.7554/eLife.60208

The bi-phasic blood flow simulations have been performed in realistic microvascular networks (MVNs) from the mouse somatosensory cortex first published in:
[2] The cortical angiome: an interconnected vascular network with noncolumnar patterns of blood flow. P Blinder, PS Tsai, JP Kaufhold, PM Knutsen, H Suhl and D Kleinfeld. Nature Neuroscience. 2013. Doi: 10.1038/nn.3426

The bi-phasic blood flow model for realistic MVNs has first been published in:
[3] Depth-dependent flow and pressure characteristics in cortical microvascular networks. F Schmid, PS Tsai, D Kleinfeld, P Jenny and B Weber. PLoS Computational Biology. 2017. Doi: 10.1371/journal.pcbi.1005392

For further information on how to perform bi-phasic blood flow simulation, please contact the corresponding authors of [1] or [3].

2. Requirements (software):
All simulations and analyses have been performed in Python 2.7. To execute the analysis script the following python libraries need to be installed: cPickle, python-igraph, pandas, seaborn, scipy. The individual analyses script can then be executed by in Python (e.g. “python plot_Figure3.py”).

3. Content:
All folders are stored as compressed archives (*.tar.bz2). On unix-based system the folders can be unpacked by: "tar –jxf  ARCHIVE_NAME"

3a. Time-averaged simulation results (python dictionaries stored as python 2.7 pickle files):
SimulationResults_Baseline.tar.bz2:
Folders: MVN1, MVN2
Content: verticesDict_baseline.pkl, edgesDict_baseline.pkl, pathsDict_allPaths_from_DA_to_AV_mainBranch.pkl (generated from prepare_Figure4.py), data_spatial_distribution_AVfactor.pkl (generated from plot_Figure4.py)

SimulationResults_SingleCapillaryOcclusions.tar.bz2:
Folders: 1-in-1-out, 1-in-2-out, 2-in-1-out, 2-in-2-out, 2-in-2-out_high, 2-in-2-out_AL1, 2-in-2-out_AL2, 2-in-2-out_AL3, 2-in-2-out_AL4, 2-in-2-out_AL5, 2-in-2-out_closeToDA, 2-in-2-out_farFromDA
Content: verticesDict_baseline.pkl, edgesDict_baseline.pkl, pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl (only folders: 1-in-1-out, 1-in-2-out, 2-in-1-out, 2-in-2-out)

SimulationResults_MultiCapillaryOcclusions.tar.bz2:
Folders: vesselsOccluded_1, vesselsOccluded_3, vesselsOccluded_5, vesselsOccluded_7, vesselsOccluded_9
Content: verticesDict_baseline.pkl, edgesDict_baseline.pkl, pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl

3b. Analysis scripts (python 2.7 scripts in folder Analyses_Scripts):
For details on the figure content see [1]. The verticesDict* and the edgesDict* are converted into graph structure (python-igraph) for all analyses. The functionality of python-igraph is used heavily throughout the various analyses.

helperFunctions.py: various functions used by the other analysis scripts

plot_Figure1_and_Figure1-supplement_1_a-d.py:
Input: SimulationResults_Baseline/MVN1/edgesDict_baseline.pkl, SimulationResults_Baseline/MVN1/verticesDict_baseline.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-2-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-2-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-1-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-1-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-2-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-2-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-1-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-1-out/verticesDict.pkl
Output: Figures/Figure_1/*, Supplementary_Figures/Figure_1-supplement_1_a-d/*

plot_Figure2_and_Figure2_supplement_1_a-d.py:
Input: SimulationResults_Baseline/MVN1/edgesDict_baseline.pkl, SimulationResults_Baseline/MVN1/verticesDict_baseline.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-2-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-2-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-1-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-1-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-2-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-2-out/verticesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-1-out/edgesDict.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-1-out/verticesDict.pkl
Output: Figures/Figure_2/*, Supplementary_Figures/Figure_2-supplement_1_a-d/*

plot_Figure3.py:
Input: SimulationResults_Baseline/MVN1/edgesDict_baseline.pkl, SimulationResults_Baseline/MVN1/verticesDict_baseline.pkl, SimulationResults_MultiCapillaryOcclusion/*/edgesDict.pkl, SimulationResults_MultiCapillaryOcclusion/*/verticesDict.pkl 
Output: Figures/Figure_3/*

prepare_Figure4.py (long execution time!):
Input: SimulationResults_Baseline/MVN*/edgesDict_baseline.pkl, SimulationResults_Baseline/MVN*/verticesDict_baseline.pkl,
Output: SimulationResults_Baseline/MVN*/pathsDict_allPaths_from_DA_to_AV_mainBranch.pkl

plot_Figure4.py (long execution time!):
Input: SimulationResults_Baseline/MVN*/*
Output: SimulationResults_Baseline/MVN*/edgesDict_baseline.pkl (attribute Lfactor_median added), SimulationResults_Baseline/MVN*/data_spatial_distribution_AVfactor.pkl, Figures/Figure_4/*

plot_Figure5.py:
Input: SimulationResults_Baseline/MVN*/* 
Output: Figures/Figure_5/*

plot_Figure6.py:
Input: SimulationResults_Baseline/MVN1/*, SimulationResults_SingleCapillaryOcclusion/2-in-2- out/pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl, SimulationResults_SingleCapillaryOcclusion/2-in-1- out/pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-2- out/pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl, SimulationResults_SingleCapillaryOcclusion/1-in-1- out/pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased.pkl Output: Figures/Figure_6/*

4. Attributes stored in python dictionaries:

4a. Baseline:
verticesDict: contains all relevant information and data stored at vertices.

• index: index of vertex
• pressure: time averaged pressure at vertex [mmHg]
• inflowE: list of edges delivering blood to the vertex (inflows of the vertex)
• outflowE: list of edges removing blood from the vertex (outflows of the vertex)
• coords: coordinates of the vertex [µm]
• pBC: pressure boundary conditions [mmHg], None for internal vertices
• corticalDepth: depth from cortical surface [µm]
• nkind: identifier for the vessel type. 0: pial artery, 1: pial vein, 2: descending arteriole, 3: ascending vein, 4: capillary

edgesDict: contains all relevant information and data stored at edges.

• diameter: effective vessel diameter [µm]. See [3] for details.
• htd: time averaged discharge hematocrit [-]. 
• connectivity: tuple of vertex indices which are connected by the edge.
• mainAV: identifier for ascending venule (AV) main brain. 1: is AV main brain, 0: no AV main branch
• mainDA: identifier for descending arteriole (DA) main brain. 1: is DA main brain, 0: no DA main branch
• flow: time averaged flow rate [µm³ ms^-1]
• length: tortuous vessel length [µm] See [1] and [3] for details.
• tissueVolume: topological tissue volume supplied by vessel [µm³]. See [1] for details.
• nkind: identifier for the vessel type. 0: pial artery, 1: pial vein, 2: descending arteriole, 3: ascending vein, 4: capillary
• edgesFulfillingSelection: identifier if vessels fulfils selection criteria to qualify for analysis. 1: vessel included for analysis, 0: vessel not included for analysis. Details on the selection criteria are provided in [1].
• htt: time averaged tube hematocrit [-]
• RBCflux: time averaged RBC flux [RBC/s] computed from the discharge hematocrit and the flow rate.
• sign: sign describing the flow direction in the vessel. +: flow direction from source (vertex with lower index) to target (vertex with higher index), -: flow direction from target to source vertex. Based on time averaged pressure values.
• points: list of tortuous vessel coordinates of the edge [µm]. Starting at the source vertex. Ending at the target vertex.
• Lfactor_median: AV-factor of the vessel. None if no AV-factor can be assigned. See [1] for details. Attribute added by plot_Figure4.py

pathsDict_allPaths_from_DA_to_AV_mainBranch: contains all flow path from DA main brain to AV main branch. For details see [1].

• startPoint: list of vertex indices of the end point of the DA
• endPoint: list of vertex indices of the end point of the AV
• allPaths: list of lists of vertex indices describing all paths between a the associated startPoint and endPoint.

data_spatial_distribution_AVfactor: contains information on the spatial distribution of venule-sided capillaries (AV-factor  > 0.5). For details see [1].

• edges_L_mean_50um: list of all edges for which the average AV-factor in an analysis sphere of 50 µm has been computed.
• resulting_L_mean_50um: average AV-factor for an analysis sphere for 50 µm (see Figure4/AV_factor_delta_analysisSphere50_MVN*.pkl)
• shortest_distance_to_closest_vessel: list of shortest distances to any vessel for all discretization points along all venule sided capillaries.
• shortest_distance_to_Lfactor_lt_05: list of shortest distances to an arteriole-sided capillary (AV-factor < 0.5) for all discretization points along all venule sided capillaries.

4b. Occlusion scenarios (both single- and multi-capillary occlusions):

verticesDict:

• index: index of vertex
• coords: coordinates of the vertex [µm]
• pressure_strokeIndex_n: time averaged pressure at vertex [mmHg] for the simulation where edge n has been occluded. For details see [1].

edgesDict:

• htd_strokeIndex_n: time averaged discharge hematocrit [-] for the simulation where edge n has been occluded. For details see [1]. 
• flow: time averaged flow rate [µm³ ms^-1] for the simulation where edge n has been occluded. For details see [1].
• RBCflux: time averaged RBC flux [RBC/s] computed from the discharge hematocrit and the flow rate for the simulation where edge n has been occluded. For details see [1].
• htt: time averaged tube hematocrit [-] for the simulation where edge n has been occluded. For details see [1].
• connectivity: tuple of vertex indices which are connected by the edge.
• diameter_strokeIndex_n: effective vessel diameter [µm] for the simulation where edge n has been occluded (only given for multi-capillary occlusions).

pathsDict_allPaths_from_DA_to_AV_mainBranch_vertexBased: contains all flow path from DA main brain to AV main branch (unique vertex sequences). For details see helperFunctions.py --> function convert_pathsDict_to_unique_vertexSequence.

• startPoint_strokeIndex_n: list of vertex indices of the end point of the DA for the simulation where edge n has been occluded.
• endpoint_strokeIndex_n: list of vertex indices of the end point of the AV for the simulation where edge n has been occluded.
• allPaths_strokeIndex_n: list of lists of vertex indices describing all paths between a the associated startPoint and endpoint for the simulation where edge n has been occluded.