ndslib

This software is companion to the book “Neuroimaging and Data Science” by Ariel Rokem and Tal Yarkoni. An online version of the book can be found at https://neuroimaging-data-science.org.

These are the functions available through the software:

ndslib.data.load_data(dataset, fname=None)

Load data for use in examples

Parameters:

datasetstr

The name of a dataset. Can be one of:

"bold_numpy" : Read a BOLD time-series as a numpy array.

"bold_volume" : Read a single volume of a BOLD time-series
                a numpy array

"afq" : Read AFQ data

"age_groups_fa" : Read AFQ data and return dataframe divided
                  by age-groups

"abide2_saggitals": Read ABIDE2 mid-saggitals as numpy arrays.

fnamestr, optional.

If provided, data will be cached to this local path and retrieved from there on future calls with the same value.

ndslib.data.download_bids_dataset()

Makes a minimal BIDS dataset with one fMRI subject from OpenNeuro ds001233

ndslib.viz.imshow_with_annot(im, vmax=40)

Like imshow, but with added annotation of the array values

Parameters:

imnumpy array object

ndslib.viz.plot_diffeomorphic_map(mapping, ax, delta=15, direct_grid_shape=None, direct_grid2world=-1, inverse_grid_shape=None, inverse_grid2world=-1, show_figure=True, **fig_kwargs)

Draw the effect of warping a regular lattice by a diffeomorphic map. Draws a diffeomorphic map by showing the effect of the deformation on a regular grid. The resulting figure contains two images: the direct transformation is plotted to the left, and the inverse transformation is plotted to the right.

Parameters:

mappingDiffeomorphicMap object

the diffeomorphic map to be drawn

deltaint, optional

the size (in pixels) of the squares of the regular lattice to be used to plot the warping effects. Each square will be delta x delta pixels. By default, the size will be 10 pixels.

fnamestring, optional

the name of the file the figure will be written to. If None (default), the figure will not be saved to disk.

direct_grid_shapetuple, shape (2,), optional

the shape of the grid image after being deformed by the direct transformation. By default, the shape of the deformed grid is the same as the grid of the displacement field, which is by default equal to the shape of the fixed image. In other words, the resulting deformed grid (deformed by the direct transformation) will normally have the same shape as the fixed image.

direct_grid2worldarray, shape (3, 3), optional

the affine transformation mapping the direct grid’s coordinates to physical space. By default, this transformation will correspond to the image-to-world transformation corresponding to the default direct_grid_shape (in general, if users specify a direct_grid_shape, they should also specify direct_grid2world).

inverse_grid_shapetuple, shape (2,), optional

the shape of the grid image after being deformed by the inverse transformation. By default, the shape of the deformed grid under the inverse transform is the same as the image used as “moving” when the diffeomorphic map was generated by a registration algorithm (so it corresponds to the effect of warping the static image towards the moving).

inverse_grid2worldarray, shape (3, 3), optional

the affine transformation mapping inverse grid’s coordinates to physical space. By default, this transformation will correspond to the image-to-world transformation corresponding to the default inverse_grid_shape (in general, if users specify an inverse_grid_shape, they should also specify inverse_grid2world).

show_figurebool, optional

if True (default), the deformed grids will be plotted using matplotlib, else the grids are just returned

fig_kwargs: extra parameters for saving figure, e.g. `dpi=300`.

Returns:

warped_forwardarray

Image with the grid showing the effect of transforming the moving image to the static image. The shape will be direct_grid_shape if specified, otherwise the shape of the static image.

warped_backwardarray

Image with the grid showing the effect of transforming the static image to the moving image. Shape will be inverse_grid_shape if specified, otherwise the shape of the moving image.

Notes

The default value for the affine transformation is “-1” to handle the case in which the user provides “None” as input meaning “identity”. If we used None as default, we wouldn’t know if the user specifically wants to use the identity (specifically passing None) or if it was left unspecified, meaning to use the appropriate default matrix.

ndslib.viz.plot_coef_path(estimator, X, y, alpha, **kwargs)

Plot the coefficient path for a sklearn estimator

Parameters:

estimatorsklearn estimator

For example Lasso()

Xndarray (n, m)

Feature matrix

yndarray (n,)

Target matrix

Returns:

axMPL Axes object

ndslib.viz.plot_train_test(x_range, train_scores, test_scores, label, hlines=None)

Plot train/test \(R^2\)

Parameters:

x_rangesequence

The range of x values used (e.g., number of features, number of samples)

train_scoressequence

The train r2_score corresponding to different x values

test_scoressequence

The test r2_score corresponding to different x values

labelstr

Used in the legend labels.

hlinesdict

A dictionary where keys are labels and values are y values for hlines.

Returns:

axMPL Axes object.

ndslib.viz.plot_learning_curves(estimators, X_sets, y, train_sizes, labels=None, errors=True, **kwargs)

Generate multi-panel plot displaying learning curves for multiple predictor sets and/or estimators.

Parameters:

estimatorslist,

A scikit-learn Estimator or list of estimators. If a list is provided, it must have the same number of elements as X_sets.

X_setslist,

An NDArray or similar object, or list. If a list is passed, it must have the same number of elements as estimators.

yndarray

A 1-D numpy array (or pandas Series) representing the outcome variable to predict.

train_sizeslist

List of ints providing the sample sizes at which to evaluate the estimator.

labelslist, optional.

List of labels for the panels. Must have the same number of elements as X_sets.

errorsbool, optional.

If True, plots error bars representing 1 StDev. Default: True.

kwargsdict, optional

Optional keyword arguments passed on to sklearn’s learning_curve utility.

ndslib.viz.plot_graphviz_tree(tree, feature_names)

Helper function that takes a tree as input, calls sklearn’s export_graphviz function to generate an image of the tree using graphviz, and then plots the result in-line.

Parameters:

tree: sklearn tree object

feature_namessequence of strings

ndslib.image.gaussian_kernel(x=20, sigma=4)

Construct a 2D Gaussian kernel for image processing

Parameters:

xint, optional

The number of pixels on a side for the filter. Default : 20

sigmafloat, optional

The standard deviation parameter for the Gaussian. Default : 4

Returns:

gaussndarray

Contains the values of the 2D Gaussian normalized to sum to 1.