---
jupytext:
formats: ipynb,md:myst
text_representation:
extension: .md
format_name: myst
format_version: 0.13
jupytext_version: 1.11.5
kernelspec:
display_name: Python 3 (ipykernel)
language: python
name: python3
---
```{code-cell} ipython3
:tags: [remove-cell]
from ndslib.config import jupyter_startup
jupyter_startup()
```
(ndslib)=
# `ndslib` function reference
The `ndslib` software library implements functions that we use in the book to
download datasets, and to encapsulate some computations. We provide descriptions
of the functions for each module below. Additional documentation can be found in
the ndslib [library website](https://neuroimaging-data-science.github.io/ndslib/).
```{eval-rst}
`ndslib.data.load_data(dataset, fname=None)`
Loads data for use in examples.
Parameters:
**dataset** : str
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 as a numpy array
"afq" : Read diffusion MRI data in tabular format
"age_groups_fa" : Read AFQ data and return dataframe divided by age-groups
"abide2_saggitals": Read ABIDE2 mid-saggitals as numpy arrays.
**fname** : str, 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 dataset "ds001233".
`ndslib.viz.imshow_with_annot(im, vmax=40)`
Like imshow, but with added annotation of the array values.
Parameters:
**im** : numpy array
`ndslib.viz.plot_diffeomorphic_map(mapping, ax, delta=15, direct_grid_shape=None, direct_grid2world=- 1, inverse_grid_shape=None, inverse_grid2world=- 1)`
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:
**mapping** : DiffeomorphicMap
the diffeomorphic map to be drawn
**delta** : int, 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.
**fname** : string, 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_shape** : tuple, 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_grid2world** : array, 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_shape** : tuple, 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_grid2world** : array, 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).
Returns:
**warped_forward** : array
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_backward** : array
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:
**estimator** : sklearn estimator
For example "`Lasso()`"
**X** : ndarray (n, m)
Feature matrix
**y** : ndarray (n,)
Target matrix
Returns:
**ax** : Matplotlib `Axes` object
`ndslib.viz.plot_train_test(x_range, train_scores, test_scores, label, hlines=None)`
Plot train/test $R^2$
Parameters:
**x_range** : sequence
The range of x values used (e.g., number of features, number
of samples)
**train_scores** : sequence
The train r2_score corresponding to different x values
**test_scores** : sequence
The test r2_score corresponding to different x values
**label** : str
Used in the legend labels.
**hlines** : dict
A dictionary where keys are labels and values are y values
for hlines.
Returns:
**ax** : Matplotlib `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:
**estimators** : list,
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_sets** : list,
An NDArray or similar object, or list. If a list is passed,
it must have the same number of elements as estimators.
**y** : ndarray
A 1-D numpy array (or pandas Series) representing the outcome
variable to predict.
**train_sizes** : list
List of ints providing the sample sizes at which to evaluate
the estimator.
**labels** : list, optional.
List of labels for the panels. Must have the same number of
elements as X_sets.
**errors** : bool, optional.
If True, plots error bars representing 1 StDev. Default:
True.
**kwargs** : dict, optional
Optional keyword arguments passed on to sklearn's
*learning_curve* utility.
`ndslib.viz.plot_graphviz_tree(tree, feature_names)`
Takes a tree as input, calls Scikit-learn'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_names** : sequence of strings
`ndslib.image.gaussian_kernel(x=20, sigma=4)`
Construct a 2D Gaussian kernel for image processing
Parameters:
**x** : int, optional
The number of pixels on a side for the filter. Default : 20
**sigma** : float, optional
The standard deviation parameter for the Gaussian. Default :
4
Returns:
**gauss** : ndarray
Contains the values of the 2D Gaussian normalized to sum to 1.
```