viz

Module: viz

Tools for visualization of time-series data.

Depends on matplotlib. Some functions depend also on networkx

Functions

nitime.viz.draw_arrows(G, pos, edgelist=None, ax=None, edge_color='k', alpha=1.0, width=1)

Draw arrows on a set of edges

nitime.viz.draw_graph(G, labels=None, node_colors=None, node_shapes=None, node_scale=1.0, edge_style='solid', edge_cmap=None, colorbar=False, vrange=None, layout=None, title=None, font_family='sans-serif', font_size=9, stretch_factor=1.0, edge_alpha=True, fig_size=None)

Draw a weighted graph with options to visualize link weights.

The resulting diagram uses the rank of each node as its size, and the weight of each link (after discarding thresholded values, see below) as the link opacity.

It maps edge weight to color as well as line opacity and thickness, allowing the color part to be hardcoded over a value range (to permit valid cross-figure comparisons for different graphs, so the same color corresponds to the same link weight even if each graph has a different range of weights). The nodes sizes are proportional to their degree, computed as the sum of the weights of all their links. The layout defaults to circular, but any nx layout function can be passed in, as well as a statically precomputed layout.

Parameters:

G : weighted graph

The values must be of the form (v1,v2), with all v2 in [0,1]. v1 are used for colors, v2 for thickness/opacity.

labels : list or dict, optional.

An indexable object that maps nodes to strings. If not given, the string form of each node is used as a label. If False, no labels are drawn.

node_colors : list or dict, optional.

An indexable object that maps nodes to valid matplotlib color specs. See matplotlib’s plot() function for details.

node_shapes : list or dict, optional.

An indexable object that maps nodes to valid matplotlib shape specs. See matplotlib’s scatter() function for details. If not given, circles are used.

node_scale : float, optional

A scale factor to globally stretch or shrink all nodes symbols by.

edge_style : string, optional

Line style for the edges, defaults to ‘solid’.

edge_cmap : matplotlib colormap, optional.

A callable that returns valid color specs, like matplotlib colormaps. If not given, edges are colored black.

colorbar : bool

If true, automatically add a colorbar showing the mapping of graph weight values to colors.

vrange : pair of floats

If given, this indicates the total range of values that the weights can in principle occupy, and is used to set the lower/upper range of the colormap. This allows you to set the range of multiple different figures to the same values, even if each individual graph has range variations, so that visual color comparisons across figures are valid.

layout : function or layout dict, optional

A NetworkX-like layout function or the result of a precomputed layout for the given graph. NetworkX produces layouts as dicts keyed by nodes and with (x,y) pairs of coordinates as values, any function that produces this kind of output is acceptable. Defaults to nx.circular_layout.

title : string, optional.

If given, title to put on the main plot.

font_family : string, optional.

Font family used for the node labels and title.

font_size : int, optional.

Font size used for the node labels and title.

stretch_factor : float, optional

A global scaling factor to make the graph larger (or smaller if <1). This can be used to separate the nodes if they start overlapping.

edge_alpha: bool, optional :

Whether to weight the transparency of each edge by a factor equivalent to its relative weight

fig_size: list of height by width, the size of the figure (in :

inches). Defaults to [6,6] :
Returns:

fig :

The matplotlib figure object with the plot.
nitime.viz.draw_matrix(mat, th1=None, th2=None, clim=None, cmap=None)

Draw a matrix, optionally thresholding it.

nitime.viz.draw_networkx_nodes(G, pos, nodelist=None, node_size=300, node_color='r', node_shape='o', alpha=1.0, cmap=None, vmin=None, vmax=None, ax=None, linewidths=None, label=None, **kwds)

Draw the nodes of the graph G.

This draws only the nodes of the graph G.

Parameters:

G : graph

A networkx graph

pos : dictionary

A dictionary with nodes as keys and positions as values. Positions should be sequences of length 2.

ax : Matplotlib Axes object, optional

Draw the graph in the specified Matplotlib axes.

nodelist : list, optional

Draw only specified nodes (default G.nodes())

