brainlife/neuropythy repository overview

⁠Description

This repository provides a containerized implementation of retinotopic mapping workflows based on the Neuropythy software library. The container is built directly from the original source code available at the Neuropythy repository and is intended to facilitate reproducible execution in high-performance and cloud-based environments.

Neuropythy is a Python-based framework for analyzing neuroimaging data, with particular emphasis on cortical surface representations, FreeSurfer integration, and anatomically informed models of retinotopic organization in the human visual cortex. The methods implemented in this container include anatomically-defined retinotopy and related interpolation procedures derived from published work.

This repository does not reimplement Neuropythy; rather, it packages the original software within a container environment to ensure portability and reproducibility.

⁠Maintainers

Gabriele Amorosino ([email protected]⁠)

Yang Zhang ([email protected]⁠)

⁠Citation

If you use this container, please cite the original work:

Benson, N. C., Butt, O. H., Brainard, D. H., & Aguirre, G. K. (2014). Correction of distortion in flattened cortical representations allows prediction of V1–V3 organization from anatomy. PLoS Computational Biology.

Benson, N. C., & Winawer, J. (2018). Bayesian analysis of retinotopic maps. eLife.

⁠Source

Original repository: https://github.com/noahbenson/neuropythy⁠

⁠Apply Retinotopic Prediction using Benson method with the Latest Version (0.12.16)

singularity exec -e docker://brainlife/neuropythy:0.12.16  \
        python -m neuropythy benson14_retinotopy \
        --verbose --template ${template}  \
        --vol-format=nii.gz \
        "/my/freesurfer/subject"

⁠Apply a Neuropythy Atlas with the Latest Version (0.12.16)

Use the latest image to apply an atlas such as benson14 or wang15 to a FreeSurfer subject.

singularity exec \
  --env FS_LICENSE="/my/freesurfer/license.txt" \
  -e docker://brainlife/neuropythy:0.12.16 \
  python -m neuropythy atlas \
    -a <atlas> \
    --output-format=mgz \
    --surface-export \
    --volume-export \
    --volume-path "/my/output/volumes" \
    --output-path "/my/output/surfaces" \
    --verbose \
    -c \
    "/my/freesurfer/subject"

Where <atlas> can be, for example:

• benson14
• wang15
• glasser16
• rosenke18

⁠Previous Version (0.12.6) Has a NumPy Compatibility Bug

Version 0.12.6 may fail with newer NumPy releases because deprecated aliases such as np.int are no longer available. A runtime workaround is to restore these aliases before importing and running Neuropythy.

singularity exec -e docker://brainlife/neuropythy:0.12.6 \
python - <<'PY'
import sys
import numpy as np

for name, val in {
    "int": int,
    "float": float,
    "bool": bool,
    "object": object,
}.items():
    if not hasattr(np, name):
        setattr(np, name, val)

from neuropythy.commands.benson14_retinotopy import main

argv = [
    "--verbose",
    "/my/freesurfer/subject",
    "--surf-format=nii.gz",
    "--template=Benson14",
    "--vol-format=nii.gz",
]

sys.exit(main(argv))
PY

⁠Notes

• 0.12.16 is the recommended version for atlas application.
• 0.12.6 should only be used if you specifically need that older image.
• The FS_LICENSE environment variable must point to a valid FreeSurfer license file.
• The final positional argument should be the path to the FreeSurfer subject directory.