{"id":37679029,"url":"https://github.com/connectomicslab/probconnatlas","last_synced_at":"2026-01-16T12:21:45.576Z","repository":{"id":70173827,"uuid":"387064424","full_name":"connectomicslab/probconnatlas","owner":"connectomicslab","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-14T17:26:59.000Z","size":85,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-10T05:31:53.900Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/connectomicslab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-18T01:04:27.000Z","updated_at":"2025-08-12T08:53:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"cd73f0db-5c88-400d-a428-d0144afb37f3","html_url":"https://github.com/connectomicslab/probconnatlas","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/connectomicslab/probconnatlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connectomicslab%2Fprobconnatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connectomicslab%2Fprobconnatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connectomicslab%2Fprobconnatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connectomicslab%2Fprobconnatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/connectomicslab","download_url":"https://codeload.github.com/connectomicslab/probconnatlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connectomicslab%2Fprobconnatlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T12:21:44.919Z","updated_at":"2026-01-16T12:21:45.564Z","avatar_url":"https://github.com/connectomicslab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Description\nThis repository complements the paper submitted to __Scientific Data__ named _**A multi-scale probabilistic atlas of the human connectome**_.\nThe atlas and the set of open-source tools allow go beyond the description of a few well-known fiber bundles and allow to perform specific connectomic analysis with almost any brain imaging data (without the need for diffusion MRI per se). This should allow the broadest community of basic and clinical neuroscientists to perform high-end connectomice research. \nThis atlas is derived from a cohort of 66 normal adult subjects from the Human Connectome Project (_[HCP]_), whose white matter (_WM_) connectivity has been investigated with the most up to date methods and in a multi-scale manner. This is a subsample of the original 100 unrelated subjects dataset freely available at the HCP website. Only the 70 subjects belonging to the releases Q1, Q2 and Q3 were included. From these subjects, the thalamic clustering failed to provide the expected segmentation pattern for three subjects and the registration of the streamlines to MNI space failed to provide the expected spatial alignment for one subject. Thus a final cohort of 66 healthy subjects was finally used in the atlas construction.\nThe IDs, age and gender of these subjects are provided in the CSV file called __subjects_66_HCP.csv__. An example of the data stored in this file is shown in the following table:\n\n| Subject | Release | Acquisition | Gender | Age |\n| ------ | ------ | ------ | ------ | ------ |\n| 100307 | Q1 | Q01 | F | 26-30 |\n| 100408 | Q3 | Q03 | M\t| 31-35 |\n| 101915 | Q3 | Q04 | F | 31-35 |\n\nThe atlas is referenced in standard [MNI] (_Montreal Neurological Institute_) space with a high resolution T1 weighted image (__ICBM 2009c Nonlinear Asymmetric__ ). Accordingly, registration of individual brain images of various imaging modalities can be matched with the atlas, and individual expected connectivity can be mapped and put in relation with individual imaging features.\n\n## Connectome atlas\nThe developed multi-scale atlas is presented in four different files stored in **Hierarchical Data Format** ([HDF5] files with _**.h5**_ extension). Each file contains the probabilistic connectome atlas for each of the four scales. Each of these [HDF5] files contains the same groups and datasets. The main difference among them is the amount of data stored because it proportionally depends on the number of gray matter (_GM_) regions included in each parcellation scale. Each [HDF5] file contains three different groups of datasets: 1) **header**, 2) **matrices** and 3) **atlas**.\n\nInside the **header** group, the number of subjects employed to build the atlas and the required data to pass from the [HDF5] format to [Nifti-1] file format is contained in different datasets. This group also contains scale-specific information about the gray matter regions employed to separate the bundles.\nThese files can be downloaded from https://doi.org/10.5281/zenodo.4919131.\n\n| Group/Dataset | Description |\n| ------ | ------ |\n| `header/nsubjects` | Number of subjects employed to build the atlas.|\n| `header/dim` | Image dimensions.|\n| `header/voxsize` | Voxel dimensions.|\n| `header/affine` | Position of the image array data in MNI space.|\n| `header/gmcodes`| Region codes (position in the matrix). |\n| `header/gmregions`| Region names. |\n| `header/gmcolors` | Region RGB (red, green and blue) colors triplets. It can be used for networks visualization. |\n| `header/gmcoords` | Coordinates of the center-of mass in mm (MNI space). |\n\nThis information is useful for visualization purposes (ie. network visualization) and it is key to establish the relationship between the WM bundles and the real brain anatomy.\n\nThe **matrices** group contains three relevant connectivity matrices computed from the subjects sample used to create the multi-scale atlas:\n Group/Dataset | Description |\n| ------ | ------ |\n| `matrices/consistency` | Number of subjects in which at least one streamline is present connecting each pair of gray matter regions).|\n| `matrices/numbStlines` | Average number of streamlines connecting each pair of gray matter regions.|\n| `matrices/length` | Mean length of the streamlines connecting each pair of gray matter regions.|\n\nFinally, the **atlas** group contains the coordinates and subject consistency for each of the voxels belonging to each WM bundle of the developed atlas. This group contains as many datasets as the number of scale-specific bundles. The names of the datasets are defined by the codes of the GM regions connected by the probabilistic bundle (e.g., **1_10** and **10_57**: bundles connecting the regions 1 and 10 and 10 and 57, respectively).\nEach dataset contains a Nx4 matrix where N is the number of voxels belonging to the bundle. The first three columns are the X, Y and Z voxel coordinates in MNI template space, and the fourth column is the number of subjects where this specific voxel contains at least one streamline passing through it.\n\n| Group/Dataset | Description |\n| ------ | ------ |\n| `atlas/1_10` | Nx4 matrix. Where N is the number of voxels belonging to the connection bundle **1_10**. |\n| `atlas/10_57`| Nx4 matrix. Where N is the number of voxels belonging to the connection bundle **10_57**. |\n| `altas/82_92`| Nx4 matrix. Where N is the number of voxels belonging to the connection bundle **82_92**. |\n\n## Other files in the repository\n\n1. Color-coded Nifti-1 images are also provided inside the __.zip__ file named __colored_wmbundles.zip__. There is one 4D volumetric Nifti-1 image for each scale where the three volumes along the fourth dimension represent the red, green and blue channels. Different colors are for different white matter bundles and the intensity of the colors are given by the probability of the voxel to belong to certain bundles. \n\n2. The average number of streamlines and the number of bundles passing through each voxel for each scale are stored in the compressed file called __bundcount_and_tdi.zip__. \n\n3. A set of tables (__sample_tables.zip__) with the information about the cohorts employed to build and evaluate the developed multi-scale connectome atlas.\n\n## Acknowledgments\n\nThe used HCP data is provided by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University.\n\n## Open-source tools to manipulate and apply the multi-scale connectome atlas\n\nHere, a set of Python-based tools to apply the atlas within different research scopes are provided. \nThe __wm_bundles_atlas.py__ is the main tool for manipulating the connectome atlas developed at Lausanne University Hospital. It is implemented as a Python 3 application running on Ubuntu Linux, relying on different Python packages such as __[h5py]__.\n\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m \u003cMethod\u003e  -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e \n```\n\n##### Options:\nBrief description of input options:\n\n| Option | Description |\n| ------ | ------ |\n| `--method`, `-m` | Method selection (**connectivity** or **consfile**).|\n| `--out`, `-o` | Output basename. |\n| `--scale`, `-s` | Scale Id (**scale1**, **scale2**, **scale3** or **scale4**) |\n| `--bfile`, `-bf` | Nifti-1 image containing Regions of Interest or Comma-Separated Values (_**.csv**_) file. |\n| `--map`, `-p` | Scalar map. |\n| `--subth`, `-st` | Subject-level consistency threshold in percentage (0-100). |\n| `--voxth`, `-vt` | Voxel-level consistency threshold. Probability values (0-1). |\n| `--extract`, `-e` | Save individual bundles in Nifti-1 format. |\n| `--all`, `-a` | Save individual bundles intercepting any of the regions of interest inside the mask. |\n| `--collapse`, `-c` | Collapse the selected bundles into a 4D color-coded Nifti-1 file. |\n| `--force`, `-f` | Overwrite the results. |\n| `--verbose`, `-v` | Verbose (**0**, **1** or **2**). |\n| `--help`, `-h` | Help. |\n\n***\n\n## Installation\n\nRequired python packages: \n- [h5py],  [numpy], [nibabel], [time], [os], [pathlib], [argparse], [sys], [csv]\n\n---\n## Usage  of the tool\n\n#### 1. Computing connectivity matrices\nCompute the mean value of a supplied scalar map along all the bundles included in the atlas for a specific scale. It outputs a connectivity matrix where the connection strength is the mean value of the scalar map along each bundle.\n\n##### Examples\nCompute the mean, median and standard deviation values of a supplied scalar map along all the bundles included in the atlas. It outputs a connectivity matrix where the connection strength is the mean value of the scalar map along each bundle. Another file should be supplied if connectivity is selected as method. This file should be supplied through the flags --map -p.\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m connectivity -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e \n```\nOnly the connections that appears in the 70% of the subjects will be selected.\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m connectivity -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e --subth 30\n```\nOnly the connections that appears in the 73% of the subjects will be selected. For these connections, only the voxels appearing in the 80% of the subjects will be used.\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m connectivity -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e --subth 27 --voxth 0.2\n```\n\n##### Results\nThe resulting connectivity matrices are stored using the **Hierarchical Data Format** ([HDF5]).\n\nThese files are saved with extension _**.h5**_. \n:   **Mean connectivity matrix** (_-connmat-mean-scaleN.h5_)**:** The weights of this connectivity matrix represent the mean value of the scalar map along all the voxels belonging to the bundle connecting each pair of regions.\n:   **Median connectivity matrix** (_-connmat-median-scaleN.h5_)**:** The connection strength is the median value of the scalar map including all the voxels belonging to the bundle connecting each pair of regions.\n:   **Std connectivity matrix** (_-connmat-std-scaleN.h5_)**:** The connection strength is the standard deviation value of the scalar map including all the voxels belonging to the bundle connecting each pair of regions.\n\n \nOnly one group is stored inside each  HDF5 file (_**.h5**_) . This group contains different datasets with the scale-specific information about the gray matter regions employed to separate the bundles. This information is key to establish the relationship between the WM bundles and the real brain anatomy.\n\n| Group/Dataset | Description |\n| ------ | ------ |\n| `connmat/matrix` | Connectivity matrix.|\n| `connmat/gmcodes`| Region codes (position in the matrix). |\n| `connmat/gmregions`| Region names. |\n| `connmat/gmcolors` | Region RGB (red, green and blue) colors triplets. It can be used for networks visualization. |\n| `connmat/gmcoords` | Coordinates of the center-of mass in mm (MNI space). |\n\nThese files can be loaded very easily using python.\n```python\n# Importing libraries\nimport h5py\nimport numpy as np\nimport matplotlib.pyplot as plt\n\n# Reading the h5 file\nconnFilename = '\u003cmy-connmat-scaleN.h5\u003e'\nhf = h5py.File(hfName, 'r')\n\n# Loading the matrix\ntempVar       = hf.get('connmat/matrix')\n\n# Ploting the matrix using matplotlib\nplt.imshow(np.array(tempVar))\nplt.colorbar()\nplt.show()\n```\n\n\n\n#### 2. Selecting specific bundles\n\nExtract and/or save some specific bundles. The desired bundles should be supplied through a Nifti-1 file or a Comma-Separated Value (_**.csv**_) text file using the flags `--bfile` or `-bf`. If a scalar map is supplied using the options `--map` or `-o`, a table with the mean values along these bundles is stored as well. The images will be saved only if the flags `--extract` or `--e` are specified. \n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m consfile -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e \n```\n\n##### I. Using a mask file with one or more regions of interest \nIf the file is a Nifti-1 image, the bundles intercepting its non-zero values will be extracted and/or saved. If the image contains different Region of Interest (_ROIs_) only the bundles connecting two or more ROIs will be selected. \n```sh\n   $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m consfile -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e -bf \u003cMask\u003e\n```\nIf the flags `--all` or `-a` is specified then all the bundles intercepting any of these ROIs will be selected.\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m consfile -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e -bf \u003cMask\u003e -a\n```\nIf the flags `--collapse` or `-c` is specified then all the bundles will be collapses into a single 4D color-coded Nifti-1 file. It can be used to compute a binary mask of the bundles reaching the ROIs.\n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m consfile -p \u003cScalarMap\u003e -o \u003cOutputBasename\u003e -bf \u003cMask\u003e -c\n```\n\n\u003e ##### II. Using a _*.csv_ file for one or more bundles \nIf the file is a readable text file, each row of the txt file should contain the source and target regions separated by a comma (ie. 10,57). \n```sh\n    $ python wm_bundles_atlas.py -s \u003cScaleId\u003e -m consfile -p \u003cScalar Map\u003e -o \u003cOutput Basename\u003e -bf \u003cCSV file\u003e -c\n```\n\n\n###### Examples of  _*.csv_ text file\nIf the _**.csv**_ file contains two rows then the bundles between the source and the target regions codes will be selected. The first row of the file will be ignored because it is assumed that it contains the column headers. \n1. Bundles between two ROIs.\n\n| SourceROI | TargetROI |\n| ------ | ------ |\n| 10| 57|\n| 22| 48|\n| 112| 28|\n| 11| 45|\n\nIf the _**.csv**_ file contains only one row then the bundles reaching any of the specified regions will be selected. \n2. Bundles reaching one ROI.\n\n| SourceROI | \n| ------ |\n| 10|\n| 22|\n| 112|\n| 11|\n\n\u003e  Note: Any of the options described for the usage of the mask can be used for the _**.csv**_ file\n\n##### III. Results \nThe main output result, if `--method` or `--m` flag is set to **consfile**, is a Comma-Separated Value file. This file stores a table containing different columns.\n\nColumns meanings:\n:   **BundleId:**  Codes of the two gray matter regions connected by this bundle.\n:   **SourceROI** and **TargetROI:** Gray matter regions names.\n:   **Consistency:**  Percentage of the subjects used to build the atlas that contained the bundle.\n:   **MeanValue:**  Mean value of the scalar map along the bundle.\n:   **StdValue:**  Standard deviation value of the scalar map along the bundle.\n:   **MedianValue:**  Median value of the scalar map along the bundle.\n\n_**Table example**_\n| BundleId | SourceROI | TargetROI | Consistency | MeanValue | StdValue | MedianValue | \n| ------ | ------ | ------ | ------ | ------ | ------ |------ |\n| 8_55 | ctx-rh-superiorfrontal | ctx-lh-superiorfrontal | 100.0 | 0.37 | 0.17 | 0.38 | \n| 9_56 | ctx-rh-caudalmiddlefrontal | ctx-lh-caudalmiddlefrontal | 98.48 | 0.39 | 0.15 | 0.39 | \n| 10_57 | ctx-rh-precentral | ctx-lh-precentral | 98.48 | 0.43 | 0.13 | 0.42 | \n| 11_55 | ctx-rh-paracentral | ctx-lh-superiorfrontal | 100.0 | 0.52 | 0.12 | 0.52 | \n\nIf the options `--extract` or `-e` are specified, the individual bundles in Nifti-1 format will be saved. A 4D color-coded Nifti-1 file could be saved if the `--collapse` or `-c` is selected.\n\n## License\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n\n   [HDF5]: \u003chttps://www.hdfgroup.org/solutions/hdf5/\u003e\n   [https://doi.org/10.5281/zenodo.4919131]: \u003chttps://doi.org/10.5281/zenodo.4919131\u003e\n   [Nifti-1]: \u003chttps://www.nitrc.org/docman/view.php/26/204/TheNIfTI1Format2004.pdf\u003e\n   [HCP]: \u003chttps://www.humanconnectome.org\u003e\n   [HCP website]: \u003chttps://db.humanconnectome.org/\u003e\n   [MNI]: \u003chttps://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009\u003e \n   [h5py]: \u003chttps://www.h5py.org/\u003e\n   [numpy]:\u003chttps://numpy.org/\u003e\n   [nibabel]:\u003chttps://nipy.org/nibabel/\u003e\n   [time]:\u003chttps://docs.python.org/3/library/time.html\u003e\n   [os]:\u003chttps://docs.python.org/3/library/os.html\u003e\n   [pathlib]:\u003chttps://docs.python.org/3/library/pathlib.html\u003e\n   [argparse]:\u003chttps://docs.python.org/3/library/argparse.html\u003e\n   [sys]:\u003chttps://docs.python.org/3/library/sys.html\u003e\n   [csv]:\u003chttps://docs.python.org/3/library/csv.html\u003e\n   \n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnectomicslab%2Fprobconnatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconnectomicslab%2Fprobconnatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnectomicslab%2Fprobconnatlas/lists"}