Netneurotools

https://netneurotools.readthedocs.io/en/latest/
Admin
Netneurotools is a Python toolbox providing a collection of functions for network neuroscience...
Tokens:233,159
Snippets:384
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install netneurotools and Dependencies

Source: https://netneurotools.readthedocs.io/en/latest/installation

Provides commands to install netneurotools and its dependencies, including Mayavi and PySurfer, from source using pip.

```bash
pip install dist/vtk-*.whl
pip install git+https://github.com/enthought/mayavi.git
pip install git+https://github.com/nipy/PySurfer.git
pip install git+https://github.com/netneurolab/netneurotools.git
```

--------------------------------

### Install netneurotools from Source

Source: https://netneurotools.readthedocs.io/en/latest/installation

Clones the netneurotools repository from GitHub and installs the package locally using pip. This method is useful for development or when needing the latest unreleased changes. Requires Git and Python.

```shell
git clone https://github.com/netneurolab/netneurotools.git
cd netneurotools
pip install .
```

--------------------------------

### Install netneurotools from PyPI

Source: https://netneurotools.readthedocs.io/en/latest/installation

Installs the netneurotools package directly from the Python Package Index (PyPI) using pip. This is the recommended method for most users. Requires pip and Python.

```shell
pip install netneurotools
```

--------------------------------

### Build VTK Wheel for Python >= 3.9

Source: https://netneurotools.readthedocs.io/en/latest/installation

Provides commands to build a VTK wheel from source, specifically for Python versions where official wheels might not be available. This involves cloning VTK, configuring with CMake, and building the wheel. Requires Git, CMake, Ninja, and a Python executable.

```shell
git clone https://github.com/Kitware/VTK
cd VTK

mkdir build
cd build
PYBIN=<PATH TO YOUR PYTHON EXECUTABLE>
cmake -GNinja -DVTK_BUILD_TESTING=OFF -DVTK_WHEEL_BUILD=ON -DVTK_PYTHON_VERSION=3 -DVTK_WRAP_PYTHON=ON -DPython3_EXECUTABLE=$PYBIN ../

# optionally, apt install ninja
ninja
$PYBIN setup.py bdist_wheel
```

--------------------------------

### Install Pyvista and Jupyterlab with Conda

Source: https://netneurotools.readthedocs.io/en/latest/installation

Sets up a dedicated conda environment for plotting, installing Pyvista and necessary Jupyter extensions. This is the recommended approach for using the newer plotting functionalities. Requires Conda.

```shell
conda create -n plotting python=3.12
conda activate plotting
conda install -c conda-forge pyvista
# if you are using Jupyter notebooks
conda install -c conda-forge jupyterlab trame trame-vtk trame-jupyter-extension
```

--------------------------------

### Install VTK, Mayavi, and Pysurfer with Pip

Source: https://netneurotools.readthedocs.io/en/latest/installation

Installs the legacy plotting libraries (vtk, mayavi, pysurfer) using pip. These are required for older plotting functions like plot_fsaverage. Requires pip and Python.

```shell
pip install vtk mayavi pysurfer
```

--------------------------------

### Install netneurotools

Source: https://netneurotools.readthedocs.io/en/latest/index

Provides commands to install the netneurotools Python package. Users can install from PyPI for the latest stable release or directly from the GitHub repository for development versions, including options for specific branches or tags.

```bash
pip install netneurotools
```

```bash
pip install git+https://github.com/netneurolab/netneurotools.git
```

```bash
pip install git+https://github.com/netneurolab/netneurotools.git@0.2.X
```

--------------------------------

### Mayavi VTK Version Workaround

Source: https://netneurotools.readthedocs.io/en/latest/installation

A temporary workaround for errors related to VTK_MAJOR_VERSION in Mayavi by manually setting the version.

```python
# Temporary workaround: adding VTK_MAJOR_VERSION = 9 to mayavi/tvtk/vtk_module.py
```

--------------------------------

### Download fsaverage FreeSurfer template (Python)

