Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Surface plots #2477

Merged
merged 58 commits into from
Jun 30, 2020
Merged
Show file tree
Hide file tree
Changes from 46 commits
Commits
Show all changes
58 commits
Select commit Hold shift + click to select a range
0201b22
Add plot_surf_montage
dangom Jan 20, 2019
78bec87
Fix float division by zero in Python 2 in plot_surf_montage
dangom Jan 21, 2019
ea0dd3f
Rename plot_surf_montage to plot_img_on_surf
dangom Jan 21, 2019
55fb7a7
Move _check_mesh from html_surface into check_mesh in surface.
dangom Jan 21, 2019
4d87ae9
Plot_img_on_surf now uses check_mesh
dangom Jan 21, 2019
d334693
Improve handling of keyword args in plot_img_on_surf
dangom Jan 21, 2019
867a01e
Factor out plot_img_on_surf's colorbar code into a helper function
dangom Jan 21, 2019
983745b
Improve docs related to surf_mesh
dangom Jan 21, 2019
f31bd3c
Move cmap to a keyword argument in plot_img_on_surf
dangom Jan 21, 2019
f32e614
Fix plot_img_on_surf surf_mesh default. From None to fsaverage5
dangom Jan 21, 2019
1ce4aad
Add more tests.
dangom Jan 21, 2019
e4e7a9e
Update examples/01_plotting/plot_img_on_surf.py
jeromedockes Jan 22, 2019
1388051
Update examples/01_plotting/plot_img_on_surf.py
jeromedockes Jan 22, 2019
31a7991
Move plot_img_on_surf example to plot_3d_map_to_surface_projection
dangom Jan 23, 2019
648fa94
Remove unused import in surf_plotting.py
dangom Jan 23, 2019
7bdd9c1
Make 'cold_hot' the default cmap in plot_img_on_surf
dangom Jan 23, 2019
2dc314f
Use safeguard check_niimg_3d to plot_img_on_surf
dangom Jan 23, 2019
35e30c3
Merged latest master into @dangom's/surf_montage.
ZviBaratz May 21, 2020
66c2a47
Fixed surface module's tests.
ZviBaratz May 21, 2020
14fac1a
Fixed the test failure. It was caused by a line I missed in the merge.
ZviBaratz May 21, 2020
e2dd639
Merged upstream and added examples artifacts to gitignore.
ZviBaratz May 29, 2020
1a50359
Added plot_img_on_surf() to reference.rst and made tiny styling fixes…
ZviBaratz May 29, 2020
fc0aaa1
Added a What's New entry for plot_img_on_surf().
ZviBaratz May 29, 2020
63129da
Added some missing tests for plot_img_on_surf().
ZviBaratz May 29, 2020
05d2510
Changed relative imports to absolute imports in surf_plotting.py.
ZviBaratz May 29, 2020
a1895fc
Merge branch 'master' into surface_plots
ZviBaratz Jun 1, 2020
a62f0fc
Merged master and edited plot_img_on_surf() docstring to fix RST inde…
ZviBaratz Jun 1, 2020
5eaad19
Another round with Sphinx.
ZviBaratz Jun 1, 2020
d4cb770
Updated test surface fetch method and resolved linting issues.
ZviBaratz Jun 1, 2020
74c016e
Fixed to conform with the default flake8 max-line-length configuration.
ZviBaratz Jun 1, 2020
d4c1a88
Sphinx U+1F3F3
ZviBaratz Jun 1, 2020
c0c4f58
Added .vscode to gitignore and organized a bit.
ZviBaratz Jun 2, 2020
56de47c
Changed test_plot_img_on_surf_output_file() in attempt to solve build…
ZviBaratz Jun 2, 2020
6db1144
Merge branch 'master' into surface_plots
ZviBaratz Jun 6, 2020
e3e993b
Fixed horizontal squeeze by adding an aspect_ratio parameter to plot_…
ZviBaratz Jun 7, 2020
7f55423
Fixed bad :func: directive in plot_img_on_surf() example.
ZviBaratz Jun 7, 2020
962e13f
Update examples/01_plotting/plot_3d_map_to_surface_projection.py
ZviBaratz Jun 9, 2020
ebb7e6f
Removed length check from `_check_hemisphere()`
ZviBaratz Jun 9, 2020
e95c882
Proposed Orientation Enum for surface plotting configuration.
ZviBaratz Jun 9, 2020
c150fdf
Updated example to comply with changing the display_mode parameter to…
ZviBaratz Jun 9, 2020
d218a82
Reverted Enum creation and updated plot_img_on_surf's hemispheres par…
ZviBaratz Jun 9, 2020
bb118d7
Reverted changes to gitignore.
ZviBaratz Jun 10, 2020
942fa0f
Removed obj domain referencing in docstrings.
ZviBaratz Jun 10, 2020
3034054
Removed f-strings to maintain python 3.5 compatibility.
ZviBaratz Jun 10, 2020
1c617f2
Fixed missed f-strings.
ZviBaratz Jun 10, 2020
f6ccb9f
Fixed error message strings in _check_views() and _check_hemispheres().
ZviBaratz Jun 10, 2020
03a2e78
Reverted image module docstring fixes.
ZviBaratz Jun 25, 2020
9ede345
Made check_mesh() private.
ZviBaratz Jun 25, 2020
b357672
Reverted img_plotting module docstring fixes.
ZviBaratz Jun 25, 2020
da9d243
Removed list conversion in _check_hemispehres() and _check_views() an…
ZviBaratz Jun 25, 2020
44646f4
Made 'fsaverage5' plot_img_on_surf()'s default surf_mesh value and up…
ZviBaratz Jun 25, 2020
ac23a61
Added a try-except block to remove plot_img_on_surf()'s output file a…
ZviBaratz Jun 25, 2020
3c84edc
Changed test_plot_img_on_surf_output_file() to use pytest's tmp_path …
ZviBaratz Jun 25, 2020
5f5d3e8
Fixed plot_img_on_surf()'s aspect ratio parameter to default to 1.4 a…
ZviBaratz Jun 25, 2020
9f8fbc6
Removed symmetric_cbar parameter from plot_img_on_surf().
ZviBaratz Jun 25, 2020
52794d6
Removed symmetric_cbar parameter from _colorbar_from_array().
ZviBaratz Jun 25, 2020
d7daa31
Reverted changes to the image.py module.
ZviBaratz Jun 30, 2020
6feb6ba
Merged changes from master.
ZviBaratz Jun 30, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,6 @@ tags
venv/

