连接组工具包

复杂网络表示和分析层

目录

1. 什么是连接组工具包？
   • 与基于Sonata的模型的使用
   • 非Sonata示例
   • 摘要
2. 安装
3. 示例
4. 更多信息
   • 内容与概述
   • 功能
   • 在.json配置中定义分析
5. 贡献指南
6. 引用
7. 致谢和资助

什么是连接组工具包以及它提供了什么？

Connectome Utilities 的目的是通过提供一个桥梁，将现有的分析与其模型表示之间连接起来，简化对网络详细模型的拓扑分析。其目的不是提供分析本身，因为已经有许多针对此目的的现有软件包和解决方案。而是简化将其应用于与节点和边属性相互依赖的复杂、非同质网络。这体现在两种类型的功能：首先，将复杂的连接组加载到仍然保留显著细节的简化表示中。其次，自动化标准操作，如提取特定子网络和生成统计控制。

关于第一个问题，提供了从 SONATA 模型加载的功能。但是一旦加载，表示就独立于 Sonata，第二点也为非 Sonata 网络提供了实用功能。

与基于Sonata的模型的使用

为了说明，我们将从神经回路生物详细模型领域提供一些示例，尽管这些方法本身也可以用于其他领域以及更简化的神经元网络。

• 示例 1：要分析一个电路模型的网络，但用户希望分别分析不同的神经元类型，因为已知它们的连接性差异很大。Connectome Utilities 提供了对分离路径应用相同分析以及比较结果的自动化应用。

• 示例 2：在网络上已经识别出神经元子网络。用户发现其连接性相对于某个度量是非随机的。但它是否可以通过考虑一个更复杂的基线模型来解释？Connectome Utilities 处理了生成复杂控制模型、应用分析和比较结果。请注意（如同分析一样），控制连接性模型需要由用户提供，但 Connectome Utilities 简化了其执行和分析。

• 示例 3：基于前一个示例，用户发现非随机连接性趋势不能由复杂控制解释。可能非随机方面可以通过子网络的神经元组成来解释，例如，它可能偏向于采样中间神经元。或者，它可能有更深的根源。为了决定这一点，Connectome Utilities 提供了从基础网络中采样具有与原始样本相同神经元类型分布或相同神经元位置分布的随机控制子网络。它还提供了在数据和控制上运行相同分析并比较其结果的功能。

• 示例 4：要分析一个大型网络模型。用户希望将其分析在由体素化大脑图谱提供的空间环境中进行，例如，连接在区域内部比区域之间更常见吗？Connectome Utilities 提供了从大脑图谱加载数据并将它们与网络模型进行交叉引用的功能。

• 示例 5：已经加载了一个存在于空间环境中的大型微观尺度网络模型。用户想知道网络在降低分辨率下的样子，例如，在体素化中观尺度或层之间的路径。Connectome Utilities 提供了根据空间或其他属性轻松划分网络并生成（降低尺度）商图的功能。

• 示例 6：要分析一个微观尺度网络模型。但因为它代表了一个神经元网络，它随时间而改变，这是由于可塑性。Connectome Utilities 允许表示和分析随时间变化、在结构上或功能上（即仅权重）变化的网络。

基于非 Sonata 的示例

• 非Sonata示例1：这是一个示例，展示了如何从Excel文件中加载不同发育阶段的线虫连接组数据，而不是从Sonata模型中加载。数据来源：Witvliet等人，2021和wormatlas.org。输入数据未包含在此存储库中，但笔记本中提供了下载说明。

• 非Sonata示例2：这是另一个示例，展示了如何从非Sonata模型中加载连接组数据。它加载了果蝇连接性的R格式（.rds）数据。数据来源：Mehta等人，2023。输入数据未包含在此存储库中，但笔记本中提供了下载说明。

摘要

总之，当网络比仅由节点和无权边更复杂时，必须考虑更多混杂因素，并且在分析过程中必须做出某些决策。我们提供的包使这些决策明确，并为它们提供合理的默认值。此外，该包定义并使用了一种配置文件格式，将上述任何或所有复杂性组合成json文件的形式化分析。这促进了在不同网络中重复相同分析。

上述内容围绕“ConnectivityMatrix”类及其各种派生类展开，它们提供了一种强大且详细地表示复杂网络的方法。它还提供了保存和加载操作，使数据共享更加高效。还提供了一些额外的独立功能

• 提取皮质连接拓扑映射表示的功能，该表示由BBP "白质"项目参数化。
• 同时表示多个空间尺度的连接功能。
• 在Sonata模型中神经形态上的突触之间快速计算路径距离的功能。

安装

只需运行

pip install .

所有依赖项都在setup.py中声明，并可在pypi上获取

然后可以将该包导入为"conntility"。有关更多详细信息，请参阅各种示例笔记本。