Source: https://netneurotools.readthedocs.io/en/latest/api

Downloads files for the fsaverage FreeSurfer template. Supports specifying version, local use, and forcing re-download.

```python
fetch_fsaverage(version, use_local, force, ...)
  Download files for fsaverage FreeSurfer template.
```

--------------------------------

### Permutation Test Pearsonr Example 2

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.stats.permtest_pearsonr

Illustrates permtest_pearsonr with more strongly correlated data. This example highlights how the function can detect significant correlations with a low p-value.

```python
import numpy as np
from netneurotools import stats

x, y = stats.make_correlated_xy(corr=0.5, size=100)
print(stats.permtest_pearsonr(x, y))
```

--------------------------------

### Download CIVET template (Python)

Source: https://netneurotools.readthedocs.io/en/latest/api

Downloads files for the CIVET template. Supports specifying version and forcing re-download.

```python
fetch_civet_curated(version, force, ...)
  Download files for CIVET template.
```

--------------------------------

### Example Usage of communicability_wei

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.metrics.communicability_wei

Demonstrates how to use the communicability_wei function with a sample adjacency matrix.

```python
>>> from netneurotools import metrics
>>> import numpy as np
>>> A = np.array([[2, 0, 3], [0, 2, 1], [0.5, 0, 1]])
>>> Q = metrics.communicability_wei(A)
>>> Q
array([[0.        , 0.        , 1.93581903],
       [0.07810379, 0.        , 0.94712177],
       [0.32263651, 0.        , 0.        ]])
```

--------------------------------

### Fetch CIVET Template Data

Source: https://netneurotools.readthedocs.io/en/latest/_modules/netneurotools/datasets/fetch_template

Downloads standard CIVET template files. It validates requested versions and densities, raising errors for invalid combinations, such as '164k' density with 'v1' version. It fetches necessary files and organizes them into a Bunch object.

```python
def fetch_civet(version="v1", density="41k", force=False, data_dir=None, verbose=1):
    """
    Download files for CIVET template.

    Parameters
    ----------
    version : {{"v1", "v2"}}, optional
        Which version of CIVET to fetch.
    density : {{"41k", "164k"}}, optional
        Which density of the CIVET-space geometry files to fetch.

    Returns
    -------
    filenames : :class:`sklearn.utils.Bunch` 
        Dictionary-like object with template files.

    Other Parameters
    ----------------
    force : bool, optional
        If True, will overwrite existing dataset. Default: False
    data_dir : str, optional
        Path to use as data directory. If not specified, will check for
        environmental variable 'NNT_DATA'; if that is not set, will use
        `~/nnt-data` instead. Default: None
    verbose : int, optional
        Modifies verbosity of download, where higher numbers mean more updates.
        Default: 1
    """
    densities = ["41k", "164k"]
    if density not in densities:
        raise ValueError(
            f'The density of CIVET requested "{density}" does not exist. '
            f"Must be one of {densities}"
        )
    versions = ["v1", "v2"]
    if version not in versions:
        raise ValueError(
            f'The version of CIVET requested "{version}" does not exist. '
            f"Must be one of {versions}"
        )

    if version == "v1" and density == "164k":
        raise ValueError(
            'The "164k" density CIVET surface only exists for ' 'version "v2"'
        )

    dataset_name = "tpl-civet"
    _get_reference_info(dataset_name, verbose=verbose)

    keys = ["mid", "white"]

    fetched = fetch_file(
        dataset_name,
        keys=[version, "civet" + density],
        force=force,
        data_dir=data_dir,
        verbose=verbose,
    )

    data = {
        k: SURFACE(
            fetched / f"tpl-civet_space-ICBM152_hemi-L_den-{density}_{k}.obj",
            fetched / f"tpl-civet_space-ICBM152_hemi-R_den-{density}_{k}.obj",
        )
        for k in keys
    }
    return Bunch(**data)
```

--------------------------------

### netneurotools Experimental Module

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.metrics.effective_resistance