doc/themes/nilearn/static/jquery.js
.vscode/
examples/results/
examples/**/*.pdf
1 change: 1 addition & 0 deletions doc/modules/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,7 @@ the :ref:`user guide <user_guide>` for more information and usage examples.
plot_surf
plot_surf_roi
plot_surf_stat_map
plot_img_on_surf
view_surf
view_img_on_surf
view_connectome
Expand Down
9 changes: 6 additions & 3 deletions doc/whats_new.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ NEW
:func:`nilearn.plotting.plot_carpet` generates a "carpet plot" (also known
as a "Power plot" or a "grayplot"), for visualizing global patterns in
4D functional data over time.
- New plotting function
:func:`nilearn.plotting.plot_img_on_surf` generates multiple views of
:func:`nilearn.plotting.plot_surf_stat_map` in a single figure.


Fixes
Expand Down Expand Up @@ -340,7 +343,7 @@ NEW
when using the `mask_strategy="template"` option for brains in MNI space.
- New brain development fMRI dataset fetcher
:func:`nilearn.datasets.fetch_development_fmri` can be used to download
movie-watching data in children and adults; a light-weight dataset
movie-watching data in children and adults; a light-weight dataset
implemented for teaching and usage in the examples.
- New example in `examples/05_advanced/plot_age_group_prediction_cross_val.py`
to compare methods for classifying subjects into age groups based on
Expand All @@ -363,8 +366,8 @@ Changes

- All the connectivity examples are changed from ADHD to brain development
fmri dataset.
- Examples plot_decoding_tutorial, plot_haxby_decoder,
ZviBaratz marked this conversation as resolved.
Show resolved Hide resolved
plot_haxby_different_estimators, plot_haxby_full_analysis, plot_oasis_vbm now
- Examples plot_decoding_tutorial, plot_haxby_decoder,
plot_haxby_different_estimators, plot_haxby_full_analysis, plot_oasis_vbm now
use :class:`nilearn.decoding.Decoder` and :class:`nilearn.decoding.DecoderRegressor`
instead of sklearn SVC and SVR.

