brainsmash.workbench package

Submodules

brainsmash.workbench.geo module

Routines for constructing distance matrices from neuroimaging files.

brainsmash.workbench.geo.cortex(surface, outfile, euclid=False, dlabel=None, medial=None, use_wb=True, unassigned_value=0, verbose=True, n_jobs=None)

Calculates surface distances for surface mesh and saves to outfile.

Parameters

  • surface (str or os.PathLike) – Path to surface file on which to calculate distance

  • outfile (str or os.PathLike) – Path to which generated distance matrix should be saved

  • euclid (bool, optional, default False) – Whether to compute Euclidean distance instead of surface distance

  • dlabel (str or os.PathLike, optional, default None) – Path to file with parcel labels for provided surf. If provided, calculate and save parcel-parcel distances instead of vertex distances.

  • medial (str or os.PathLike, optional, default None) – Path to file containing labels for vertices corresponding to medial wall. If provided and use_wb=False, will disallow calculation of surface distance along the medial wall.

  • use_wb (bool, optional, default True) – Whether to use calls to wb_command -surface-geodesic-distance for computation of the surface distance matrix; this will involve significant disk I/O. If False, all computations will be done in memory using the scipy.sparse.csgraph.dijkstra function.

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

  • verbose (bool, optional, default True) – Whether to print status updates while distances are calculated.

  • n_jobs (int, default None) – The number of parallel jobs to run for distance calculation. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors.

Returns

distance – Path to generated outfile

Return type

str

Notes

The surface distance matrix computed with use_wb=False will have slightly lower values than when use_wb=True due to known estimation errors. These will be fixed at a later date. By default, use_wb=True for backwards- compatibility but this will be changed in a future update.

:raises ValueError : inconsistent # of vertices in label, mask, and/or surface file:

brainsmash.workbench.geo.subcortex(fout, image_file=None, dlabel=None, unassigned_value=0, verbose=True)

Compute inter-voxel Euclidean distance matrix.

Parameters

  • fout (str or os.Pathlike) – Path to output text file

  • image_file (str or os.Pathlike or None, default None) – Path to a CIFTI-2 format neuroimaging file (eg .dscalar.nii). MNI coordinates for each subcortical voxel are read from this file’s metadata. If None, uses dlabel file defined in brainsmash.config.py.

  • dlabel (str or os.PathLike, optional, default None) – Path to file with parcel labels for provided surf. If provided, calculate and save parcel-parcel distances instead of vertex distances.

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

  • verbose (bool, optional, default True) – Whether to print status updates while distances are calculated.

Returns

filename – Path to output text file containing pairwise Euclidean distances

Return type

str

Notes

Voxel indices are used as a proxy for physical distance, since the two are related by a simple linear scaling. Note that this assumes voxels are cubic, i.e., that the scaling is equivalent along the x, y, and z dimension.

:raises ValueError : image_file header does not contain volume information: :raises IndexError : Inconsistent number of elements in image_file and dlabel:

brainsmash.workbench.geo.parcellate(infile, dlabel_file, outfile, delimiter=' ', unassigned_value=0)

Parcellate a dense distance matrix.

Parameters

  • infile (filename) – Path to delimiter-separated distance matrix file

  • dlabel_file (filename) – Path to parcellation file (.dlabel.nii)

  • outfile (filename) – Path to output text file (to be created)

  • delimiter (str, default ' ') – Delimiter between elements in infile

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

Returns

filename – Path to output parcellated distance matrix file

Return type

str

Notes

For two parcels A and B, the inter-parcel distance is defined as the mean distance between area i in parcel A and area j in parcel B, for all i,j.

Inputs infile and dlabel_file should include the same anatomical structures, e.g. the left cortical hemisphere, and should have the same number of elements. If you need to isolate one anatomical structure from dlabel_file, see the following Workbench function: https://www.humanconnectome.org/software/workbench-command/-cifti-separate

:raises ValueError : infile and dlabel_file have inconsistent sizes:

brainsmash.workbench.geo.volume(coord_file, outdir, chunk_size=1000)

Generate distance-matrix-related memory-mapped files for volumetric data.

Parameters

  • coord_file (str or os.PathLike) – Path to text file in which rows correspond to voxels of interest, and three columns correspond to voxels’ coordinates

  • outdir (str or os.PathLike) – Path to the directory where outputs will be saved

  • chunk_size (int, default 1000) – The number of voxels to process per chunk. For N voxels, this will impose a memory burden of N*`chunk_size` per iteration (in contrast to a memory burden of N*N for a single iteration, in the absence of chunking).