Documentation for the netneurotools.experimental module, containing functions in alpha stage.

```APIDOC
module: netneurotools.experimental

Description: Functions in alpha stage.

Reference: ../api.html#module-netneurotools.experimental
```

--------------------------------

### R Example for Spatial Autocorrelation

Source: https://netneurotools.readthedocs.io/en/latest/_modules/netneurotools/spatial/spatial_stats

Demonstrates how to use the R package 'spdep' to calculate spatial autocorrelation statistics, mirroring the functionality described for netneurotools.

```r
x <- rnorm(100)
y <- rnorm(100)
m <- matrix(runif(100*100), nrow=100)
lee(x, y, mat2listw(m), 100)
# or
lee.test(x, y, mat2listw(m))
```

--------------------------------

### Helper: Generate community boundaries

Source: https://netneurotools.readthedocs.io/en/latest/_modules/netneurotools/plotting/mpl_plotters

Generates the boundaries for community assignments in a data array. It sorts communities and identifies the start and end indices for each unique community. Dependencies include numpy.

```Python
def _grid_communities(communities):
    """
    Generate boundaries of `communities`.

    Parameters
    ----------
    communities : array_like
        Community assignment vector

    Returns
    -------
    bounds : list
        Boundaries of communities
    """
    communities = np.asarray(communities)
    if 0 in communities:
        communities = communities + 1

    comm = communities[np.argsort(communities)]
    bounds = []
    for i in np.unique(comm):
        ind = np.where(comm == i)
        if len(ind) > 0:
            bounds.append(np.min(ind))

    bounds.append(len(communities))

    return bounds
```

--------------------------------

### Get Available Colormaps

Source: https://netneurotools.readthedocs.io/en/latest/api

Returns a list of available colormaps within the netneurotools.plotting module. This utility function helps users discover and select appropriate colormaps for their visualizations.

```python
from netneurotools.plotting import available_cmaps

# Get the list of colormaps
# colormaps = available_cmaps()
```

--------------------------------

### Download curated fsaverage FreeSurfer template (Python)

Source: https://netneurotools.readthedocs.io/en/latest/api

Downloads curated files for the fsaverage FreeSurfer template. Supports specifying version and forcing re-download.

```python
fetch_fsaverage_curated(version, force, ...)
  Download files for fsaverage FreeSurfer template.
```

--------------------------------

### netneurotools Modules Overview

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.datasets.fetch_hansen_receptors

Overview of the main modules within the netneurotools package, indicating their primary functionalities.

```APIDOC
netneurotools:
  datasets: Automatic dataset fetching.
  networks: Constructing networks.
  plotting: Plotting brain data.
  metrics: Calculating graph metrics.
  modularity: Calculating network modularity.
  stats: General statistics functions.
  spatial: Spatial statistics.
  interface: Interface with external data and tools.
  experimental: Functions in alpha stage.

```

--------------------------------

### Example: Network Pearson Correlation with Effective Resistance Weights

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.metrics.network_pearsonr

Demonstrates how to calculate network Pearson correlation using weights derived from normalized effective resistance between nodes.

```python
import numpy as np
from netneurotools.metrics import network_pearsonr, effective_resistance

# Assume W_adj is an adjacency matrix
# For demonstration, let's create dummy data
N = 100
W_adj = np.random.rand(N, N) # Dummy adjacency matrix
np.fill_diagonal(W_adj, 0)

R_eff = effective_resistance(W_adj)
R_eff_norm = R_eff / np.max(R_eff)
W = 1 / R_eff_norm
W = W / np.max(W)
np.fill_diagonal(W, 1.0)

# Dummy annotation vectors
annot1 = np.random.rand(N)
annot2 = np.random.rand(N)

netcorr = network_pearsonr(annot1, annot2, W)
print(f"Network Pearson Correlation (Effective Resistance weights): {netcorr}")
```

--------------------------------

### Get Modularity Contribution (netneurotools.modularity)

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.modularity.get_modularity

