Visualization

Every figure of a run. hetero.sim imports nine of these lazily; the remaining ones are still part of the module’s public surface.

hetero.viz.polish(fig, axs, lw=1, tight=True)

hetero.viz.simpleaxis(ax, lw=2)

hetero.viz.get_cax(ax, width=3., dist=.05)

Returns a human-friendly colorbar axis from a given ax, to be used with matplotlib’s colorbar method.

hetero.viz.aggregate_scores(res_path, sims=[], sim_pattern='')

hetero.viz.append_subplot(fig, axes, position='bottom')

hetero.viz.plot_input_char(corrs, psds, deltas, freqs, dts, res_path, mark_peaks=True, name='input_character')

The point of this plot is to compare the first peak of autocorrelation and the first frequency in the power density. So either all the frequency and time quantities must be integers or in physical units.

Here I assume they are in physical units (that’s how I set the labels).

hetero.viz.plot_activity(t, v, activation, res_path, name, **kwargs)

hetero.viz.plot_weights(t, w, res_path, name, **kwargs)

hetero.viz.plot_score_map(res_path)

hetero.viz.plot_score_score(res_path, rlz_id=None)

Plots, for each mean-timescale level n (first digit of the net_id), the trial-averaged score of every task of a heterogeneous network (net_id with a non-zero second digit h) against the score of the exact same task for the homogeneous network of the same group (the net_id with h=0). Each h level is colored by hetero_colors.

The score of the homogeneous network is on the x-axis and the score of the heterogeneous network on the y-axis, so points above the identity line indicate that heterogeneity improves performance.

The trn_/tst_ score files of every network are read, and the per-task score is obtained by averaging across all trials. When rlz_id is given, only the score files of that realization (e.g. LI-rlz000) are read. One figure per score file (state LI-rlz000 and readout such as possig1) is saved into res_path, named score_score_{trn|tst}{scr_name}.png to keep the rlzXXX naming convention alive.

Parameters:

• res_path (str) – The path to a simulation directory, containing one subdirectory per network ({n}{h} with h=0 the homogeneous network) with the trn_/tst_ score files.

• rlz_id (int, optional) – The realization to plot. By default all realizations found are plotted.

hetero.viz.plot_angle_vs_score(res_path, rlz_id=None)

Plots, for every task, the minimal angle between the network state and the task against the task’s benchmark score, for all networks.

Networks are split into groups by their mean-timescale level n (the first digit of the net_id, i.e. the mean tau, per TAU_MAP); each group gets one panel. Within each panel the different heterogeneity levels h (the second digit of the net_id) are plotted with different colors, using the same color scheme as the other plots of this module (hetero_colors, labeled by HETERO_LABEL_MAP). The top and bottom rows use the train and test splits respectively, so every task appears once per split.

The task angle is read from the angle_{state}.csv files produced by hetero.sim.Simulation.compute_minimal_angles() and the score from the paired trn_/tst_{state}-{readout}.csv files, averaged across trials. When rlz_id is given, only that realization (e.g. 0 -> LI-rlz000) is plotted.

One figure per score file is saved into res_path, each coloring the scatter with a different scheme: by the heterogeneity/color level h (the default, angle_vs_score{scr_name}.png), and by the task properties dim, delta and deg (angle_vs_score{scr_name}- {dim,delta,deg}.png). The task-property figures reuse the colormaps of plot_udf_vs_complexity(): dim and deg are categorical (Set2 and Accent), delta is continuous (coolwarm).

Parameters:

• res_path (str) – The path to a simulation directory, containing one subdirectory per network ({n}{h}) with the angle and trn_/tst_ score files of each benchmarked realization.

• rlz_id (int, optional) – The realization to plot. By default all realizations found are plotted.

hetero.viz.plot_overlap_cdf(res_path, rlz_id=None)

Plots the cumulative distribution of the minimal angles of every task, grouped into panels by the mean-timescale level n (the first digit of the net_id, i.e. the mean tau, per TAU_MAP). Within each panel the different heterogeneity levels h (the second digit of the net_id) are drawn in the module’s hetero_colors, labeled by HETERO_LABEL_MAP.

The angles are read from the angle_{state}.csv files produced by hetero.sim.Simulation.compute_minimal_angles(). Each panel pools the train and test angles of every subtask of every network sharing that n, held separately for each h, and draws the fraction of tasks whose angle lies below each value (an empirical CDF): a curve shifting toward zero means the tasks are, on average, better aligned with the network state. One figure per angle file (state token) is saved into res_path as overlap_cdf{state}.png. When rlz_id is given, only that realization (e.g. 0 -> -rlz000) is plotted.

Parameters:

• res_path (str) – The path to a simulation directory, containing one subdirectory per network ({n}{h}) with the angle files of each benchmarked realization.

• rlz_id (int, optional) – The realization to plot. By default all realizations found are plotted.

hetero.viz.plot_svals_erank(res_path, rlz_id=None)

Plots the singular-value spectrum of every network’s activity and the cumulative distribution of its effective rank, grouped into panels by the mean-timescale level n (the first digit of the net_id, i.e. the mean tau, per TAU_MAP), with the heterogeneity levels h (the second digit of the net_id) drawn in the module’s hetero_colors and labeled by HETERO_LABEL_MAP – the exact grouping of plot_overlap_cdf().

The spectra and effective ranks are read from the svals_{state}.csv and erank_{state}.csv files produced by hetero.sim.Simulation.compute_minimal_angles(). Two figures per state token are saved into res_path:

