Skip to content

Figures

Generated from figure_manifest.yaml by tools/gen_docs.py. Edit the manifest, not this page.

Every figure in the paper, the notebook that draws it, and what that notebook reads. To reproduce one, install the package, unpack the cached results into data/, and run the notebook from top to bottom; the figure appears inline. Set SAVE_FIGURES = True at the top of the notebook to write it to figures/ as well.

Figure What it shows Notebook
1 Classical ring-attractor model and mouse head-direction tuning curves data_and_generative_model.ipynb
2 Ring attractor built from the data: PCA convergence, connectivity, closed-loop integration data_driven_attractor.ipynb
3 Circular symmetry in the distribution of head-direction responses data_and_generative_model.ipynb
4 Tuning curves and connectivity from the generative model data_and_generative_model.ipynb
5 Model vs. data: profiles, peak statistics, symmetry and information data_and_generative_model.ipynb
6 Circular geometry, disordered embedding, and the spectrum of the optimal weights spectra.ipynb
7 Dynamical mean-field theory of the disordered ring attractor dmft.ipynb
8 Grid-cell simulations from the disordered attractor grid_sims.ipynb
S1 Low-rank connectivity: kappa trajectories weight_matrix_analyses.ipynb
S2 Mixture loadings: the attractor is the whole torus weight_matrix_analyses.ipynb
S3 Left and right singular vectors of the connectivity weight_matrix_analyses.ipynb
S4 Real vs. surrogate connectivity matrices and their spectra weight_matrix_analyses.ipynb
S5 Origin of the Mexican-hat connectivity profile mexican_hat_and_asymmetry.ipynb
S6 Asymmetric connectivity models mexican_hat_and_asymmetry.ipynb
S7 Double normalization of tuning curves data_driven_reconstruction.ipynb
S8 PCA convergence of the data-driven ring attractor data_driven_reconstruction.ipynb
S9 Reconstruction error vs. regularization strength data_driven_reconstruction.ipynb
S10 Noise-driven dynamics: circulant vs. disordered weight_matrix_analyses.ipynb
S11 Searching for spurious fixed points in finite-N attractors spurious_fixed_points.ipynb
S12 Attractor dynamics at finite N spurious_fixed_points.ipynb
S13 Normalized covariance matrices and their eigenvectors data_and_generative_model.ipynb
S14 Eigenvalue and singular-value spectra of the data and of subsamples data_driven_reconstruction.ipynb
S15 Eigenvalue spectrum of the grid-cell connectivity grid_sims.ipynb
S16 Attractor dynamics in a reservoir RNN reservoir_rnn.ipynb

Main text

Figure 1

Classical ring-attractor model and mouse head-direction tuning curves.

  • Image: figures/classical_attractor_vs_data.pdf
  • Notebook: notebooks/data_and_generative_model.ipynb
  • Cell: the one containing plt.savefig("../figures/classical_attractor_vs_data.pdf", dpi=400)
  • Reads: data/mouse_data/tc_data.npz
  • Panels:
    • a: ring-attractor schematic
    • b: circulant weight matrix
    • c: translation-invariant tuning curves
    • d: flow of the paper
    • e: tuning curves measured in each mouse
    • f, g: mean and fluctuation profiles

One cell draws all seven panels. Panel b shows the classical connectivity kernel J(theta - theta') = J0 + J1 cos(theta - theta') with J0 = 0 and J1 = 1. Its colour limits are symmetric about zero so that white marks the sign change, and it carries no colorbar because the kernel is a schematic with no units.

Figure 2

Ring attractor built from the data: PCA convergence, connectivity, closed-loop integration.

  • Image: figures/data_driven_attractor.pdf
  • Notebook: notebooks/data_driven_attractor.ipynb
  • Cell: the one containing plt.savefig("../figures/data_driven_attractor.pdf", dpi=400)
  • Reads: data/mouse_data/tc_data.npz, data/closing_the_loop.npz, data/convergence_pcs.npz, data/convergence_distances.npz, data/surrogate_bump_sims.npz, data/surrogate_spectra.npz, data/velocity_integration_sims.npz

One cell draws the whole figure. The closed-loop integration panels come from closing_the_loop.npz, which closing_the_loop.ipynb builds from the raw recordings; the other panels come from caches written by this notebook. Both random steps, the scrambled-noise shuffle and the initial conditions of the convergence analysis, are seeded.

