transbrain 0.1.7__tar.gz

transbrain-0.1.7/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

transbrain-0.1.7/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: transbrain
+Version: 0.1.7
+Summary: TransBrain is an integrated computational framework for bidirectional translation of brain-wide phenotypes between humans and mice.
+Home-page: https://github.com/ibpshangzheng/transbrain
+Author: Shangzheng Huang, Tongyu Zhang
+Author-email: huangshangzheng@ibp.ac.cn
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib==3.7.5
+Requires-Dist: matplotlib-inline==0.1.7
+Requires-Dist: nibabel==5.2.1
+Requires-Dist: nilearn==0.10.4
+Requires-Dist: numpy==1.24.4
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: pandas==2.0.3
+Requires-Dist: scikit-learn==1.3.2
+Requires-Dist: scipy==1.10.1
+Requires-Dist: seaborn==0.13.2
+Requires-Dist: six==1.17.0

transbrain-0.1.7/README.md

@@ -0,0 +1,161 @@
+# TransBrain
+
+TransBrain is an integrated computational framework for bidirectional translation of brain-wide phenotypes between humans and mice. Specifically, TransBrain provides a systematic approach for cross-species quantitative comparison and mechanistic investigation of both normal and pathological brain functions.
+
+![TransBrain_FIG1](./figure/transbrain_fig1.jpg)
+
+What can TransBrain do?
+
+1. Exploring the similarity relationships at the transcriptional level.
+
+2. Inferring the conservation of whole-brain phenotypes.
+
+3. Transforming and annotating whole-brain functional circuits.
+
+4. Linking specific mouse models with human diseases.
+
+## Further Reading
+
+If you wish to learn more about the construction details of this method, please refer to our article: [https://www.biorxiv.org/content/10.1101/2025.01.27.635016v1](https://www.biorxiv.org/content/10.1101/2025.01.27.635016v1) (in preprint).
+
+
+## Installation
+TransBrain is on pypi: https://pypi.org/project/transbrain/
+
+To install TransBrain as a package, run:
+
+```sh
+pip install transbrain
+```
+
+You can also create a conda environment from the environment.yml file:
+
+* First, clone this repository,
+```sh
+git clone https://github.com/ibpshangzheng/transbrain.git
+```
+
+* Then, create the environment,
+```sh
+cd transbrain
+conda env create -f environment.yml
+```
+
+* Activate the environment,
+```sh
+conda activate transbrain_env
+```
+
+## Python Dependencies
+
+The project mainly depends on Python (>= 3.8.5).
+
+```
+matplotlib==3.7.5,
+matplotlib-inline==0.1.7,
+nibabel==5.2.1,
+nilearn==0.10.4,
+numpy==1.24.4,
+openpyxl==3.1.5,
+pandas==2.0.3,
+scikit-learn==1.3.2,
+scipy==1.10.1,
+seaborn==0.13.2,
+six==1.17.0
+```
+See full list in environment.yml file. 
+
+## Unit Test
+
+- We provide a [Python Unit Test](https://www.dataquest.io/blog/unit-tests-python/) module to check whether the installation was successful.
+- Clone our repository and run this file. Make sure you are in the ​**root directory**​ (where `test_transbrain.py` is located) before running the test.
+
+### File Structure
+
+    transbrain-main/
+    ├── transbrain/
+    │ └── exampledata/
+    ├── test_transbrain.py # Unit Test file
+    └── tests/ # Verification files
+
+
+```bash
+python test_transbrain.py
+```
+
+- If you see the message ``🎉 TransBrain installed successfully!!!``, it means that TransBrain is ready to use.
+
+
+## Getting Started
+### Usage
+- After installation, you can refer to the [**basic usage notebook**](./tests/basic_usage.ipynb) in the root directory of TransBrain to explore usage examples and other functions.
+- You can see detailed documentation of TransBrain [here](http://192.168.193.179:10088/)
+- We also provide a [online mapping website](http://192.168.193.179:10087/), which enables users to directly upload your data for online mapping and visualization.
+
+
+```python
+import pandas as pd
+import transbrain as tb
+
+#Initialize TransBrain for specific atlas
+Transformer = tb.trans.SpeciesTrans('bn')
+```
+
+```python
+# Example from mouse to human
+mouse_phenotype = pd.read_csv('./transbrain/exampledata/mouse/mouse_all_example_data.csv',index_col=0)
+mouse_phenotype_in_human = Transformer.mouse_to_human(mouse_phenotype, region_type='all', normalize=True)
+```
+
+```python
+# Example from human to mouse
+human_phenotype = pd.read_csv('./transbrain/exampledata/human/bn/human_bn_all_example_data.csv',index_col=0)
+human_phenotype_in_mouse = Transformer.human_to_mouse(human_phenotype, region_type='all', normalize=True)
+```
+
+```python
+# Get human phenotypes from nii file
+human_atlas = tb.atlas.fetch_human_atlas(atlas_type='bn',region_type='cortex')
+phenotype_nii_path = ('./transbrain/exampledata/human/human_example_phenotype_data.nii.gz')
+human_phenptype_extracted = tb.base.get_region_phenotypes(phenotype_nii_path, atlas_dict = human_atlas)
+```
+
+```python
+# Get mouse phenotypes from nii file
+mouse_atlas = tb.atlas.fetch_mouse_atlas(region_type='all')
+phenotype_nii_path = ('./transbrain/exampledata/mouse/mouse_example_phenotype_data.nii.gz')
+mouse_phenptype_extracted = tb.base.get_region_phenotypes(phenotype_nii_path, atlas_dict = mouse_atlas)
+```
+
+
+```python
+# Get graph embeddings 
+Transformer = tb.trans.SpeciesTrans('bn')
+Human_Mouse_embedding_bn = Transformer._load_embeddings()
+```
+
+This allows seamless integration into your existing workflows. 🚀
+
+
+### Toturials
+We provided [**Tutorial Cases**](#tutorial-cases) demonstrating how to apply TransBrain for cross-species translation and comparison, which includes:
+
+* Analyzing and visualizing transcriptional similarity between humans and mice.
+
+* Characterizing the evolutionary spectrum of resting-state fMRI network phenotypes.
+
+* Annotating the optogenetic circuits in mice using Neurosynth.
+
+* Linking gene mutations to imaging phenotype deviations in autism.
+
+The analysis process and figures can be viewed in the Jupyter Notebook. The necessary files and datas for completing these analysis are included in the notebook's folder.
+
+
+
+## License
+This project is covered under the Apache 2.0 License.
+
+## Support
+For questions and comments, please file a Github issue and/or email Shangzheng Huang(huangshangzheng@ibp.ac.cn)
+
+

transbrain-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transbrain-0.1.7/setup.py

@@ -0,0 +1,32 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="transbrain",  
+    version="0.1.7",        
+    author="Shangzheng Huang, Tongyu Zhang",
+    author_email="huangshangzheng@ibp.ac.cn",
+    description="TransBrain is an integrated computational framework for bidirectional translation of brain-wide phenotypes between humans and mice.", 
+    long_description_content_type="text/markdown",
+    url="https://github.com/ibpshangzheng/transbrain",  
+    packages=find_packages(), 
+    include_package_data=True,
+    install_requires=[
+        "matplotlib==3.7.5",
+        "matplotlib-inline==0.1.7",
+        "nibabel==5.2.1",
+        "nilearn==0.10.4",
+        "numpy==1.24.4",
+        "openpyxl==3.1.5",
+        "pandas==2.0.3",
+        "scikit-learn==1.3.2",
+        "scipy==1.10.1",
+        "seaborn==0.13.2",
+        "six==1.17.0",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        'License :: OSI Approved :: Apache Software License',
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.8",
+)

transbrain-0.1.7/transbrain/__init__.py

@@ -0,0 +1,4 @@
+from transbrain import trans
+from transbrain import base
+from transbrain import atlas
+from transbrain import config

transbrain-0.1.7/transbrain/atlas.py

@@ -0,0 +1,146 @@
+import os
+import pandas as pd
+import numpy as np
+from nilearn import image
+from transbrain.config import Config
+from typing import Literal
+
+AtlasType = Literal['bn', 'dk', 'aal']
+RegionType = Literal['cortex', 'subcortex', 'all']
+
+def fetch_human_atlas(atlas_type: AtlasType = 'bn', region_type: RegionType = 'all'):
+    """
+    Fetch a human brain atlas image and its region information.
+
+    This function loads a labeled brain atlas image (e.g., Brainnetome, Desikan-Killiany, or AAL) 
+    along with its corresponding ROI (region of interest) metadata table.
+
+    Parameters
+    ----------
+    atlas_type : {'bn', 'dk', 'aal'}, optional
+        The type of atlas to load. Must be one of:
+        - 'bn'  : Brainnetome Atlas
+        - 'dk'  : Desikan-Killiany Atlas
+        - 'aal' : Automated Anatomical Labeling (AAL) Atlas
+        Default is 'bn'.
+    
+    region_type : {'cortex', 'subcortex', 'all'}, optional
+        Which regions to include in returned region names and info table: cortical, subcortical, or all. Default is 'all'.
+
+    Returns
+    -------
+    dict
+        A dictionary with the following keys:
+        - 'atlas' : nibabel.Nifti1Image
+            The loaded NIfTI image of the atlas.
+        - 'atlas_data' : np.ndarray
+            The atlas volume data as a NumPy array.
+        - 'region_info' : np.ndarray
+            A list of anatomical region names, extracted from the 'Anatomical Name' column of the label file.
+        - 'info_table' : pandas.DataFrame
+            The full region-of-interest (ROI) information table including additional metadata.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the atlas image file or the ROI label file is not found.
+    """
+
+    # Load the Human atlas image
+    human_atlas_path,human_labels_path = Config.atlas_resources[atlas_type]
+
+    if not os.path.exists(human_atlas_path):
+        raise FileNotFoundError(f"Human atlas file not found at {human_atlas_path}")
+    human_brain_atlas = image.load_img(human_atlas_path)
+
+    # Load the ROI information table
+    if not os.path.exists(human_labels_path):
+        raise FileNotFoundError(f"ROI information file not found at {human_labels_path}")
+    
+    human_brain_info_all = pd.read_csv(human_labels_path,index_col=0)
+    human_brain_atlas_data = np.asarray(human_brain_atlas.dataobj).astype(np.int32)
+    
+    # Extract region information based on region_type
+    cortex_region_list = Config.region_resources[atlas_type][0]
+    subcortex_region_list = Config.region_resources[atlas_type][1]
+
+    if region_type == 'cortex':
+        human_brain_info = human_brain_info_all.loc[human_brain_info_all['Anatomical Name'].isin(cortex_region_list)]
+        human_brain_info = human_brain_info.reset_index(drop=True)
+        region_info = human_brain_info['Anatomical Name'].values  # Cortex regions
+    elif region_type == 'subcortex':
+        human_brain_info = human_brain_info_all.loc[human_brain_info_all['Anatomical Name'].isin(subcortex_region_list)]
+        human_brain_info = human_brain_info.reset_index(drop=True)
+        region_info = human_brain_info['Anatomical Name'].values  # Cortex regions
+    elif region_type == 'all':
+        human_brain_info = human_brain_info_all
+        region_info = human_brain_info['Anatomical Name'].values 
+    else:
+        raise ValueError(f"Invalid region_type: {region_type}")
+
+
+    # Return the results as a dictionary
+    return {
+        'atlas': human_brain_atlas,
+        'atlas_data': human_brain_atlas_data,
+        'region_info': region_info,
+        'info_table': human_brain_info
+    }
+
+
+def fetch_mouse_atlas(region_type: RegionType = 'all'):
+    """
+    Fetch the Mouse atlas data and related information.
+
+    Parameters:
+    ----------
+        region_type : {'cortex', 'subcortex', 'all'}, optional
+            Which regions to include in returned region names and info table: cortical, subcortical, or all. Default is 'all'.
+
+    Returns:
+        dict: A dictionary containing the following keys:
+              - 'atlas': The loaded Mouse atlas image.
+              - 'atlas_data': The atlas data as a numpy array.
+              - 'region_info': A list of anatomical names for the specified regions.
+              - 'info_table': The full ROI information table.
+    """
+    mouse_atlas_path,mouse_labels_path = Config.atlas_resources['mouse']
+
+    if not os.path.exists(mouse_atlas_path):
+        raise FileNotFoundError(f"Mouse atlas file not found at {mouse_atlas_path}")
+    mouse_brain_atlas = image.load_img(mouse_atlas_path)
+
+    # Load the ROI information table
+    if not os.path.exists(mouse_labels_path):
+        raise FileNotFoundError(f"ROI information file not found at {mouse_labels_path}")
+    mouse_brain_info_all = pd.read_csv(mouse_labels_path,index_col=0)
+
+    # Extract region information based on region_type
+    cortex_region_list = Config.region_resources['mouse'][0]
+    subcortex_region_list = Config.region_resources['mouse'][1]
+
+    if region_type == 'cortex':
+        mouse_brain_info = mouse_brain_info_all.loc[mouse_brain_info_all['Anatomical Name'].isin(cortex_region_list)]
+        mouse_brain_info = mouse_brain_info.reset_index(drop=True)
+        region_info = mouse_brain_info['Anatomical Name'].values  # Cortex regions
+    elif region_type == 'subcortex':
+        mouse_brain_info = mouse_brain_info_all.loc[mouse_brain_info_all['Anatomical Name'].isin(subcortex_region_list)]
+        mouse_brain_info = mouse_brain_info.reset_index(drop=True)
+        region_info = mouse_brain_info['Anatomical Name'].values  # Cortex regions
+    elif region_type == 'all':
+        mouse_brain_info = mouse_brain_info_all
+        region_info = mouse_brain_info['Anatomical Name'].values 
+    else:
+        raise ValueError(f"Invalid region_type: {region_type}")
+
+
+    # Convert the atlas data to a numpy array
+    mouse_atlas_data = np.asarray(mouse_brain_atlas.dataobj).astype(np.float32)
+
+    # Return the results as a dictionary
+    return {
+        'atlas': mouse_brain_atlas,
+        'atlas_data': mouse_atlas_data,
+        'region_info': region_info,
+        'info_table': mouse_brain_info
+    }

transbrain-0.1.7/transbrain/base.py

@@ -0,0 +1,81 @@
+import numpy as np
+import pandas as pd
+from scipy import ndimage
+from nilearn import image
+from transbrain.config import Config
+
+def get_region_phenotypes(phenotype_nii_path: str,atlas_dict: dict,method: str = 'mean',resample: bool = True,label_column: str = 'Atlas Index',
+    region_column: str = 'Anatomical Name') -> pd.DataFrame:
+
+    """
+    Calculate region-wise phenotype values using a specified brain atlas.
+
+    This function extracts regional statistics (mean or sum) from a phenotype NIfTI image 
+    based on a chosen human or mouse brain atlas. The phenotype image can be automatically 
+    resampled to match the atlas resolution if needed.
+
+    Parameters
+    ----------
+    phenotype_nii_path : str
+        Path to the input phenotype NIfTI file. Should be in MNI space for human atlases,
+        or Allen CCFv3 space for mouse atlas.
+    atlas_dict : dict
+        A dictionary containing the following keys:
+        - 'atlas': The loaded Mouse atlas image.
+        - 'atlas_data': The atlas data as a numpy array.
+        - 'region_info': A list of anatomical names for the specified regions.
+        - 'info_table': The full ROI information table.
+
+    method : {'mean', 'sum'}, optional
+        Method for aggregating voxel values within each region. Default is 'mean'.
+    resample : bool, optional
+        If True, resample the atlas to match the shape and resolution of the phenotype image.
+        Default is True.
+    label_column : str, optional
+        Name of the column in the atlas label CSV that contains numeric label indices.
+        Default is 'Atlas Index'.
+    region_column : str, optional
+        Name of the column in the atlas label CSV that contains region names.
+        Default is 'Anatomical Name'.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame with aggregated phenotype values (mean or sum) for each region, , indexed by brain region name.
+    """
+
+    if method not in ('mean', 'sum'):
+        raise ValueError(f"Invalid method: '{method}'. Use 'mean' or 'sum'")
+    
+    atlas_path = atlas_dict['atlas']
+    atlas_arr = atlas_dict['atlas_data']
+    atlas_df = atlas_dict['info_table']
+    labels = atlas_df[label_column].values
+
+    phenotype_img = image.load_img(phenotype_nii_path)
+    atlas_img = image.load_img(atlas_path)
+
+    if resample and phenotype_img.shape != atlas_img.shape:
+        print("Resampling phenotype to match atlas...")
+        atlas_img = image.resample_to_img(atlas_img, phenotype_img, interpolation='nearest')
+
+    phenotype_arr = np.asarray(phenotype_img.dataobj)
+
+    if phenotype_arr.shape != atlas_arr.shape:
+        raise ValueError("Phenotype and atlas shape mismatch after resampling")
+    
+    if method == 'mean':
+        region_values = ndimage.mean(phenotype_arr, labels=atlas_arr, index=labels)
+    else: 
+        region_values = ndimage.sum(phenotype_arr, labels=atlas_arr, index=labels)
+    
+    result_df = atlas_df.copy()
+    result_df['Phenotype'] = region_values
+
+    result_df = result_df[[region_column,'Phenotype']]
+    result_df.columns = ['Region name','Phenotype']
+    result_df = result_df.set_index('Region name')
+
+    return result_df
+
+

transbrain-0.1.7/transbrain/config.py

@@ -0,0 +1,104 @@
+import os
+
+file_path = os.path.abspath(__file__)
+dir_path = os.path.dirname(file_path)
+atlas_folder = os.path.join(dir_path, 'atlas')
+graph_embeddings_folder = os.path.join(dir_path, 'graphembeddings')
+
+
+class Config:
+    """Centralized configuration for TransBrain with minimal structure"""
+    
+    # Atlas paths
+    bnatlas_path = os.path.join(atlas_folder, 'bn_atlas_2mm_symmetry.nii.gz')
+    bnatlas_label_path = os.path.join(atlas_folder, 'bn_atlas.csv')
+    dkatlas_path = os.path.join(atlas_folder, 'dk_atlas_2mm_symmetry.nii.gz')
+    dkatlas_label_path = os.path.join(atlas_folder, 'dk_atlas.csv')
+    aalatlas_path = os.path.join(atlas_folder, 'aal_atlas_2mm_symmetry.nii.gz')
+    aalatlas_label_path = os.path.join(atlas_folder, 'aal_atlas.csv')
+    mouseatlas_path = os.path.join(atlas_folder, 'mouse_atlas.nii.gz')
+    mouseatlas_label_path = os.path.join(atlas_folder, 'mouse_atlas.csv')
+
+    atlas_resources = {
+        'bn': (bnatlas_path, bnatlas_label_path),
+        'dk': (dkatlas_path, dkatlas_label_path),
+        'aal': (aalatlas_path, aalatlas_label_path),
+        'mouse': (mouseatlas_path, mouseatlas_label_path)
+    }
+    
+    # Graph embeddings paths
+    bn_embeddings = os.path.join(graph_embeddings_folder, 'bn_p0.01_q0.1_graph_embeddings.pkl')
+    dk_embeddings = os.path.join(graph_embeddings_folder, 'dk_p0.01_q0.1_graph_embeddings.pkl')
+    aal_embeddings = os.path.join(graph_embeddings_folder, 'aal_p0.01_q0.1_graph_embeddings.pkl')
+
+    embeddings_resources = {
+        'bn': bn_embeddings,
+        'dk': dk_embeddings,
+        'aal': aal_embeddings,
+    }
+    
+    # Region definitions
+    BN_CORTICAL = (
+        'A8m', 'A8dl', 'A9l','A6dl', 'A6m', 'A9m', 'A10m', 'A9/46d', 'IFJ', 'A46', 'A9/46v', 
+        'A8vl', 'A6vl','A10l', 'A44d', 'IFS', 'A45c', 'A45r', 'A44op', 'A44v','A14m', 'A12/47o', 
+        'A11l','A11m', 'A13', 'A12/47l','A32p','A32sg','A24cd','A24rv','A4hf', 'A6cdl', 'A4ul', 
+        'A4t', 'A4tl', 'A6cvl','A1/2/3ll', 'A4ll','A1/2/3ulhf', 'A1/2/3tonIa', 'A2','A1/2/3tru',
+        'A7r', 'A7c', 'A5l', 'A7pc', 'A7ip', 'A39c', 'A39rd', 'A40rd', 'A40c', 'A39rv','A40rv', 
+        'A7m', 'A5m', 'dmPOS','A31','A23d','A23c','A23v','cLinG', 'rCunG','cCunG', 'rLinG', 
+        'vmPOS', 'mOccG', 'V5/MT+', 'OPC', 'iOccG', 'msOccG', 'lsOccG', 'G', 'vIa', 'dIa', 
+        'vId/vIg', 'dIg', 'dId','A38m', 'A41/42', 'TE1.0 and TE1.2', 'A22c', 'A38l', 'A22r', 
+        'A21c','A21r', 'A37dl', 'aSTS', 'A20iv', 'A37elv', 'A20r', 'A20il', 'A37vl', 'A20cl',
+        'A20cv', 'A20rv', 'A37mv', 'A37lv', 'A35/36r', 'A35/36c', 'lateral PPHC', 'A28/34', 
+        'TH','TI','rpSTS','cpSTS'
+    )
+    
+    BN_SUBCORTICAL = (
+        'mAmyg', 'lAmyg', 'CA1', 'CA4DG', 'CA2CA3', 'subiculum','Claustrum', 
+        'head of caudate', 'body of caudate', 'Putamen','posterovemtral putamen', 
+        'nucleus accumbens','external segment of globus pallidus',
+        'internal segment of globus pallidus', 'mPMtha', 'Stha','cTtha', 'Otha',
+        'mPFtha','lPFtha','rTtha', 'PPtha'
+    )
+    
+    DK_CORTICAL = (
+        'caudalanteriorcingulate','rostralanteriorcingulate','caudalmiddlefrontal',
+        'rostralmiddlefrontal','superiorfrontal','lateralorbitofrontal','medialorbitofrontal',
+        'parsopercularis','parsorbitalis','parstriangularis','precentral','postcentral',
+        'inferiorparietal','superiorparietal','supramarginal','paracentral','posteriorcingulate',
+        'isthmuscingulate','pericalcarine','cuneus','lingual','lateraloccipital','insula',
+        'transversetemporal','superiortemporal','middletemporal','inferiortemporal','temporalpole',
+        'parahippocampal','entorhinal','fusiform'
+    )
+    
+    DK_SUBCORTICAL = (
+        'Amygdala','Hippocampus','Accumbens-area','Putamen','Caudate','Pallidum','Thalamus-Proper'
+    )
+    
+    AAL_CORTICAL = (
+        'CingulateAnt', 'CingulateMid', 'FrontalSupMedial','FrontalSup2','FrontalMid2','OFCmed',
+        'OFCant','OFCpost','OFClat','FrontalMedOrb','FrontalInfOrb2','FrontalInfOper',
+        'FrontalInfTri','RolandicOper','SuppMotorArea','Precentral','Postcentral','ParietalSup',
+        'ParietalInf','SupraMarginal','Angular','ParacentralLobule','Precuneus','CingulatePost',
+        'Calcarine','Cuneus','Lingual','OccipitalSup','OccipitalMid','OccipitalInf','Insula',
+        'Heschl','TemporalSup','TemporalMid','TemporalInf','TemporalPoleSup','TemporalPoleMid',
+        'ParaHippocampal','Fusiform'
+    )
+    
+    AAL_SUBCORTICAL = ('Amygdala','Hippocampus','Caudate','Putamen','Pallidum','Thalamus')
+    
+    MOUSE_CORTICAL = (
+        'ACAd', 'ACAv', 'PL','ILA', 'ORBl', 'ORBm', 'ORBvl','MOp','SSp-n', 'SSp-bfd', 'SSp-ll', 'SSp-m',
+        'SSp-ul', 'SSp-tr', 'SSp-un','SSs','PTLp','RSPagl','RSPd', 'RSPv','VISpm','VISp','VISal','VISl',
+        'VISpl','AId','AIp','AIv','GU','VISC','TEa', 'PERI', 'ECT','AUDd', 'AUDp','AUDpo', 'AUDv'
+    )
+    
+    MOUSE_SUBCORTICAL = (
+        'LA', 'BLA', 'BMA', 'PA','CA1', 'CA2', 'CA3', 'DG', 'SUB', 'ACB', 'CP', 'FS', 'SF', 'SH','sAMY', 
+        'PAL', 'VENT', 'SPF', 'SPA', 'PP', 'GENd', 'LAT', 'ATN','MED', 'MTN', 'ILM', 'GENv', 'EPI', 'RT'
+    )
+    
+    region_resources = {
+        'bn': (list(BN_CORTICAL), list(BN_SUBCORTICAL)),
+        'dk': (list(DK_CORTICAL), list(DK_SUBCORTICAL)),
+        'aal': (list(AAL_CORTICAL), list(AAL_SUBCORTICAL)),
+        'mouse': (list(MOUSE_CORTICAL), list(MOUSE_SUBCORTICAL))}

transbrain-0.1.7/transbrain/trans.py

@@ -0,0 +1,221 @@
+import numpy as np
+import pandas as pd
+import pickle
+import logging
+from typing import Literal
+from sklearn.linear_model import LinearRegression
+from sklearn.preprocessing import MinMaxScaler
+from transbrain.config import Config
+
+
+logging.basicConfig(level=logging.INFO)
+RegionType = Literal['cortex', 'subcortex', 'all']
+
+class SpeciesTrans:
+    """
+    Transfer phenotypes between species using graph embeddings.
+
+    Parameters
+    ----------
+    atlas_type : {'bn', 'dk', 'aal'}, optional
+        The type of atlas to load:
+        - 'bn'  : Brainnetome Atlas
+        - 'dk'  : Desikan-Killiany Atlas
+        - 'aal' : Automated Anatomical Labeling (AAL) Atlas
+        Default is 'bn'.
+
+    Attributes
+    ----------
+    atlas_type : str
+        The selected atlas type.
+    regions : dict
+        Dictionary containing human and mouse brain regions (cortex, subcortex, all).
+    embeddings : np.ndarray
+        Loaded graph embeddings used for phenotype translation.
+    """
+    
+    def __init__(self, atlas_type: str = 'bn'):
+        self.atlas_type = atlas_type
+        self.regions = self._load_region_data()
+        self.embeddings = self._load_embeddings()
+        logging.info(f'Initialized for {atlas_type} atlas.')
+
+    def _load_region_data(self) -> dict:
+        h_cortex, h_subcortex = Config.region_resources[self.atlas_type]
+        m_cortex, m_subcortex = Config.region_resources['mouse']
+        return {
+            'human': {'cortex': h_cortex, 'subcortex': h_subcortex, 'all': h_cortex + h_subcortex},
+            'mouse': {'cortex': m_cortex, 'subcortex': m_subcortex, 'all': m_cortex + m_subcortex}
+        }
+
+    def _load_embeddings(self) -> np.ndarray:
+        with open(Config.embeddings_resources[self.atlas_type], 'rb') as f:
+            return pickle.load(f)
+
+    def _dual_mapping(self, pheno_data: np.ndarray, source_matrix: np.ndarray, 
+                     target_matrix: np.ndarray, normalize: bool = False,restore: bool = False) -> np.ndarray:
+
+        """
+        Map phenotype data from source to target space using dual regression.
+
+        Parameters
+        ----------
+        pheno_data : np.ndarray
+            An array of phenotype values (regions,) in the source species.
+        source_matrix : np.ndarray
+            The embedding matrix for the source species.
+        target_matrix : np.ndarray
+            The embedding matrix for the target species.
+        normalize : bool, optional
+            Whether to normalize the phenotype values before regression. Default is False.
+        restore : bool, optional
+            Whether to inverse-transform the predicted values back to original scale.
+            Only used if `normalize=True`.
+
+        Returns
+        -------
+        np.ndarray
+            An array of predicted phenotype values in the target species.
+        """
+
+        if restore and not normalize:
+            raise ValueError("Restore requires normalized input.")
+            
+        y = pheno_data.reshape(-1, 1)
+        scaler = MinMaxScaler() if normalize else None
+        
+        if normalize:
+            y = scaler.fit_transform(y)
+        
+        model = LinearRegression().fit(source_matrix, y.ravel())
+        prediction = model.predict(target_matrix)
+        
+        if restore:
+            return scaler.inverse_transform(prediction.reshape(-1, 1)).ravel()
+        return prediction
+
+    def _translate(self, phenotype: pd.DataFrame, direction: str, region_type: RegionType = 'cortex',
+                  normalize: bool = True,restore: bool = False) -> pd.DataFrame:
+        """
+        Unified translation method for both directions.
+
+        Parameters
+        ----------
+        phenotype : pd.DataFrame
+            A DataFrame where rows are brain regions and columns are phenotype types.
+        direction : {'human_to_mouse', 'mouse_to_human'}
+            The translation direction.
+        region_type : {'cortex', 'subcortex', 'all'}, optional
+            The region subset to use for translation. Default is 'cortex'.
+        normalize : bool, optional
+            Whether to normalize phenotype values before translation. Default is True.
+        restore : bool, optional
+            Whether to inverse-transform values back to original scale. Only used if normalize is True.
+
+        Returns
+        -------
+        pd.DataFrame
+            Translated phenotype values in the target species, indexed by brain region name.
+        """
+
+        if direction not in ['human_to_mouse', 'mouse_to_human']:
+            raise ValueError("Invalid translation direction.")
+            
+        source_species, target_species = direction.split('_to_')
+        region_data = self.regions[source_species][region_type]
+
+        phenotype = phenotype.T[region_data].T
+        n_cortex = len(self.regions[source_species]['cortex'])
+        n_subcortex = len(self.regions[source_species]['subcortex'])
+        
+        if region_type == 'cortex':
+            padding = ((0, 0), (0, n_subcortex))
+        elif region_type == 'subcortex':
+            padding = ((0, 0), (n_cortex, 0))
+        else:
+            padding = None
+        
+        n_human = len(self.regions['human']['all'])
+        embed_slices = {
+            'mouse_to_human': (slice(n_human, None), slice(0, n_human)),
+            'human_to_mouse': (slice(0, n_human), slice(n_human, None))
+        }
+        src_slice, tgt_slice = embed_slices[direction]
+        
+        results = {}
+        for phenotype_name, values in phenotype.items():
+            arr = np.pad(values.values[None, :], padding) if padding else values.values[None, :]
+            predictions = []
+            
+            for emb in self.embeddings:
+                src_mat = emb[src_slice]
+                tgt_mat = emb[tgt_slice]
+                pred = self._dual_mapping(arr, src_mat, tgt_mat, normalize, restore)
+                predictions.append(pred)
+                
+            results[phenotype_name] = np.mean(predictions, axis=0)
+        
+        target_regions = self.regions[target_species]
+        if region_type == 'cortex':
+            results = {k: v[:len(target_regions['cortex'])] for k, v in results.items()}
+            index = target_regions['cortex']
+        elif region_type == 'subcortex':
+            results = {k: v[-len(target_regions['subcortex']):] for k, v in results.items()}
+            index = target_regions['subcortex']
+        else:
+            index = target_regions['all']
+        
+        logging.info(f'Successfully translated {source_species} {region_type} region to {target_species}.')
+        return pd.DataFrame(results, index=index)
+
+    def mouse_to_human(self, phenotype: pd.DataFrame, region_type: RegionType = 'cortex',
+                      normalize: bool = True,restore: bool = False) -> pd.DataFrame:
+        
+        """
+        Translate mouse phenotype to human.
+
+        Parameters
+        ----------
+        phenotype : pd.DataFrame
+            Mouse phenotype DataFrame (regions × phenotypes).
+        region_type : {'cortex', 'subcortex', 'all'}, optional
+            The brain region type to translate. Default is 'cortex'.
+        normalize : bool, optional
+            Whether to normalize data before translation. Default is True.
+        restore : bool, optional
+            Whether to restore values back to original scale after translation. Only used if normalize is True.
+            Please enable this parameter with caution, unless you are certain that the distributions of this phenotype are consistent between the two species.
+
+        Returns
+        -------
+        pd.DataFrame
+            Translated human phenotype DataFrame (regions × phenotypes).
+        """
+
+        return self._translate(phenotype, 'mouse_to_human', region_type, normalize, restore)
+
+    def human_to_mouse(self, phenotype: pd.DataFrame, region_type: RegionType = 'cortex',
+                      normalize: bool = True,restore: bool = False) -> pd.DataFrame:
+
+        """
+        Translate human phenotype to mouse.
+
+        Parameters
+        ----------
+        phenotype : pd.DataFrame
+            Human phenotype DataFrame (regions × phenotypes).
+        region_type : {'cortex', 'subcortex', 'all'}, optional
+            The brain region type to translate. Default is 'cortex'.
+        normalize : bool, optional
+            Whether to normalize data before translation. Default is True.
+        restore : bool, optional
+            Whether to restore values back to original scale after translation. Only used if normalize is True.
+            Please enable this parameter with caution, unless you are certain that the distributions of this phenotype are consistent between the two species.
+
+        Returns
+        -------
+        pd.DataFrame
+            Translated mouse phenotype DataFrame (regions × phenotypes).
+        """
+        
+        return self._translate(phenotype, 'human_to_mouse', region_type, normalize, restore)

transbrain-0.1.7/transbrain.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: transbrain
+Version: 0.1.7
+Summary: TransBrain is an integrated computational framework for bidirectional translation of brain-wide phenotypes between humans and mice.
+Home-page: https://github.com/ibpshangzheng/transbrain
+Author: Shangzheng Huang, Tongyu Zhang
+Author-email: huangshangzheng@ibp.ac.cn
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib==3.7.5
+Requires-Dist: matplotlib-inline==0.1.7
+Requires-Dist: nibabel==5.2.1
+Requires-Dist: nilearn==0.10.4
+Requires-Dist: numpy==1.24.4
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: pandas==2.0.3
+Requires-Dist: scikit-learn==1.3.2
+Requires-Dist: scipy==1.10.1
+Requires-Dist: seaborn==0.13.2
+Requires-Dist: six==1.17.0

transbrain-0.1.7/transbrain.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+setup.py
+transbrain/__init__.py
+transbrain/atlas.py
+transbrain/base.py
+transbrain/config.py
+transbrain/trans.py
+transbrain.egg-info/PKG-INFO
+transbrain.egg-info/SOURCES.txt
+transbrain.egg-info/dependency_links.txt
+transbrain.egg-info/requires.txt
+transbrain.egg-info/top_level.txt

transbrain-0.1.7/transbrain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

transbrain-0.1.7/transbrain.egg-info/requires.txt

@@ -0,0 +1,11 @@
+matplotlib==3.7.5
+matplotlib-inline==0.1.7
+nibabel==5.2.1
+nilearn==0.10.4
+numpy==1.24.4
+openpyxl==3.1.5
+pandas==2.0.3
+scikit-learn==1.3.2
+scipy==1.10.1
+seaborn==0.13.2
+six==1.17.0

transbrain-0.1.7/transbrain.egg-info/top_level.txt

@@ -0,0 +1 @@
+transbrain