Returns

Keys are ‘D’ and ‘index’; values are absolute paths to the corresponding files on disk. These files are used as inputs to brainsmash.mapgen.sampled.Sampled.

Return type

dict

:raises IOError : outdir doesn’t exist: :raises ValueError : coord_file does not contain three columns:

Notes

This function computes 3D Euclidean distance between all pairs of voxels whose 3D coordinates are provided in coord_file. The distance matrix is not saved in its raw, symmetric form, but rather as a pair of memory-mapped arrays which are needed to create an instance of the brainsmash.mapgen.sampled.Sampled class. See brainsmash.mapgen.memmap.txt2memmap for more details. Note that the input file should only contain brain voxels — i.e., voxels in your brain map of interest. Each row of coord_file, which indicates the coordinates of a voxel, should therefore correspond to one brain map value.

brainsmash.workbench.io module

Functions for Connectome Workbench-style neuroimaging file I/O.

brainsmash.workbench.io.image2txt(image_file, outfile, maskfile=None, delimiter=' ')

Export neuroimaging data to txt file.

Parameters

  • image_file (filename) – Path to input neuroimaging file

  • outfile (filename) – Path to output text file

  • maskfile (filename or None, default None) – Path to neuroimaging file containing a binary map where non-zero values indicate masked brain regions.

  • delimiter (str, default ' ') – Character used to delimit elements in image_file

Notes

More generally, this can be done via wb_command -cifti-convert -to-text <image_file> <outfile>.

brainsmash.workbench.io.check_surface(surface)

Check and load MNI coordinates from a surface file.

Parameters

surface (filename) – Path to GIFTI-format surface file (.surf.gii)

Returns

MNI coordinates. columns 0,1,2 correspond to X,Y,Z coord, respectively

Return type

(N,3) np.ndarray

:raises ValueError : surface does not contain 3 columns (assumed to be X, Y, Z):

brainsmash.workbench.io.check_image_file(image)

Check a neuroimaging file and return internal scalar neuroimaging data.

Parameters

image (filename) – Path to neuroimaging file or txt file

Returns

Scalar brain map values

Return type

(N,) np.ndarray

:raises FileNotFoundError : image does not exist: :raises IOError : filetype not recognized: :raises ValueError : image contains more than one neuroimaging map:

Module contents

brainsmash.workbench.cortex(surface, outfile, euclid=False, dlabel=None, medial=None, use_wb=True, unassigned_value=0, verbose=True, n_jobs=None)

Calculates surface distances for surface mesh and saves to outfile.

Parameters

  • surface (str or os.PathLike) – Path to surface file on which to calculate distance

  • outfile (str or os.PathLike) – Path to which generated distance matrix should be saved

  • euclid (bool, optional, default False) – Whether to compute Euclidean distance instead of surface distance

  • dlabel (str or os.PathLike, optional, default None) – Path to file with parcel labels for provided surf. If provided, calculate and save parcel-parcel distances instead of vertex distances.

  • medial (str or os.PathLike, optional, default None) – Path to file containing labels for vertices corresponding to medial wall. If provided and use_wb=False, will disallow calculation of surface distance along the medial wall.

  • use_wb (bool, optional, default True) – Whether to use calls to wb_command -surface-geodesic-distance for computation of the surface distance matrix; this will involve significant disk I/O. If False, all computations will be done in memory using the scipy.sparse.csgraph.dijkstra function.

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

  • verbose (bool, optional, default True) – Whether to print status updates while distances are calculated.

  • n_jobs (int, default None) – The number of parallel jobs to run for distance calculation. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors.

Returns

distance – Path to generated outfile

Return type

str

Notes

The surface distance matrix computed with use_wb=False will have slightly lower values than when use_wb=True due to known estimation errors. These will be fixed at a later date. By default, use_wb=True for backwards- compatibility but this will be changed in a future update.

:raises ValueError : inconsistent # of vertices in label, mask, and/or surface file:

brainsmash.workbench.subcortex(fout, image_file=None, dlabel=None, unassigned_value=0, verbose=True)

Compute inter-voxel Euclidean distance matrix.