Expand Down
15 changes: 14 additions & 1 deletion examples/01_plotting/plot_3d_map_to_surface_projection.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,22 @@
threshold=1., bg_map=big_fsaverage.sulc_right)


##############################################################################
# Plot multiple views of the 3D volume on a surface
# -------------------------------------------------
#
# *plot_img_on_surf* takes a statistical map and projects it onto a surface.
# It supports multiple choices of orientations, and can plot either one or both
# hemispheres. If no *surf_mesh* is given, *plot_img_on_surf* projects the
# images onto `FreeSurfer <https://surfer.nmr.mgh.harvard.edu/>`_\'s
# fsaverage5.

plotting.plot_img_on_surf(stat_img,
views=['lateral', 'medial'],
hemispheres=['left', 'right'],
colorbar=True)
plotting.show()


##############################################################################
# 3D visualization in a web browser
# ---------------------------------
Expand Down
60 changes: 30 additions & 30 deletions nilearn/image/image.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,15 @@ def high_variance_confounds(imgs, n_confounds=5, percentile=2.,
If provided, confounds are extracted from voxels inside the mask.
See http://nilearn.github.io/manipulating_images/input_output.html.

n_confounds : :obj:`int`
n_confounds : int
ZviBaratz marked this conversation as resolved.
Show resolved Hide resolved
Number of confounds to return.

percentile : :obj:`float`
percentile : float
Highest-variance signals percentile to keep before computing the
singular value decomposition, 0. <= `percentile` <= 100.
`mask_img.sum() * percentile / 100` must be greater than `n_confounds`.

detrend : :obj:`bool`
detrend : bool
If True, detrend signals before processing.

Returns
Expand Down Expand Up @@ -175,10 +175,10 @@ def _smooth_array(arr, affine, fwhm=None, ensure_finite=True, copy=True):
are also accepted (only these coefficients are used).
If `fwhm='fast'`, the affine is not used and can be None.

fwhm : scalar, :class:`numpy.ndarray`/:obj:`tuple`/:obj:`list`, 'fast' or None
fwhm : scalar, :class:`numpy.ndarray`/tuple/list, 'fast' or None
Smoothing strength, as a full-width at half maximum, in millimeters.
If a nonzero scalar is given, width is identical in all 3 directions.
A :class:`numpy.ndarray`, :obj:`tuple`, or :obj:`list` must have 3 elements,
A :class:`numpy.ndarray`, tuple, or list must have 3 elements,
giving the FWHM along each axis.
If any of the elements is zero or None, smoothing is not performed
along that axis.
Expand All @@ -188,11 +188,11 @@ def _smooth_array(arr, affine, fwhm=None, ensure_finite=True, copy=True):
If fwhm is None, no filtering is performed (useful when just removal
of non-finite values is needed).

ensure_finite : :obj:`bool`
ensure_finite : bool
If True, replace every non-finite values (like NaNs) by zero before
filtering.

copy : :obj:`bool`
copy : bool
If True, input array is not modified. True by default: the filtering
is not performed in-place.

Expand Down Expand Up @@ -313,15 +313,15 @@ def _crop_img_to(img, slices, copy=True):
Defines the range of the crop.
E.g. [slice(20, 200), slice(40, 150), slice(0, 100)] defines a cube.

copy : :obj:`bool`
copy : bool
Specifies whether cropped data is to be copied or not (default is `True`).

Returns
-------
Niimg-like object
Cropped version of the input image.

offset: :obj:`list` (optional)
offset: list (optional)
List of tuples representing the number of voxels removed (before, after)
the cropped volumes, i.e.:
*[(x1_pre, x1_post), (x2_pre, x2_post), ..., (xN_pre, xN_post)]*
Expand Down Expand Up @@ -364,24 +364,24 @@ def crop_img(img, rtol=1e-8, copy=True, pad=True, return_offset=False):
http://nilearn.github.io/manipulating_images/input_output.html
for a detailed description of the valid input types).

rtol : :obj:`float`
rtol : float
relative tolerance (with respect to maximal absolute value of the
image), under which values are considered negligeable and thus
croppable.

