Quickstart

Install and set your key

pip install neuroencoder
export NEUROENCODER_API_KEY=ne_...

Keys are issued on request through the contact form.

Embed an array

Any number of channels and any sampling rate. Channel names are 10-20 labels.

import mne
from neuroencoder import embeddings

raw = mne.io.read_raw_edf("recording.edf", preload=True)
r = embeddings(
    raw.get_data(),                  # [channels, samples]
    sfreq=raw.info["sfreq"],
    channel_names=raw.ch_names,
    stride_seconds=30,               # one window per 30 s; default 1.0 (sliding)
)
emb = r.to_numpy()                   # [n_epochs, 768], L2-normalised
t0 = r.t_start                       # window start in seconds

Or send the file

EDF, BDF, FIF, EEGLAB .set and BrainVision .vhdr are read server-side; nothing is stored.

r = embeddings(open("recording.edf", "rb"))

embeddings(...) is the same as embeddings.create(...). For explicit configuration use Neuroencoder(api_key=..., base_url=...).embeddings.create(...). Without a key, the call runs locally if ~/.cache/neuroencoder/epi300k.pt exists.

Visualise

import neuroencoder as ne
ne.explore(r, labels=stages)        # Jupyter widget
ne.export(r, "atlas")               # standalone web app to share

Common patterns

import numpy as np
sim = emb @ emb.T                                  # cosine similarity (already normalised)
nearest = np.argsort(-sim[0])[1:6]                 # 5 windows most similar to the first

from sklearn.linear_model import LogisticRegression
clf = LogisticRegression(max_iter=200).fit(emb[train], y[train])   # linear probe

curl

curl https://api.neuroencoder.com/v1/embeddings \
  -H "Authorization: Bearer $NEUROENCODER_API_KEY" \
  -F file=@recording.edf -F 'metadata={"stride_seconds": 30}'

Errors

Every error is JSON with a fix field that says what to change:

{"error": {"message": "sfreq is required with .npy input.", "type": "invalid_request_error",
           "code": "missing_sfreq", "param": "sfreq", "fix": "Pass metadata={\"sfreq\": 256, ...}"}}

Get started

Reference

Visualise

Common patterns

curl

Errors

​Visualise

​Common patterns

​curl

​Errors

Visualise

Common patterns

curl

Errors