> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuroencoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Functions and classes

```python theme={null}
import neuroencoder as ne
from neuroencoder import MRL
```

## MRL

```python theme={null}
model = MRL.from_pretrained(device="cuda")
embeddings = model.predict(images, dim=192)
```

The MRL model class. Auto-downloads from `Neuroencoder/epi-embedding` on HuggingFace and caches locally. Pass `token=...` for explicit authentication.

### MRL.from\_pretrained

```python theme={null}
MRL.from_pretrained(repo_id="Neuroencoder/epi-embedding", filename="mrl.pt", device=None, **kwargs)
```

<ParamField path="repo_id" type="str" default="&#x22;Neuroencoder/epi-embedding&#x22;">
  HuggingFace repo identifier.
</ParamField>

<ParamField path="filename" type="str" default="&#x22;mrl.pt&#x22;">
  Checkpoint filename in the repo.
</ParamField>

<ParamField path="device" type="str">
  Torch device. Defaults to CUDA if available.
</ParamField>

<ParamField path="**kwargs">
  Forwarded to `huggingface_hub.hf_hub_download` (e.g. `token="hf_..."`).
</ParamField>

### MRL.from\_checkpoint

```python theme={null}
MRL.from_checkpoint(path, device=None)
```

Load from a local file. Handles raw state dicts and PyTorch Lightning checkpoint formats.

### model.embed

```python theme={null}
model.embed(eeg, sfreq, channel_names=None, dim=192, filter=True, stride_seconds=None)
```

One-call convenience: raw EEG -> L2-normalized embeddings as a numpy array. Equivalent to `model.predict(ne.preprocess(eeg, ...), dim=dim).cpu().numpy()`.

<ParamField path="eeg" type="np.ndarray | torch.Tensor" required>
  Raw EEG `[C, T]` continuous, or `[N, C, T]` pre-epoched.
</ParamField>

<ParamField path="sfreq" type="float" required>
  Sampling frequency in Hz.
</ParamField>

<ParamField path="channel_names" type="list[str]">
  10-20 names (required if `C != 8`).
</ParamField>

<ParamField path="dim" type="int" default="192">
  One of `768`, `384`, `192`, `48`, `16`.
</ParamField>

### model.predict

```python theme={null}
model.predict(x, dim=192)
```

Returns `[N, dim]` L2-normalized embeddings on the model's device. Runs in `torch.no_grad()`. Input is auto-moved to the model device.

<ParamField path="x" type="torch.Tensor" required>
  `[B, 8, 224, 224]` from `ne.preprocess`.
</ParamField>

<ParamField path="dim" type="int" default="192">
  One of `768`, `384`, `192`, `48`, `16`.
</ParamField>

### model.forward

```python theme={null}
model(x, dim=192)
```

Forward pass with gradients (for fine-tuning). Output is **not** L2-normalized.

### Attributes

```python theme={null}
model.encoder    # underlying encoder
model.projector  # MRL projector head
```

## ne.preprocess

```python theme={null}
ne.preprocess(data, sfreq, channel_names=None, filter=True, stride_seconds=None, device=None)
```

Raw EEG to temporal matrix images. Handles any channel count (averages into 8 brain regions, zero-fills missing). Returns `[N, 8, 224, 224]`.

<ParamField path="data" type="np.ndarray | torch.Tensor" required>
  `[C, T]` continuous, or `[N, C, T]` pre-epoched.
</ParamField>

<ParamField path="sfreq" type="float" required>
  Sampling frequency in Hz.
</ParamField>

<ParamField path="channel_names" type="list[str]">
  10-20 electrode names.
</ParamField>

<ParamField path="filter" type="bool" default="true">
  Apply 1-100 Hz bandpass and 50/100 Hz notch.
</ParamField>

<ParamField path="stride_seconds" type="float" default="1.0">
  Hop between successive 30s epochs. Default is 1.0s (continuous sliding window). Pass `30.0` for non-overlapping epochs — typical for classification with epoch-level labels.
</ParamField>

<ParamField path="device" type="str">
  Torch device.
</ParamField>

## ne.explore

```python theme={null}
ne.explore(embeddings, filename=None, method="umap", show_charts=False, show_table=False)
```

Interactive Apple Embedding Atlas widget. Defaults: time-coloring, side panels hidden.

<ParamField path="embeddings" type="np.ndarray | torch.Tensor" required>
  `[N, D]`.
</ParamField>

<ParamField path="filename" type="str | list[str]">
  Source-file label for each point. String applies to all, or one entry per point.
</ParamField>

<ParamField path="method" type="str" default="&#x22;umap&#x22;">
  `"umap"`, `"tsne"`, or `"pca"`.
</ParamField>

<ParamField path="n_neighbors" type="int" default="15">
  UMAP / KNN neighbors.
</ParamField>

<ParamField path="point_size" type="float" default="3.0">
  Scatter point size.
</ParamField>

<ParamField path="epoch_seconds" type="float" default="30.0">
  Seconds per embedding (used to compute the time axis).
</ParamField>

<ParamField path="show_charts" type="bool" default="false">
  Show right-side charts panel.
</ParamField>

<ParamField path="show_table" type="bool" default="false">
  Show bottom data-table panel.
</ParamField>

## ne.serve

```python theme={null}
ne.serve(embeddings, filename=None, method="umap", host="127.0.0.1", port=5055, open_browser=True)
```

Standalone Atlas web server (no Jupyter). Same defaults as `ne.explore`. Blocks until Ctrl-C.

<ParamField path="host" type="str" default="&#x22;127.0.0.1&#x22;">
  Bind address.
</ParamField>

<ParamField path="port" type="int" default="5055">
  Server port.
</ParamField>

<ParamField path="open_browser" type="bool" default="true">
  Open the URL in the default browser.
</ParamField>

(Other args identical to `ne.explore`.)

## ne.plot

```python theme={null}
ne.plot(embeddings, color=None, **kwargs)
```

Static matplotlib UMAP. Default coloring: time (viridis).

<ParamField path="embeddings" type="np.ndarray | torch.Tensor" required>
  `[N, D]`.
</ParamField>

<ParamField path="color" type="str | array">
  `"time"` (default), `"cluster"`, or array of values.
</ParamField>

## Constants

```python theme={null}
from neuroencoder import MRL_DIMS
# [768, 384, 192, 48, 16]
```