Figure 3

Circular symmetry in the distribution of head-direction responses.

  • Image: figures/circular_symmetry_in_data.pdf
  • Notebook: notebooks/data_and_generative_model.ipynb
  • Cell: the one containing plt.savefig("../figures/circular_symmetry_in_data.pdf", dpi=400)
  • Reads: data/mouse_data/tc_data.npz, data/grid_search_results.npz

Panel b's matched-uniform null is the only random draw in the figure, and it is seeded. Panels a and c are deterministic.

On rerunning: Rebuilding grid_search_results.npz with python -m ring.gp_opt can land on a different, equally good optimum, because the loss surface is a Monte Carlo estimate that is nearly flat near its minimum. The released cache holds the fit the paper reports, so panels drawn from a rebuilt fit shift slightly while showing the same thing.

Figure 4

Tuning curves and connectivity from the generative model.

  • Image: figures/generative_model_tuning.pdf
  • Notebook: notebooks/data_and_generative_model.ipynb
  • Cell: the one containing plt.savefig("../figures/generative_model_tuning.pdf") # SAVE_FIGURES-gated
  • Reads: data/mouse_data/tc_data.npz, data/grid_search_results.npz
  • Panels:
    • a-f: covariance, Gaussian-process samples, softplus nonlinearity, error vs. sigma, error landscape, and the data/model correlation
    • g: 24 independent samples of tuning curves from the fitted process

One cell assembles all seven panels. Panel e's axes are labelled '$b$ [soft threshold]' and '$\beta$ [sharpness]', matching the notation in the paper.

On rerunning: Rebuilding grid_search_results.npz with python -m ring.gp_opt can land on a different, equally good optimum, because the loss surface is a Monte Carlo estimate that is nearly flat near its minimum. The released cache holds the fit the paper reports, so panels drawn from a rebuilt fit shift slightly while showing the same thing.

Figure 5

Model vs. data: profiles, peak statistics, symmetry and information.

  • Image: figures/model_vs_data.pdf
  • Notebook: notebooks/data_and_generative_model.ipynb
  • Cell: the one containing plt.savefig("../figures/model_vs_data.pdf") # SAVE_FIGURES-gated
  • Reads: data/analysis_results.npz, data/mouse_data/tc_data.npz, data/grid_search_results.npz
  • Panels:
    • a, b: mean and fluctuation profiles, model vs. data
    • c: peak counts at three z-thresholds
    • d: peak-height histograms for the first three peaks
    • e: flip symmetry, full distribution and zoomed tail
    • f: head-direction information

Peak detection treats the tuning curve as circular and checks the final angular bin, so every curve contributes at least one peak, as a circular signal must.

On rerunning: Rebuilding analysis_results.npz redraws the four generative-model peak-count arrays, since they are a fresh sample from the model rather than a function of the data, so panel c shifts slightly. The four arrays measured from the recordings are exact. Rebuilding grid_search_results.npz can likewise land on a different, equally good optimum (its loss surface is a nearly flat Monte Carlo estimate), shifting the model-side panels. Reading the released caches reproduces the committed figure.

Figure 6

Circular geometry, disordered embedding, and the spectrum of the optimal weights.

  • Image: figures/disordered_vs_circulant_spectra.pdf
  • Notebook: notebooks/spectra.ipynb
  • Cell: the one containing plt.savefig("../figures/disordered_vs_circulant_spectra.pdf", dpi=400)
  • Reads: data/spectra_cache.npz
  • Panels:
    • a: ring-embedding schematic
    • b-h: weight matrices, spectrum, eigenvalue planes, and eigenvector scatters

The tuning curves are generated in the notebook rather than measured; spectra_cache.npz only stores the results of the expensive computations, and the notebook recomputes it from scratch if it is absent. The spectra use ridge regularization lambda = 1e-8, applied as Gamma_x / (Gamma_phi + lambda); the leading eigenvalues and the pattern of doublets and singlets are stable under that choice.

On rerunning: Singular vectors are defined only up to sign and the seed does not fix which sign the solver returns, so the rightmost subplot of panel g can come out sign-flipped on different hardware or a different BLAS build. Deleting data/spectra_cache.npz forces a recompute of the mean-field weight profile; the released cache predates the seed on that computation, so a recompute shifts the circulant-side panels slightly while recomputes agree with each other exactly.

