htfa.animate_network

htfa.animate_network(nodes, connectivity, out, *, fps=10, duration=None, n_frames=None, interpolation='linear', spin=None, sizes=None, widths=None, subject='global', mesh='ch2', snap=True, mask=None, scale_by_mass=False, fade_by_mass=False, node_mode='auto', lobe_level=0.05, lobe_negative_color='teal', captions=None, frames_dir=None, jpeg_quality=None, **style)

Render a (T, K, K) connectivity series as an mp4 or GIF.

By default the movie has one frame per connectivity window, and the camera, mesh, nodes and threshold stay fixed. duration (or n_frames) sets the number of frames instead, interpolating between windows, and spin turns the brain.

Parameters:

nodes, sizes, widths, subject, mesh, snap, mask, scale_by_mass, fade_by_mass

As in plot_network (snap is on by default).

node_mode, lobe_level, lobe_negative_color

As in plot_network; the same component geometry and repeated edges are used in every frame.

**style

As in plot_network.

connectivityarray of shape (T, K, K), or (K, K) with duration

One edge matrix per window. A single (K, K) matrix needs duration or n_frames and gives fixed edges (for a spin).

outpath

.mp4 (H.264 via imageio-ffmpeg) or .gif. An mp4 is encoded while frames render, holding one frame in memory at a time. A GIF needs all frames for its shared palette, about 4.8 MB per 1600 x 1000 frame (see write_animation).

fpsfloat

Frame rate of the movie, in frames per second (default 10).

durationfloat, optional

Length of the movie in seconds: it gets round(duration * fps) frames whatever T is, so the windows play in slow motion or fast forward. Movie frame i of n shows window time t = i * (T - 1) / (n - 1) (all of the windows, first to last).

n_framesint, optional

The number of movie frames, instead of duration.

interpolation{“linear”, “nearest”}

How a fractional t is drawn: "linear" (default) mixes the two neighbouring windows, (1 - f) * E[floor(t)] + f * E[floor(t) + 1] with f = t - floor(t), so edges fade in and out smoothly as their weights cross threshold; "nearest" shows the nearest window (halves round up).

spin(x, y, z) turns, optional

Number of full turns of the brain about the MNI x, y and z axes over the whole movie, through the center of the mesh’s bounding box (of the nodes without a mesh). Fractions are allowed. Movie frame k of n turns the brain by spin * k / n turns, about x first, then y, then z (right-hand rule: (0, 0, 0.25) brings the front of the brain towards the camera in the left lateral view). The turn is made by orbiting the camera (with its light) around the brain, with the parallel projection kept and the zoom fixed at the largest one that keeps the brain and nodes inside every frame. With a whole number of turns the movie loops seamlessly: frame n would be frame 0 again. None (default) keeps the fixed camera of view; any spin, even (0, 0, 0), uses the centered, fitted zoom.

captionssequence of T str, or callable, optional

Text shown in a white band above each frame (not over the brain). A sequence gives the caption of each window (a movie frame takes that of the nearest window); a callable is called with each frame’s window time t (a float) and returns its caption.

frames_dirpath, optional

Also save each frame there as 1.png, 2.png, … (.jpg with jpeg_quality).

jpeg_qualityint, optional

JPEG-compress each frame at this quality before it goes into the movie. Lower quality values increase compression artifacts.

Returns:

pathlib.Path

out.

Examples

Suppose centers contains K node locations in MNI anatomical reference coordinates, E contains 30 corresponding K-by-K connectivity matrices, and C is a single static connectivity matrix. The following examples illustrate animation settings independently of the experiment that supplied those connections.

A 6 s animation of the 30 windows at 15 frames per second (90 frames, interpolated across the window sequence), turning once about the vertical axis:

>>> animate_network(centers, E, "net.mp4", fps=15, duration=6,
...                 spin=(0, 0, 1))

A 4 s spin of one static network:

>>> animate_network(centers, C, "spin.gif", fps=12, duration=4,
...                 spin=(0, 0, 1), size=(480, 300))