Calculates the modularity contribution for each community in a given assignment vector using an adjacency matrix. It takes the adjacency matrix, community assignments, and an optional resolution parameter.

```APIDOC
netneurotools.modularity.get_modularity(*adjacency*, *comm*, *gamma=1*)
:   Calculate modularity contribution for each community in comm.

    Parameters:
    :   * **adjacency** (*(N, N) array_like*) – Adjacency (e.g., correlation) matrix
        * **comm** (*(N,) array_like*) – Community assignment vector splitting N subjects into G groups
        * **gamma** (*float, optional*) – Resolution parameter used in original modularity maximization.
          Default: 1

    Returns:
    :   **comm_q** – Relative modularity for each community

    Return type:
    :   (G,) ndarray

    See also

    [`netneurotools.modularity.get_modularity_z`](netneurotools.modularity.get_modularity_z.html#netneurotools.modularity.get_modularity_z "netneurotools.modularity.get_modularity_z"), [`netneurotools.modularity.get_modularity_sig`](netneurotools.modularity.get_modularity_sig.html#netneurotools.modularity.get_modularity_sig "netneurotools.modularity.get_modularity_sig")
```

--------------------------------

### Fetch fsaverage curated surface data

Source: https://netneurotools.readthedocs.io/en/latest/_modules/netneurotools/datasets/fetch_template

Downloads curated surface data for various fsaverage versions. It validates the requested version, fetches the necessary files, and organizes them into a dictionary of SURFACE objects for different surface types (white, pial, etc.) and hemispheres. Dependencies include `_get_reference_info`, `fetch_file`, `shutil`, `SURFACE`, and `Bunch`.

```python
def fetch_fsaverage_curated(version, force=False, data_dir=None, verbose=1):
    """
    Download files for fsaverage template.

    Curated by neuromaps.

    This dataset contains

    If you used this data, please cite 1_, 2_, 3_, 4_.

    Parameters
    ----------
    version : str, optional
        One of {"fsaverage", "fsaverage6", "fsaverage5", "fsaverage4"}. Default: "fsaverage"

    Returns
    -------
    filenames : :class:`sklearn.utils.Bunch`
        Dictionary-like object with template files.

    Other Parameters
    ----------------
    force : bool, optional
        If True, will overwrite existing dataset. Default: False
    data_dir : str, optional
        Path to use as data directory. If not specified, will check for
        environmental variable 'NNT_DATA'; if that is not set, will use
        `~/nnt-data` instead. Default: None
    verbose : int, optional
        Modifies verbosity of download, where higher numbers mean more updates.
        Default: 1

    References
    ----------
    .. [1] David C Van Essen, Kamil Ugurbil, Edward Auerbach, Deanna
        Barch,Timothy EJ Behrens, Richard Bucholz, Acer Chang, Liyong Chen,
        Maurizio Corbetta, Sandra W Curtiss, and others. The human connectome
        project: a data acquisition perspective. Neuroimage,
        62(4):2222–2231, 2012.
    .. [2] Matthew F Glasser, Stamatios N Sotiropoulos, J Anthony Wilson,
        Timothy S Coalson, Bruce Fischl, Jesper L Andersson, Junqian Xu, Saad
        Jbabdi, Matthew Webster, Jonathan R Polimeni, and others. The minimal
        preprocessing pipelines for the human connectome project. Neuroimage,
        80:105–124, 2013.
    .. [3] Bruce Fischl, Martin I Sereno, Roger BH Tootell, and Anders M Dale. High-resolution
        intersubject averaging and a coordinate system for the cortical surface.
        Human brain mapping, 8(4):272–284, 1999.
    .. [4] Ross D Markello, Justine Y Hansen, Zhen-Qi Liu, Vincent Bazinet,
        Golia Shafiei, Laura E Suárez, Nadia Blostein, Jakob Seidlitz,
        Sylvain Baillet, Theodore D Satterthwaite, and others. Neuromaps:
        structural and functional interpretation of brain maps. Nature Methods,
        19(11):1472–1479, 2022.
    """
    versions = ["fsaverage", "fsaverage6", "fsaverage5", "fsaverage4"]
    if version not in versions:
        raise ValueError(
            f"The version of fsaverage requested {version} does not "
            f"exist. Must be one of {versions}"
        )

    dataset_name = "tpl-fsaverage_curated"
    _get_reference_info("tpl-fsaverage_curated", verbose=verbose)

    keys = ["white", "pial", "inflated", "sphere", "medial", "sulc", "vaavg"]
    keys_suffix = {
        "white": "white.surf",
        "pial": "pial.surf",
        "inflated": "inflated.surf",
        "sphere": "sphere.surf",
        "medial": "desc-nomedialwall_dparc.label",
        "sulc": "desc-sulc_midthickness.shape",
        "vaavg": "desc-vaavg_midthickness.shape",
    }
    version_density = {
        "fsaverage": "164k",
        "fsaverage6": "41k",
        "fsaverage5": "10k",
        "fsaverage4": "3k",
    }
    density = version_density[version]

    fetched = fetch_file(
        dataset_name, keys=version, force=force, data_dir=data_dir, verbose=verbose
    )

    # deal with default neuromaps directory structure in the archive
    if not fetched.exists():
        import shutil

        shutil.move(fetched.parent / "atlases/fsaverage", fetched)
        shutil.rmtree(fetched.parent / "atlases")

    data = {
        k: SURFACE(
            fetched / f"tpl-fsaverage_den-{density}_hemi-L_{keys_suffix[k]}.gii",
            fetched / f"tpl-fsaverage_den-{density}_hemi-R_{keys_suffix[k]}.gii",
        )
        for k in keys
    }

    return Bunch(**data)

```