node_size : scalar or array

Size of nodes (default=300). If an array is specified it must be the same length as nodelist.

node_color : color string, or array of floats

Node color. Can be a single color format string (default=’r’), or a sequence of colors with the same length as nodelist. If numeric values are specified they will be mapped to colors using the cmap and vmin,vmax parameters. See matplotlib.scatter for more details.

node_shape : string

The shape of the node. Specification is as matplotlib.scatter marker, one of ‘so^>v<dph8’ (default=’o’).

alpha : float

The node transparency (default=1.0)

cmap : Matplotlib colormap

Colormap for mapping intensities of nodes (default=None)

vmin,vmax : floats

Minimum and maximum for node colormap scaling (default=None)

linewidths : [None | scalar | sequence]

Line width of symbol border (default =1.0)

label : [None| string]

Label for legend
Returns:

matplotlib.collections.PathCollection :

PathCollection of the nodes.

See also

draw, draw_networkx, draw_networkx_edges, draw_networkx_labels, draw_networkx_edge_labels

Examples

>>> G=nx.dodecahedral_graph()
>>> nodes=nx.draw_networkx_nodes(G,pos=nx.spring_layout(G))

Also see the NetworkX drawing examples at http://networkx.github.io/documentation/latest/gallery.html

nitime.viz.drawgraph_channels(in_m, channel_names=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, node_shapes=None, node_colors=None, title=None, layout=None, threshold=None)

Draw a graph based on the matrix specified in in_m. Wrapper to draw_graph.

Parameters:

in_m: nxn array with values of relationships between two sets of channels :

or channels :

channel_names (optional): list of strings with the labels to be applied to :

the channels in the input. Defaults to ‘0’,‘1’,‘2’, etc. :

cmap (optional): a matplotlib colormap to be used for displaying the values :

of the connections on the graph :

node_shapes: defaults to circle :

node_colors: defaults to white, :

title: str :

Sets a title for the figure.

layout, defaults to nx.circular_layout :

Returns :

——- :

fig: a figure object :

Notes