copy : :obj:`bool`
copy : bool
Specifies whether cropped data is copied or not (default is `True`).

pad : :obj:`bool`
pad : bool
Toggles adding 1-voxel of 0s around the border (default is `True`).

return_offset : :obj:`bool`
return_offset : bool
Specifies whether to return a tuple of the removed padding
(default is `False`).

Returns
-------
Niimg-like object or :obj:`tuple`
Niimg-like object or tuple
Cropped version of the input image and, if `return_offset=True`, a tuple
of tuples representing the number of voxels removed (before, after) the
cropped volumes, i.e.:
Expand Down Expand Up @@ -424,7 +424,7 @@ def _pad_array(array, pad_sizes):
----------
array : :class:`numpy.ndarray`
Array to pad.
pad_sizes : :obj:`list`
pad_sizes : list
Padding quantity specified as
*[x1minpad, x1maxpad, x2minpad,x2maxpad, x3minpad, ...]*.

Expand Down Expand Up @@ -517,16 +517,16 @@ def mean_img(imgs, target_affine=None, target_shape=None,
If specified, the image is resampled corresponding to this new affine.
target_affine can be a 3x3 or a 4x4 matrix.

target_shape : :obj:`tuple` or :obj:`list`, optional
target_shape : tuple or list, optional
If specified, the image will be resized to match this new shape.
len(target_shape) must be equal to 3.
A target_affine has to be specified jointly with target_shape.

verbose : :obj:`int`, optional
verbose : int, optional
Controls the amount of verbosity: higher numbers give more messages
(0 means no messages).

n_jobs : :obj:`int`, optional
n_jobs : int, optional
The number of CPUs to use to do the computation (-1 means
'all CPUs').

Expand Down Expand Up @@ -706,7 +706,7 @@ def new_img_like(ref_niimg, data, affine=None, copy_header=False):
affine : 4x4 :class:`numpy.ndarray`, optional
Transformation matrix.

copy_header : :obj:`bool`, optional
copy_header : bool, optional
Indicated if the header of the reference image should be used to
create the new image.

Expand Down Expand Up @@ -784,7 +784,7 @@ def threshold_img(img, threshold, mask_img=None, copy=True):
img : a 3D/4D Niimg-like object
Image contains of statistical or atlas maps which should be thresholded.

threshold : :obj:`float` or :obj:`str`
threshold : float or str
If float, we threshold the image based on image intensities meaning
voxels which have intensities greater than this value will be kept.
The given value should be within the range of minimum and
Expand All @@ -798,7 +798,7 @@ def threshold_img(img, threshold, mask_img=None, copy=True):
Mask image applied to mask the input data.
If None, no masking will be applied.

copy : :obj:`bool`
copy : bool
If True, input array is not modified. True by default: the filtering
is not performed in-place.

Expand Down Expand Up @@ -848,7 +848,7 @@ def math_img(formula, **imgs):

Parameters
----------
formula : :obj:`str`
formula : str
The mathematical formula to apply to image internal data. It can use
numpy imported as 'np'.
imgs : images (:class:`~nibabel.nifti1.Nifti1Image` or file names)
Expand Down Expand Up @@ -960,13 +960,13 @@ def clean_img(imgs, sessions=None, detrend=True, standardize=True,
Add a session level to the cleaning process. Each session will be
cleaned independently. Must be a 1D array of n_samples elements.

detrend : :obj:`bool`
detrend : bool
If detrending should be applied on timeseries (before confound removal).

standardize : :obj:`bool`
standardize : bool
If True, returned signals are set to unit variance.

confounds : :class:`numpy.ndarray`, :obj:`str` or :obj:`list` of
confounds : :class:`numpy.ndarray`, str or list of
Confounds timeseries. Shape must be
(instant number, confound number), or just (instant number,)
The number of time instants in signals and confounds must be
Expand All @@ -976,17 +976,17 @@ def clean_img(imgs, sessions=None, detrend=True, standardize=True,
If a list is provided, all confounds are removed from the input
signal, as if all were in the same array.

low_pass : :obj:`float`
low_pass : float
Low cutoff frequencies, in Hertz.

high_pass : :obj:`float`
high_pass : float
High cutoff frequencies, in Hertz.

t_r : :obj:`float`, optional
t_r : float, optional
Repetition time, in second (sampling period). Set to None if not
specified. Mandatory if used together with `low_pass` or `high_pass`.

ensure_finite : :obj:`bool`, optional
ensure_finite : bool, optional
If True, the non-finite values (NaNs and infs) found in the images
will be replaced by zeros.

Expand Down Expand Up @@ -1072,7 +1072,7 @@ def load_img(img, wildcards=True, dtype=None):
`TypeError` otherwise.
See http://nilearn.github.io/manipulating_images/input_output.html.

wildcards : :obj:`bool`, optional
wildcards : bool, optional
Use `img` as a regular expression to get a list of matching input
filenames.
If multiple files match, the returned list is sorted using an ascending
Expand Down
7 changes: 4 additions & 3 deletions nilearn/plotting/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ def _set_mpl_backend():
from .html_surface import view_surf, view_img_on_surf
from .html_stat_map import view_img
from .html_connectome import view_connectome, view_markers
from .surf_plotting import plot_surf, plot_surf_stat_map, plot_surf_roi
from .surf_plotting import (plot_surf, plot_surf_stat_map, plot_surf_roi,
plot_img_on_surf)

__all__ = ['cm', 'plot_img', 'plot_anat', 'plot_epi',
'plot_roi', 'plot_stat_map', 'plot_glass_brain',
Expand All @@ -58,5 +59,5 @@ def _set_mpl_backend():
'show', 'plot_matrix', 'view_surf', 'view_img_on_surf',
'view_img', 'view_connectome', 'view_markers',
'find_parcellation_cut_coords', 'find_probabilistic_atlas_cut_coords',
'plot_surf', 'plot_surf_stat_map', 'plot_surf_roi', 'plot_carpet'
]
'plot_surf', 'plot_surf_stat_map', 'plot_surf_roi', 'plot_carpet',
'plot_img_on_surf']
11 changes: 6 additions & 5 deletions nilearn/plotting/html_surface.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,12 @@
import matplotlib as mpl
from matplotlib import cm as mpl_cm

from .._utils.niimg_conversions import check_niimg_3d
from .. import datasets, surface
from nilearn._utils.niimg_conversions import check_niimg_3d
from nilearn import surface
from nilearn import datasets
from nilearn.reporting import HTMLDocument
from . import cm
from .js_plotting_utils import (
from nilearn.plotting import cm
from nilearn.plotting.js_plotting_utils import (
colorscale, mesh_to_plotly, get_html_template, add_js_lib,
to_color_strings)

Expand Down Expand Up @@ -91,7 +92,7 @@ def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,

"""
info = {}
mesh = _check_mesh(mesh)
mesh = surface.check_mesh(mesh)
ZviBaratz marked this conversation as resolved.
Show resolved Hide resolved
surface_maps = {
h: surface.vol_to_surf(volume_img, mesh['pial_{}'.format(h)],
**vol_to_surf_kwargs)
Expand Down
6 changes: 3 additions & 3 deletions nilearn/plotting/img_plotting.py
Original file line number Diff line number Diff line change
Expand Up @@ -1479,9 +1479,9 @@ def plot_carpet(img, mask_img=None, detrend=True, output_file=None,
Limit plotted voxels to those inside the provided mask (default is
None). If not specified a new mask will be derived from data.
See http://nilearn.github.io/manipulating_images/input_output.html.
detrend : :obj:`bool`, optional
ZviBaratz marked this conversation as resolved.
Show resolved Hide resolved
detrend : bool, optional
Detrend and z-score the data prior to plotting (default is `True`).
output_file : :obj:`str` or None, optional
output_file : str or None, optional
The name of an image file to which to export the plot (default is
None). Valid extensions are .png, .pdf, and .svg.
If `output_file` is not None, the plot is saved to a file, and the
Expand All @@ -1492,7 +1492,7 @@ def plot_carpet(img, mask_img=None, detrend=True, output_file=None,
axes : matplotlib axes or None, optional
The axes used to display the plot (default is None).
If None, the complete figure is used.
title : :obj:`str` or None, optional
title : str or None, optional
The title displayed on the figure (default is None).

Returns
Expand Down