--------------------------------

### Download Conte69 template (Python)

Source: https://netneurotools.readthedocs.io/en/latest/api

Downloads files for the Van Essen et al., 2012 Conte69 template. Supports specifying force, data directory, and verbosity.

```python
fetch_conte69(force, data_dir, verbose)
  Download files for Van Essen et al., 2012 Conte69 template.
```

--------------------------------

### Permutation Test Pearsonr Example 1

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.stats.permtest_pearsonr

Demonstrates the basic usage of permtest_pearsonr with two arrays, setting a random seed for reproducibility. It shows the correlation and p-value for moderately correlated data.

```python
import numpy as np
from netneurotools import stats

np.random.seed(12345678)  # set random seed for reproducible results
x, y = stats.make_correlated_xy(corr=0.1, size=100)
print(stats.permtest_pearsonr(x, y))
```

--------------------------------

### Example: Network Pearson Correlation with Shortest Path Length Weights

Source: https://netneurotools.readthedocs.io/en/latest/generated/netneurotools.metrics.network_pearsonr

Demonstrates how to calculate network Pearson correlation using weights derived from shortest path lengths between nodes.

```python
import numpy as np
from netneurotools.metrics import network_pearsonr
from netneurotools.datasets import fetch_surf_fsaverage
from netneurotools.utils import distance_wei_floyd

# Assume D is a distance matrix (e.g., from fetch_surf_fsaverage)
# For demonstration, let's create dummy data
# D, _ = fetch_surf_fsaverage(mesh='fsaverage', return_surf=True)
# D = D['pial_left'] # Example distance matrix

# Dummy data for demonstration
N = 100
D = np.random.rand(N, N) # Dummy distance matrix
np.fill_diagonal(D, 0)

spl, _ = distance_wei_floyd(D) # Calculate shortest path lengths
spl_wei = 1 / np.exp(spl) # Convert to weights

# Dummy annotation vectors
annot1 = np.random.rand(N)
annot2 = np.random.rand(N)

netcorr = network_pearsonr(annot1, annot2, spl_wei)
print(f"Network Pearson Correlation (SPL weights): {netcorr}")
```
Tokens:
Raw