示例

用法示例可在上方列出的jupyter笔记本中找到

更多信息

内容概述

• circuit_models：在bluepy之上提供数据加载器，用于加载特定于BlueBrain模型的Sonata格式的数据。

  • circuit_models.neuron_groups：提供加载电路模型中神经元属性并按各种方案（例如，按属性值、按属性值的分箱值、按2d网格分组）进行分组的实用程序

    • 的属性值（按etype、层、mtype等）
    • 的属性值的分箱值（按坐标）
    • 将它们分组到一个2d网格中（与平面坐标结合使用最有用）除已由bluepy加载的默认属性外，它还可以添加平面映射坐标、超采样或不超采样，以及神经元深度。它还可以进一步添加从任何体素图谱中查找的属性（按神经元位置查找）以及作为布尔属性的任何预定义神经元组的成员资格。有关详细信息，请参阅以下内容。

  • circuit_models.connection_matrix：提供查找连接矩阵的有用方式。可以是单个矩阵或神经元组之间的矩阵。或者神经元组之间连接的数量（低分辨率连接组）。可以使用circuit_models.neuron_groups提供的任何非常灵活的分组方案。

• analysis：提供简化并自动化连接矩阵分析的功能。虽然基本、原子的分析不属于此存储库，但它提供了一种轻松应用于多个矩阵、由神经元属性（如层、mtypes等）定义的子矩阵以及与随机对照组进行比较的功能。

• flatmapping：在现有的扁平图之上提供功能。也就是说，它不提供创建扁平图体积的能力，而是为了从现有的扁平图中获得更多信息。这从创建“区域图像”开始，即电路扁平版本的图像，根据区域标识着色，并扩展到超采样扁平图，即超越其像素分辨率，甚至将这些任意像素坐标转换为基于um的坐标系。

• io：提供将多个连接矩阵保存/加载到单个hdf5文件中的功能。这些矩阵必须是pandas.Series的值，以任何方式索引。当使用此功能再次加载此类Series时，将采用懒加载方案，即实际的下层数组只有在第一次实际访问时才会加载。如果您只对Series中的少数几个矩阵感兴趣，这可能很有用。

功能

我们可以从概念上将连接分析分成几个部分

• 加载神经元：首先在电路模型中查找神经元及其属性
• 过滤神经元：接下来，通过过滤掉不感兴趣的神经元来找到您真正感兴趣的神经元。
• 分组神经元：此步骤是可选的。但也许您希望根据单独的神经元组分析结果，例如按层或mtype。
• 加载连接：接下来，加载神经元之间的连接，得到一个或多个连接矩阵
• 分析连接：最后，运行您的分析。

conntility提供了Python函数来简化并标准化这些步骤中的任何一个。

为了实现灵活、可重复和可重用的分析，必须通过使用.json格式的配置文件来参数化一些功能。要了解它们的格式以及如何使用它们，请参阅此文档。在那份文档中，我将带您通过一些用例，并沿途解释配置的内容。

在本文件的其余部分，我将简单概述所有函数及其目的。

• circuit_models：用于与电路模型交互和从中加载数据

  • neuron_groups：从SONATA电路中加载数据，并定义它们的组或子集

    • load_neurons：加载指定的神经元，并返回它们的属性DataFrame。除了通过bluepy访问的基本属性外，它还提供扁平化位置、超采样扁平位置以及任何在体积图谱中的属性。

    • load_projection_locations：相同，但对于单个指定的投射。

    • load_all_projection_locations：相同，加载电路模型中存在的所有投射。

    • group_by_properties：根据结构属性定义一组神经元。

    • group_by_binned_properties：相同，但对于数值（它们被分箱）。

    • group_by_grid：按空间位置分组，将空间分割成六边形、三角形或菱形网格。

    • load_filter：访问神经元属性加载（见上文），通过.json配置进行配置。

    • load_group_filter：相同，但包括对分组功能的访问。

  • simulation_conditions：一个小工具，用于从Simulation对象返回模拟条件（如在BlueConfig.json中找到的）。

  • input_spikes：一个小工具，用于返回输入给Simulation的输入脉冲，其格式与输出脉冲（pandas.Series）相同。

  • input_innervation：计算在指定时间窗口内任何神经元如何被输入（或循环！）脉冲所刺激。

  • input_innervation_from_matrix：相同，但提供自定义连接矩阵。

  • circuit_connection_matrix：最有用的：从Circuit对象中查找任何前-后突触群体的连接矩阵，包括投射纤维；对于局部连接或任何投射。

  • connection_matrix_for_gids：相同，但直接指定sonata连接体文件而不是Circuit对象。

  • circuit_group_matrices：使用上述提到的分组功能；在指定的神经元组内查找连接矩阵。

  • circuit_cross_group_matrices：类似于上一个。但除了组内的矩阵（A->A）之外，还返回组之间的矩阵（A->B）。

  • circuit_matrix_between_groups：使用上述提到的分组功能：计算指定神经元组之间连接的数量。