The layout of the graph is done using functions from networkx (http://networkx.lanl.gov), which is a dependency of this function

nitime.viz.drawmatrix_channels(in_m, channel_names=None, fig=None, x_tick_rot=0, size=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, colorbar=True, color_anchor=None, title=None)

Creates a lower-triangle of the matrix of an nxn set of values. This is the typical format to show a symmetrical bivariate quantity (such as correlation or coherence between two different ROIs).

Parameters:

in_m: nxn array with values of relationships between two sets of rois or :

channels :

channel_names (optional): list of strings with the labels to be applied to :

the channels in the input. Defaults to ‘0’,‘1’,‘2’, etc. :

fig (optional): a matplotlib figure :

cmap (optional): a matplotlib colormap to be used for displaying the values :

of the connections on the graph :

title (optional): string to title the figure (can be like ‘$alpha$’) :

color_anchor (optional): determine the mapping from values to colormap :

if None, min and max of colormap correspond to min and max of in_m if 0, min and max of colormap correspond to max of abs(in_m) if (a,b), min and max of colormap correspond to (a,b)
Returns:

fig: a figure object :
nitime.viz.lab2node(labels, labels_dict)
nitime.viz.matshow_tseries(time_series, fig=None, axis=0, xtick_n=5, time_unit=None, xlabel=None, ylabel=None)

Creates an image of the time-series, ordered according to the first dimension of the time-series object

Parameters:

time_series: a nitime time-series object :

fig: a figure handle, opens a new figure if None :

axis: an axis number (if there are several in the figure to be opened), :

defaults to 0.

xtick_n: int, optional, sets the number of ticks to be placed on the x axis :
nitime.viz.mkgraph(cmat, threshold=0.0, threshold2=None)

Make a weighted graph object out of an adjacency matrix.

The values in the original matrix cmat can be thresholded out. If only one threshold is given, all values below that are omitted when creating edges. If two thresholds are given, then values in the th2-th1 range are omitted. This allows for the easy creation of weighted graphs with positive and negative values where a range of weights around 0 is omitted.

Parameters:

cmat : 2-d square array

Adjacency matrix.

threshold : float

First threshold.

threshold2 : float

Second threshold.
Returns:

G : a NetworkX weighted graph object, to which a dictionary called

G.metadata is appended. This dict contains the original adjacency matrix :

cmat, the two thresholds, and the weights :
nitime.viz.plot_corr_diff(tseries1, tseries2, fig=None, ts_names=['1', '2'])

Show the differences in Fischer-transformed snr correlations for two time-series

Parameters:

tseries1, tseries2 : nitime TimeSeries objects

These are the time-series to compare, with each of them having the dims: (n_channels, n_reps, time), where n_channels1 = n_channels2

lb,ub: float :

Lower and upper bounds on the frequency range over which to calculate the information rate (default to [0,Nyquist]).

fig: matplotlib figure object :

If you want to do this on already existing figure. Otherwise, a new figure object will be generated.

ts_names: list of str :

Labels for the two inputs, to be used in plotting (defaults to [‘1’,‘2’])

bandwidth, adaptive, low_bias: See :func:`SNRAnalyzer` for details :
Returns:

fig: a matplotlib figure object :
nitime.viz.plot_snr(tseries, lb=0, ub=None, fig=None)

Show the coherence, snr and information of an SNRAnalyzer

Parameters:

tseries: nitime TimeSeries object :

Multi-trial data in response to one stimulus/protocol with the dims: (n_channels,n_repetitions,time)

lb,ub: float :

Lower and upper bounds on the frequency range over which to calculate (default to [0,Nyquist]).
Returns:

A tuple containing: :

fig: a matplotlib figure object :

This figure displays: 1. Coherence 2. SNR 3. Information
nitime.viz.plot_snr_diff(tseries1, tseries2, lb=0, ub=None, fig=None, ts_names=['1', '2'], bandwidth=None, adaptive=False, low_bias=True)

Show distributions of differences between two time-series in the amount of snr (freq band by freq band) and information. For example, for comparing two stimulus conditions

Parameters:

tseries1, tseries2 : nitime TimeSeries objects

These are the time-series to compare, with each of them having the dims: (n_channels, n_reps, time), where n_channels1 = n_channels2

lb,ub: float :

Lower and upper bounds on the frequency range over which to calculate the information rate (default to [0,Nyquist]).

fig: matplotlib figure object :

If you want to do this on already existing figure. Otherwise, a new figure object will be generated.

ts_names: list of str :

Labels for the two inputs, to be used in plotting (defaults to [‘1’,‘2’])

bandwidth, adaptive, low_bias: See :func:`nta.SNRAnalyzer` for details :
Returns:

A tuple containing: :

fig: a matplotlib figure object :

This figure displays: 1. The histogram of the information differences between the two time-series 2. The frequency-dependent SNR for the two time-series

info1, info2: float arrays :

The frequency-dependent information rates (in bits/sec)

s_n_r1, s_n_r2: float arrays :

The frequncy-dependent signal-to-noise ratios
nitime.viz.plot_spectral_estimate(f, sdf, sdf_ests, limits=None, elabels=())

Plot an estimate of a spectral transform against the ground truth.

Utility file used in building the documentation

nitime.viz.plot_tseries(time_series, fig=None, axis=0, xticks=None, xunits=None, yticks=None, yunits=None, xlabel=None, ylabel=None, yerror=None, error_alpha=0.1, time_unit=None, **kwargs)

plot a timeseries object

nitime.viz.plot_xcorr(xc, ij, fig=None, line_labels=None, xticks=None, yticks=None, xlabel=None, ylabel=None)

Visualize the cross-correlation function

nitime.viz.rgb_to_dict(value, cmap)
nitime.viz.subcolormap(xmin, xmax, cmap)

Returns the part of cmap between xmin, xmax, scaled to 0,1.

nitime.viz.winspect(win, f, name=None)

Inspect a window by showing it and its spectrum

Utility file used in building the documentation