Parameters

  • fout (str or os.Pathlike) – Path to output text file

  • image_file (str or os.Pathlike or None, default None) – Path to a CIFTI-2 format neuroimaging file (eg .dscalar.nii). MNI coordinates for each subcortical voxel are read from this file’s metadata. If None, uses dlabel file defined in brainsmash.config.py.

  • dlabel (str or os.PathLike, optional, default None) – Path to file with parcel labels for provided surf. If provided, calculate and save parcel-parcel distances instead of vertex distances.

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

  • verbose (bool, optional, default True) – Whether to print status updates while distances are calculated.

Returns

filename – Path to output text file containing pairwise Euclidean distances

Return type

str

Notes

Voxel indices are used as a proxy for physical distance, since the two are related by a simple linear scaling. Note that this assumes voxels are cubic, i.e., that the scaling is equivalent along the x, y, and z dimension.

:raises ValueError : image_file header does not contain volume information: :raises IndexError : Inconsistent number of elements in image_file and dlabel:

brainsmash.workbench.parcellate(infile, dlabel_file, outfile, delimiter=' ', unassigned_value=0)

Parcellate a dense distance matrix.

Parameters

  • infile (filename) – Path to delimiter-separated distance matrix file

  • dlabel_file (filename) – Path to parcellation file (.dlabel.nii)

  • outfile (filename) – Path to output text file (to be created)

  • delimiter (str, default ' ') – Delimiter between elements in infile

  • unassigned_value (int, default 0) – Label value which indicates that a vertex/voxel is not assigned to any parcel. This label is excluded from the output. 0 is the default value used by Connectome Workbench, e.g. for -cifti-parcellate.

Returns

filename – Path to output parcellated distance matrix file

Return type

str

Notes

For two parcels A and B, the inter-parcel distance is defined as the mean distance between area i in parcel A and area j in parcel B, for all i,j.

Inputs infile and dlabel_file should include the same anatomical structures, e.g. the left cortical hemisphere, and should have the same number of elements. If you need to isolate one anatomical structure from dlabel_file, see the following Workbench function: https://www.humanconnectome.org/software/workbench-command/-cifti-separate

:raises ValueError : infile and dlabel_file have inconsistent sizes:

brainsmash.workbench.volume(coord_file, outdir, chunk_size=1000)

Generate distance-matrix-related memory-mapped files for volumetric data.

Parameters

  • coord_file (str or os.PathLike) – Path to text file in which rows correspond to voxels of interest, and three columns correspond to voxels’ coordinates

  • outdir (str or os.PathLike) – Path to the directory where outputs will be saved

  • chunk_size (int, default 1000) – The number of voxels to process per chunk. For N voxels, this will impose a memory burden of N*`chunk_size` per iteration (in contrast to a memory burden of N*N for a single iteration, in the absence of chunking).

Returns

Keys are ‘D’ and ‘index’; values are absolute paths to the corresponding files on disk. These files are used as inputs to brainsmash.mapgen.sampled.Sampled.

Return type

dict

:raises IOError : outdir doesn’t exist: :raises ValueError : coord_file does not contain three columns:

Notes

This function computes 3D Euclidean distance between all pairs of voxels whose 3D coordinates are provided in coord_file. The distance matrix is not saved in its raw, symmetric form, but rather as a pair of memory-mapped arrays which are needed to create an instance of the brainsmash.mapgen.sampled.Sampled class. See brainsmash.mapgen.memmap.txt2memmap for more details. Note that the input file should only contain brain voxels — i.e., voxels in your brain map of interest. Each row of coord_file, which indicates the coordinates of a voxel, should therefore correspond to one brain map value.

brainsmash.workbench.image2txt(image_file, outfile, maskfile=None, delimiter=' ')

Export neuroimaging data to txt file.

Parameters

  • image_file (filename) – Path to input neuroimaging file

  • outfile (filename) – Path to output text file

  • maskfile (filename or None, default None) – Path to neuroimaging file containing a binary map where non-zero values indicate masked brain regions.

  • delimiter (str, default ' ') – Character used to delimit elements in image_file

Notes

More generally, this can be done via wb_command -cifti-convert -to-text <image_file> <outfile>.

brainsmash.workbench.load(filename)

Load data contained in a CIFTI2-/GIFTI-format neuroimaging file.

Parameters

filename (filename) – Path to neuroimaging file

Returns

Brain map data stored in filename

Return type

(N,) np.ndarray

:raises TypeError : filename has unknown filetype: