Visualization

Built on Apple’s open-source Embedding Atlas (MIT). Neuroencoder only prepares the data: 2-D projection, cosine neighbours, a time axis from each window’s t_start, and any labels you pass. Everything accepts an EmbeddingResponse or a plain [N, 768] array.

import neuroencoder as ne
from neuroencoder import embeddings

r = embeddings(open("night.edf", "rb"), stride_seconds=30)
ne.explore(r, labels=stages)            # Jupyter widget, coloured by label (or by time if no labels)
ne.serve(r, labels=stages)              # local web app at http://127.0.0.1:5055, MCP endpoint at /mcp
ne.export(r, "atlas")                   # standalone web app folder (or "atlas.zip") to share or host
ne.plot(r, color=stages, save="umap.png")   # static UMAP

Embedding Atlas export coloured by label — Two nights of PhysioNet Sleep-EDF (subjects 0 and 1), two EEG channels, 1,784 thirty-second windows embedded with EPI-300K and coloured by the expert-scored stage. The model was not trained on this data.

Reproduce the figure

import numpy as np, mne, neuroencoder as ne
from neuroencoder import embeddings
from mne.datasets.sleep_physionet.age import fetch_data

stage = {"Sleep stage W": "Wake", "Sleep stage 1": "N1", "Sleep stage 2": "N2",
         "Sleep stage 3": "N3", "Sleep stage 4": "N3", "Sleep stage R": "REM"}
E, L = [], []
for psg, hyp in fetch_data(subjects=[0, 1], recording=[1]):
    raw = mne.io.read_raw_edf(psg, preload=True).pick(["EEG Fpz-Cz", "EEG Pz-Oz"])
    raw.set_annotations(mne.read_annotations(hyp))
    ev, ids = mne.events_from_annotations(raw, event_id={k: i for i, k in enumerate(stage)}, chunk_duration=30.)
    sf = raw.info["sfreq"]; x = raw.get_data()
    ep = np.stack([x[:, s:s + int(30 * sf)] for s in ev[:, 0] if s + int(30 * sf) <= x.shape[1]])
    E.append(embeddings(ep, sfreq=sf, channel_names=["Fpz", "Pz"]).to_numpy())
    L += [{v: stage[k] for k, v in ids.items()}[c] for c in ev[:len(ep), 2]]
ne.export(np.concatenate(E), "atlas", labels=L)

Arguments

All four functions share these:

str | list

One label per window (sleep stage, event, subject). Becomes the default colour and a filterable column.

str | list

Source recording per window.

array

Window start in seconds. Taken from the response automatically.

dict

Extra per-window columns, e.g. {"subject": ids, "score": p}.

str

Column to colour by; defaults to label, else time_s.

str

default:"umap"

umap, tsne or pca.

int

default:"15"

Neighbours for the projection and the neighbour list.

bool

default:"false"

Side and bottom panels.

For agents

ne.serve(..., mcp=True) exposes the Atlas MCP server at /mcp, so a coding agent can select, filter and inspect points in the running view. ne.export writes a static folder an agent can host or attach; ne.plot(..., save=path) returns the PNG path.

Large sets

For hundreds of thousands of windows, export to parquet and use the Atlas CLI directly:

embedding-atlas embeddings.parquet --x x --y y --neighbors neighbors --mcp

Get started

Reference

Reproduce the figure

Arguments

For agents

Large sets

​Reproduce the figure

​Arguments

​For agents

​Large sets

Reproduce the figure

Arguments

For agents

Large sets