• svals{tok}.png – the mean (solid line) +/- one standard deviation (shaded band) of the singular-value spectra pooled over the train and test slices and over every network sharing that n and h. Each spectrum is normalized by its own largest singular value so the curves isolate the shape of the spectrum (how many comparable modes the activity has) rather than the overall activity scale; x runs over the modes in descending order, rescaled to the unit fraction [0, 1]. A curve hugging 1 over a long stretch means the activity is effectively low-dimensional (few dominant modes); a fast decay to 0 means the variance is spread over many modes.

• erank{tok}.png – the empirical CDF of the effective rank (the Roy & Vetterli spectral-entropy rank, see hetero.sim.Simulation._effective_rank()) pooled over the train and test slices and over every network of each (n, h) pair, i.e. the fraction of states whose effective rank lies below each value.

When rlz_id is given, only that realization (e.g. 0 -> -rlz000) is plotted.

Parameters:

• res_path (str) – The path to a simulation directory, containing one subdirectory per network ({n}{h}) with the svals/erank files of each benchmarked realization.

• rlz_id (int, optional) – The realization to plot. By default all realizations found are plotted.

hetero.viz.plot_svds(net_ids, res_path, N, activation='possig', conv_params=None, suffix='')

hetero.viz.plot_connectivity(data_path, rlz_id=None)

hetero.viz.plot_tau_dist(data_path, bins=50, rlz_id=None)

Plots the distribution of the neuronal time constants of every network ID of the realization into the result path. Histograms are step type with raw counts (density=False) on a log tau axis, colored by the heterogeneity (h) level – the second digit of the net_id – following hetero_colors and labeled by HETERO_LABEL_MAP. For the homogeneous (h=0) networks, whose time constants are all equal, a vertical line at the constant value is drawn instead of a histogram. The n levels (first digit, i.e. the mean E[tau] level per TAU_MAP) are differentiated by line width. A seaborn-style legend built from dummy handles reports the h colors and the n widths. The x/y ranges are fixed across realizations: x in [5e-3, 50] and y in [N/1000, N/2] with N the number of neurons per network.

hetero.viz.plot_states_map(net_ids, data_path, activation='possig', fe=0.8)

hetero.viz.plot_complexity_map(data_path)

Creates and saves a complexity map per input dimension without recomputing the tasks.

Rather than re-synthesizing the target timeseries and recomputing information-theoretic measures for every subtask, this function simply loads the previously calculated complexities from {data_path}/complexities.csv, the file that hetero.sim.Simulation.compute_complexity() (via utils.compute_complexity) has already saved during initialization.

Parameters:

• task (hetero.tasks.TemporalTask) – The task object (its name is used in the output file name).

• data_path (str) – Path to the simulation directory containing complexities.csv.

Notes

• complexities.csv contains one row per flattened subtask with columns dim, delta, deg, complexity.

• A single figure is written to {task.name}_complexity.svg with one row per input dimension: each row is a pcolormesh of the complexity with delta on the x-axis and degree on the y-axis.

• Tasks that do not vary along both a degree axis and a delta axis (e.g. Taylor or Nostradamus alone) have no 2D map to draw and are skipped with a warning.

hetero.viz.plot_udf_vs_complexity(data_path)

Plots the input-based baseline scores against the precomputed complexities, per subtask.

Loads {data_path}/complexities.csv and {data_path}/udf.csv, merges them on (dim, delta, deg) and draws, for each subtask, the R2 scores of the linear input-to-target decoder (udf) against the associated complexity (1 - |cos(u, y)|). A single figure is saved as {task.name}_udf_vs_complexity.svg.

The layout is a grid of subtask properties (rows) vs. data splits (columns): each row colors the points by a different property of the subtask (input dimension, delta shift \Delta, degree), the two columns are the train and test scores, and a colorbar at the right of every row identifies the coloring.

The udf scores (higher = easier) quantify how much of each target subtask is linearly reachable from the input alone; the complexity (higher = harder) is the static cosine-based difficulty. The dashed complexity = 1 - score line is drawn on every panel as the reference of perfect agreement.

For a linear (OLS) input-to-target decoder and a zero-mean, univariate input, the two measures are translatable: score = |cos|^2 = (1 - complexity)^2. This mapping is drawn as a dash-dotted curve on every panel.

Parameters:

• task (hetero.tasks.TemporalTask) – The task object (its name is used in the output file name).

• data_path (str) – Path to the simulation directory containing complexities.csv and udf.csv.

hetero.viz.plot_difficulty_map_mi(task, u, data_path)

Information-theoretic difficulty map, kept alongside plot_complexity_map() for comparison.

This version recomputes the target timeseries of every subtask and measures the difficulty of the input-to-target mapping with mutual information (utils.compute_complexity_mi): for each subtask and input dimension the possibility, realizability and feasibility of the mapping are evaluated, and a single figure is saved as {task.name}_feasibility.svg with one row per input dimension and three columns (Possibility, Realizability, Feasibility).

Parameters:

• task (hetero.tasks.TemporalTask) – The task object. Works with both un-flattened subtasks ([delta, deg] or [deg]) and flattened ones ([dim, delta, deg]).

• u (ndarray of shape (n_dims, n_timesteps)) – The (compound) input timeseries.

• data_path (str) – Path to the simulation directory in which the figures are saved.

• note:: (..) – Contrary to plot_complexity_map(), this function does not reuse the precomputed complexities.csv and is therefore the expensive reference against which the cheap (loaded) map is compared.

hetero.viz.plot_uvx(u, v, x, res_path, final_chunk=1000, state_name=None, rlz_id=None)

Plots the input u, voltage v, and activation x arrays in a 3x2 grid: the last final_chunk timesteps in the first column (heatmap when the array has more than one feature, a line otherwise) and the flattened distribution of each array as a histogram in the second column. Arrays must be shaped (n_features, timesteps).