• flatmapping：获取平面图的更多工具。主要是指超级采样。

  • flat_region_image：生成模型平面视图的RGB图像（N x M x 3 numpy数组）的简单实用工具，不同区域用不同颜色表示。
  • apply_flatmap_with_translation：简单实用工具，帮助查找投影纤维的平面位置：由于它们放置在体积外，因此直接查找是不可能的，因此将沿着其方向向量进行平移，直到它们撞击映射体积。
  • supersample_flatmap：返回一个平面图的副本，其中位置不再是整数值，而是以浮点微米表示。也就是说，每个体素都与一个平面位置相关联，单位为um。
  • supersampled_locations：对任何3D点或3D点数组进行超级采样（并转换为um）。
  • estimate_flatmap_pixel_size：辅助函数，用于估计与单个平面图像素相对应的大约大小（单位为um）。
  • per_pixel_coordinate_transformation：非常技术性的辅助函数，提供了从原始3D坐标到超级采样平面坐标之间的中间坐标系访问权限，例如“每个像素内部的”局部坐标。

• io：输入/输出

  • logging：该包的集中式记录器
  • write_toc_plus_payload：辅助工具，以非常高效的方式将多个scipy.sparse矩阵存储在单个.hdf5文件中
  • read_toc_plus_payload：辅助工具，用于读取存储的矩阵。实现懒惰读取以实现潜在的加速。

• analysis：使应用连接分析更容易/更快/更可重复

  • Analysis：一个类实例化单个连接分析。可以在运行时动态地从任何文件导入分析。通过.json配置文件进行配置。有关详细信息，请参阅本教程。

  • get_analyses：辅助工具，用于快速读取在配置中定义的多个分析。

  • library：原则上，单个原子分析不应该包含在这个存储库中。但我暂时将其放在这里，直到它被另一个存储库采用。

    • embed_pathway：在连接矩阵（加权或未加权，稀疏或密集）上执行扩散嵌入。

  • analysis_decorators：装饰器，将连接矩阵的原子分析转换为更强大的分析。有关详细信息，请参阅本教程。

  • ConnectivityMatrix：高级类，定义神经元群体的连接以及神经元的属性。提供访问多个连接属性，如强度或权重。提供强大的过滤功能和生成随机控制样本。最好与加载配置和分析配置一起使用（请参阅本教程）

  • TimeDependentMatrix：表示连接属性（权重）随时间变化的ConnectivityMatrix。

  • ConnectivityGroup：表示单个较大群体的子群体的ConnectivityMatrices组。

引用

如果您使用此软件，请使用以下BIBTEX条目进行引用

@article {Isbister2023.05.17.541168,
	author = {James B. Isbister and Andr{\'a}s Ecker and Christoph Pokorny and Sirio Bola{\~n}os-Puchet and Daniela Egas Santander and Alexis Arnaudon and Omar Awile and Natali Barros-Zulaica and Jorge Blanco Alonso and Elvis Boci and Giuseppe Chindemi and Jean-Denis Courcol and Tanguy Damart and Thomas Delemontex and Alexander Dietz and Gianluca Ficarelli and Mike Gevaert and Joni Herttuainen and Genrich Ivaska and Weina Ji and Daniel Keller and James King and Pramod Kumbhar and Samuel Lapere and Polina Litvak and Darshan Mandge and Eilif B. Muller and Fernando Pereira and Judit Planas and Rajnish Ranjan and Maria Reva and Armando Romani and Christian R{\"o}ssert and Felix Sch{\"u}rmann and Vishal Sood and Aleksandra Teska and Anil Tuncel and Werner Van Geit and Matthias Wolf and Henry Markram and Srikanth Ramaswamy and Michael W. Reimann},
	title = {Modeling and Simulation of Neocortical Micro- and Mesocircuitry. Part II: Physiology and Experimentation},
	elocation-id = {2023.05.17.541168},
	year = {2023},
	doi = {10.1101/2023.05.17.541168},
	publisher = {Cold Spring Harbor Laboratory},
	\
	URL = {https://www.biorxiv.org/content/early/2023/05/23/2023.05.17.541168},
	eprint = {https://www.biorxiv.org/content/early/2023/05/23/2023.05.17.541168.full.pdf},
	journal = {bioRxiv}
}

致谢与资助

此软件的开发得到了瑞士联邦理工学院（EPFL）的一个研究中心——蓝色大脑项目（Blue Brain Project）的资助，该资助由瑞士联邦政府的技术科学伦理委员会提供。

版权（c）2023蓝色大脑项目 / EPFL。