Figure 7

Dynamical mean-field theory of the disordered ring attractor.

  • Image: figures/dmft_theory.pdf
  • Notebook: notebooks/dmft.ipynb
  • Cell: the one containing plt.savefig("../figures/dmft_theory.pdf", dpi=400)
  • Reads: data/jacobian_results.npz, data/dmft_simulation_results.npz

No random numbers enter anywhere in this pipeline. Panels b, c and f use (sigma, beta) = (1.4211, 2.7659), the values quoted in the Methods. DMFTModel carries its own regularization constant, 1e-12 by default, which guards the continuum inversion against becoming singular as Ghat^phi_n approaches zero. That constant is a numerical guard, unrelated to the ridge used when fitting finite-N networks elsewhere in the code.

Figure 8

Grid-cell simulations from the disordered attractor.

  • Image: figures/grid_cell_simulations.pdf
  • Notebook: notebooks/grid_sims.ipynb
  • Cell: the one containing plt.savefig("../figures/grid_cell_simulations.pdf", bbox_inches="tight", dpi=450) # SAVE_FIGURES-gated
  • Reads: data/grid_analysis_results.npz, data/eta_analysis.npz, data/gridness_hist_digitized.npz, data/experimental_gridness_scores.npy
  • Panels:
    • a: rat grid-cell rate maps published by Hafting et al. (2005), loaded from figures/external/hafting2005_grid_ratemaps.png and reproduced with permission from Springer Nature
    • b: grid scores digitized from Nayebi et al. (2021), replotted as our own histogram
    • c-f: simulation output, drawn from the caches

Panels a and b are experimental results from other groups rather than model output; figures/external/README.md gives their terms of use. Panels c to f read grid_analysis_results.npz, which despite the similar name is a different file from the analysis_results.npz that Figure 5 uses. The example cells shown in panels d and e are whichever simulated cells fall nearest a target grid score, so a different seed changes which cells appear without changing what the panel shows. Panel d's input-current maps are displayed sign-flipped to positive skewness where needed, because the generative process is sign-symmetric and only the positively skewed realization looks like a grid cell once rectified; the flip leaves panel c's grid scores and panel e's autocorrelations exactly as they were. Panel f is not a raw PCA projection. The leading components are near-degenerate in eigenvalue and defined only up to sign, so which three of them a standard projection would pick is arbitrary; the panel instead uses a fixed display frame pinned to the two known toroidal phases, with axes labelled torus 1, 2 and 3.

Supplementary figures

Figure S1

Low-rank connectivity: kappa trajectories.

  • Image: figures/low_rank_connectivity.pdf
  • Notebook: notebooks/weight_matrix_analyses.ipynb
  • Cell: the one containing plt.savefig("../figures/low_rank_connectivity.pdf"
  • Reads: nothing; everything it needs is computed in the notebook

An illustrative synthetic figure. The low-rank connectivity is built from a seeded random draw in the cell above the plotting cell.

Figure S2

Mixture loadings: the attractor is the whole torus.

  • Image: figures/low_rank_mixture_torus.pdf
  • Notebook: notebooks/weight_matrix_analyses.ipynb
  • Cell: the one containing plt.savefig("../figures/low_rank_mixture_torus.pdf"
  • Reads: nothing; everything it needs is computed in the notebook

Built on the same rank-four geometry and the same seed as Figure S1, with one change: the neuron loadings are drawn from a two-component Gaussian mixture, so each neuron loads onto one doublet only. Every ring is then stable at once and the attractor is the whole torus, rather than the union of rings in Figure S1. Layout, kappa normalization, colormap and axis limits are copied from Figure S1 so that the two read as a pair.

Figure S3

Left and right singular vectors of the connectivity.

  • Image: figures/left_right_singular_vectors.png
  • Notebook: notebooks/weight_matrix_analyses.ipynb
  • Cell: the one containing plt.savefig("../figures/left_right_singular_vectors.png"
  • Reads: nothing; everything it needs is computed in the notebook

The singular vectors come from the decomposition computed in the cell above, whose tuning curves are drawn from a seeded generator.

Figure S4

Real vs. surrogate connectivity matrices and their spectra.

  • Image: figures/real_vs_surrogate_matrices.png
  • Notebook: notebooks/weight_matrix_analyses.ipynb
  • Cell: the one containing plt.savefig("../figures/real_vs_surrogate_matrices.png"
  • Reads: nothing; everything it needs is computed in the notebook

The surrogate-matrix panels are identical on every run, because their random orthogonal matrices are drawn from a separately seeded generator; only the real-J heatmap and its singular-value curve depend on the seeded tuning-curve draw.

Figure S5

Origin of the Mexican-hat connectivity profile.

  • Image: figures/mexican_hat_origin.pdf
  • Notebook: notebooks/mexican_hat_and_asymmetry.ipynb
  • Cell: the one containing plt.savefig("../figures/mexican_hat_origin.pdf"
  • Reads: nothing; everything it needs is computed in the notebook

The plotting cell deconvolves normalized probability densities, stabilized by a hardcoded 1e-6 constant. That constant is specific to this deconvolution and is not the ridge used elsewhere in the code. The tuning curves it works from are generated earlier in the notebook from a seeded generator.

Figure S6

Asymmetric connectivity models.

  • Image: figures/asymmetric_models.png
  • Notebook: notebooks/mexican_hat_and_asymmetry.ipynb
  • Cell: the one containing plt.savefig("../figures/asymmetric_models.png"
  • Reads: nothing; everything it needs is computed in the notebook

This cell uses a ridge of 1e-6 rather than the 1e-8 used elsewhere, and the difference matters. The connectivity here comes from a rank-2 covariance, points on a two-dimensional ring, so the ridge acts on only two directions and enters twice through the inverse. At 1e-8 several near-null modes are admitted, and because the heatmaps autoscale, their large magnitudes wash out the structure the figure is about.

Figure S7

Double normalization of tuning curves.

  • Image: figures/double_normalization.pdf
  • Notebook: notebooks/data_driven_reconstruction.ipynb
  • Cell: the one containing plt.savefig("../figures/double_normalization.pdf"
  • Reads: data/mouse_data/tc_data.npz

The orange curve carries two transformations, not one: the sigma = 2 Gaussian smoothing of the input currents as well as the across-neuron normalization used to build the network. The neuron subsample it plots is seeded.

Figure S8

PCA convergence of the data-driven ring attractor.

  • Image: figures/pca_convergence.png
  • Notebook: notebooks/data_driven_reconstruction.ipynb
  • Cell: the one containing plt.savefig("../figures/pca_convergence.png"
  • Reads: data/mouse_data/tc_data.npz, data/pc_convergence_grid.npz

A sweep over the ridge strength lambda, with the operating value lambda = 1e-8.

On rerunning: Two things can move. The pcs_traj3_grid array in the cache is a stochastic realization, so rebuilding the cache redraws those trajectories, though the released cache reproduces the committed figure. And a different matplotlib release can reassign the categorical colour cycle, which changes the hue and drawing order of the trajectories without moving any of them.

Figure S9

Reconstruction error vs. regularization strength.

  • Image: figures/error_vs_regularization.pdf
  • Notebook: notebooks/data_driven_reconstruction.ipynb
  • Cell: the one containing plt.savefig("../figures/error_vs_regularization.pdf")
  • Reads: data/mouse_data/tc_data.npz, data/pc_convergence_grid.npz

A deterministic log-log plot of the mean squared flow error against lambda, swept from 1e-12 to 1e-2 in decades. The operating value lambda = 1e-8 sits one grid step above the curve's true minimum near 3e-11, so it should not be read as minimizing the curve: the apparent upturn below 3e-11 is an artifact of finite-precision conditioning rather than a property of the flow. The figure is saved at full canvas width without a tight bounding box, so the surrounding whitespace is intentional.

Figure S10

Noise-driven dynamics: circulant vs. disordered.

  • Image: figures/noise_driven_dynamics.png
  • Notebook: notebooks/weight_matrix_analyses.ipynb
  • Cell: the one containing plt.savefig("../figures/noise_driven_dynamics.png", bbox_inches="tight", dpi=400) # SAVE_FIGURES-gated
  • Reads: data/ring_attractor_noise_results.npz
  • Panels:
    • a: the two connectivity matrices
    • b: angular-drift trajectories, disordered network on the left and circulant on the right
    • c: angular stability across noise levels

One cell draws all three panels from the cache. The cache itself is written by a cell that only runs when REGENERATE_CACHES is True; it is seeded for both numpy and torch and is deterministic on a GPU.

Figure S11

Searching for spurious fixed points in finite-N attractors.

  • Image: figures/spurious_fixed_points.pdf
  • Notebook: notebooks/spurious_fixed_points.ipynb
  • Cell: the one containing plt.savefig("../figures/spurious_fixed_points.pdf"
  • Reads: data/mouse_data/tc_data.npz, data/spurious_fixed_points.npz

Two rows of panels at five matched noise levels, row a for the generative network and row b for the network derived from data. The data-derived network converges from every initial condition tested, including a per-neuron standard deviation of 1000, where states begin about 22 ring radii away and still end within 2e-4 of a ring radius of the manifold. Under unstructured initial conditions it also shows a preference for particular bump angles, which weakens as the initialization noise grows. Rebuilding the cache takes about two minutes.

Figure S12

Attractor dynamics at finite N.

  • Image: figures/finite_size_dynamics.pdf
  • Notebook: notebooks/spurious_fixed_points.ipynb
  • Cell: the one containing plt.savefig("../figures/finite_size_dynamics.pdf"
  • Reads: data/mouse_data/tc_data.npz

Seeded for both numpy and torch before any random draw, so it is deterministic on CPU and GPU alike.

Figure S13

Normalized covariance matrices and their eigenvectors.

  • Image: figures/normalized_covariance_eigenvectors.png
  • Notebook: notebooks/data_and_generative_model.ipynb
  • Cell: the one containing plt.savefig("../figures/normalized_covariance_eigenvectors.png"
  • Reads: data/mouse_data/tc_data.npz

Which neurons appear is a seeded random choice, so the panels are the same on every run.

Figure S14

Eigenvalue and singular-value spectra of the data and of subsamples.

  • Image: figures/data_and_subsample_spectra.png
  • Notebook: notebooks/data_driven_reconstruction.ipynb
  • Cell: the one containing plt.savefig("../figures/data_and_subsample_spectra.png", bbox_inches="tight", dpi=400) # SAVE_FIGURES-gated
  • Reads: data/mouse_data/tc_data.npz
  • Panels:
    • a: spectrum of the mouse-derived weights at N = 1533
    • b: how the spectrum converges with sample size, at N = 100, 500, 1000 and 1533

Panel a reuses the weights and tuning curves computed earlier in the same notebook and involves no random draw. Panel b builds idealized tuning curves and weights at each N with a ridge of 1e-8; it is a seeded random realization rather than an exact function of the data, so the same seed reproduces it but a different one would not.

Figure S15

Eigenvalue spectrum of the grid-cell connectivity.

  • Image: figures/grid_cell_eigenvalues.pdf
  • Notebook: notebooks/grid_sims.ipynb
  • Cell: the one containing plt.savefig("../figures/grid_cell_eigenvalues.pdf"
  • Reads: nothing; everything it needs is computed in the notebook

The leading eigenvalues of the connectivity, computed in the notebook from sampled data.

On rerunning: The spectrum is exactly six-fold degenerate, and eigenvalue solvers do not promise any particular ordering inside a degenerate cluster. Changing the number of BLAS threads, or running on a GPU instead of a CPU, can therefore swap individual points within a cluster. The six-fold degeneracy the figure is about is unaffected.

Figure S16

Attractor dynamics in a reservoir RNN.

  • Image: figures/reservoir_rnn_dynamics.png
  • Notebook: notebooks/reservoir_rnn.ipynb
  • Cell: the one containing plt.savefig("../figures/reservoir_rnn_dynamics.png", bbox_inches='tight', dpi=300)
  • Reads: nothing; everything it needs is computed in the notebook

One cell trains five reservoirs from scratch, which makes this the slowest figure here to regenerate. The reservoir weights, the input projection and the initial state are all drawn fresh from a seeded generator on each run.

On rerunning: Torch's CPU and GPU random-number streams differ even from the same seed, so a CPU run draws different reservoirs than a GPU run and about 10.6 percent of pixels change. The gain sweep, the convergent and non-convergent regimes, and the boundary between them all stay as they are. The committed image was made on a GPU, so match it on a GPU.