engram

FmriCleaner — nilearn.signal.clean, wrapped

Fri, 19 Jun 2026 00:00:00 GMT

%pip install nilearn pydantic rich -q --progress-bar off

import warnings
warnings.filterwarnings("ignore")

import numpy as np
import matplotlib.pyplot as plt
import pydantic
from typing import Literal
%config InlineBackend.figure_format = "retina"

from rich import pretty
pretty.install()

neuralset wraps nilearn.signal.clean in a tiny pydantic config object called FmriCleaner. If the five knobs (detrend, standardize, high_pass / low_pass, ensure_finite) are new to you, read signal-clean first — it builds the intuition from a synthetic signal. This notebook assumes that and focuses on what the wrapper adds:

it’s a validated config object, not a bare function call;
it flips the data contract to (n_features, time) (nilearn wants (time, n_features));
and it guards the clean() call in a way that — per neuroai#130 — silently drops ensure_finite when the signal-processing knobs are off.

We reproduce the class inline so the guard is visible and the notebook runs without the full (torch-heavy) neuralset install.

# Reproduced verbatim from neuralset.extractors.neuro.FmriCleaner (neuralset 0.2.2)
# so this notebook is self-contained. Source: github.com/facebookresearch/neuroai

class FmriCleaner(pydantic.BaseModel):
    """Configuration for fMRI signal cleaning."""

    model_config = pydantic.ConfigDict(extra="forbid")
    standardize: Literal["zscore_sample", "zscore", "psc"] | bool = "zscore_sample"
    detrend: bool = True
    high_pass: float | None = None
    low_pass: float | None = None
    filter: Literal["butterworth", "cosine"] | None = None
    ensure_finite: bool = True

    def clean(self, data: np.ndarray, t_r: float) -> np.ndarray:
        if (
            self.detrend
            or self.standardize
            or (self.high_pass is not None)
            or (self.low_pass is not None)
        ):
            import nilearn.signal

            data = data.T  # set time as first dim
            shape = data.shape
            data = nilearn.signal.clean(
                data.reshape(shape[0], -1),
                t_r=t_r,
                standardize=self.standardize,
                high_pass=self.high_pass,
                low_pass=self.low_pass,
                filter=self.filter,
                detrend=self.detrend,
                ensure_finite=self.ensure_finite,
            )
            data = data.reshape(shape).T
        return data

A config object, not a function

FmriCleaner is a pydantic.BaseModel: every field is typed and validated, defaults are declared once, and extra="forbid" means a misspelled option is rejected at construction instead of silently ignored. This is the pattern neuralset uses for all its configs.

print("fields & defaults:")
for name, field in FmriCleaner.model_fields.items():
    print(f"  {name:<14} default={field.default!r}")

print("\ndefault config:", FmriCleaner().model_dump())

# extra="forbid" -> a typo is a hard error, not a silent no-op
try:
    FmriCleaner(detrendd=True)          # note the typo
except pydantic.ValidationError as e:
    print("\nrejected unknown field 'detrendd':", e.errors()[0]["type"])

fields & defaults:
  standardize    default='zscore_sample'
  detrend        default=True
  high_pass      default=None
  low_pass       default=None
  filter         default=None
  ensure_finite  default=True

default config: {'standardize': 'zscore_sample', 'detrend': True, 'high_pass': None, 'low_pass': None, 'filter': None, 'ensure_finite': True}

rejected unknown field 'detrendd': extra_forbidden

The data contract: `(n_features, time)`

nilearn.signal.clean expects time first — (time, n_features). FmriCleaner.clean(data, t_r) flips that: it takes (n_features, time) (the layout the rest of neuralset uses), transposes internally, cleans, then transposes back — so shape in equals shape out, for any number of feature dimensions. t_r is the repetition time in seconds (1 / frequency).

We build the same synthetic voxel as the signal-clean notebook — baseline + drift + slow wave + fast noise — and plant one NaN, because non-finite values are normal in fMRI (masks, registration, surface projection all leave them behind).

t_r = 2.0                       # seconds per sample (a typical fMRI TR)
n   = 200
t   = np.arange(n) * t_r

truth  = 100 + 0.05*t + 3*np.sin(2*np.pi*0.02*t) + 1*np.sin(2*np.pi*0.20*t)
signal = truth.copy().reshape(1, -1).astype(np.float32)   # (n_features=1, time)
signal[0, 50] = np.nan                                     # one planted NaN

print("signal shape (features, time):", signal.shape, " finite:", np.isfinite(signal).all())

# shape is preserved for any number of feature dims:
multi = np.random.randn(5, n).astype(np.float32)
print("multi-voxel in:", multi.shape, "-> out:", FmriCleaner().clean(multi, t_r).shape)

signal shape (features, time): (1, 200)  finite: False
multi-voxel in: (5, 200) -> out: (5, 200)

The guard — and the bug (#130)

The whole issue lives in clean()’s opening if: it calls nilearn.signal.clean only when a signal-processing knob (detrend / standardize / a filter) is on. But ensure_finite is forwarded inside that call — so when every signal-processing knob is off, the call is skipped and ensure_finite goes with it, even when you set it to True.

Watch the same planted NaN (sample 50) under three configs:

def describe(name, x):
    x = np.asarray(x).ravel()
    print(f"{name:<48} finite={str(np.isfinite(x).all()):<5} sample50={x[50]:8.3f}")

describe("default (detrend+zscore)", FmriCleaner().clean(signal.copy(), t_r))
describe("detrend=F, standardize=F", FmriCleaner(detrend=False, standardize=False).clean(signal.copy(), t_r))
describe("detrend=F, standardize=F, ensure_finite=True", FmriCleaner(detrend=False, standardize=False, ensure_finite=True).clean(signal.copy(), t_r))

default (detrend+zscore)                         finite=True  sample50= -13.451
detrend=F, standardize=F                         finite=False sample50=     nan
detrend=F, standardize=F, ensure_finite=True     finite=False sample50=     nan

default_out = FmriCleaner().clean(signal.copy(), t_r)
leaked_out  = FmriCleaner(detrend=False, standardize=False, ensure_finite=True).clean(signal.copy(), t_r)

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))
ax1.plot(t, default_out.ravel())
ax1.set_title("default — NaN scrubbed (finite)")
ax1.set_xlabel("Time (s)"); ax1.set_ylabel("Amplitude"); ax1.grid(True, linestyle=":", alpha=0.5)

ax2.plot(t, leaked_out.ravel())
ax2.set_title("ensure_finite=True ignored — gap at the NaN")
ax2.set_xlabel("Time (s)"); ax2.set_ylabel("Amplitude"); ax2.grid(True, linestyle=":", alpha=0.5)

plt.tight_layout()
plt.show()

The takeaway

ensure_finite is data hygiene — a different category from the signal-processing knobs (see signal-clean for why). The wrapper accidentally couples the two: by nesting ensure_finite inside a guard that only fires for detrend / standardize / filters, it turns “raw signal, just keep it finite” (detrend=False, standardize=False, ensure_finite=True) into “raw signal, NaNs and all” — and those NaNs detonate the moment a downstream model or fit touches them.

The fix is to honour ensure_finite independently of the other knobs — either by adding it to the guard, or by handling finite-replacement explicitly when the guard is otherwise false. That design choice is the next step.

nilearn.signal.clean — the five knobs

Fri, 19 Jun 2026 00:00:00 GMT

Open In Colab

%pip install --upgrade nilearn -q --progress-bar off

import warnings
warnings.filterwarnings("ignore")

import numpy as np
import matplotlib.pyplot as plt
import nilearn.signal
%config InlineBackend.figure_format = 'retina'

from rich import pretty
pretty.install()

nilearn.signal.clean(signals, ...) is the workhorse fMRI preprocessing call. It bundles five operations behind one function, and they split into two categories:| Category | Knob | What it does || —————– | ———————— | ——————————- || Signal processing | detrend | remove slow drift || Signal processing | standardize | rescale to mean 0, std 1 || Signal processing | high_pass / low_pass | temporal frequency filters || Data hygiene | ensure_finite | replace NaN / ±Inf with 0 |The way to build intuition: construct a synthetic signal out of known parts, plant one bad value, then turn a single knob at a time and watch what each one removes.This notebook grew out of facebookresearch/neuroai#130 — a wrapper that skipped clean() entirely when the signal-processing knobs were off, silently disabling ensure_finite along with them. The cells below are why that matters.

# nilearn.signal.clean expects shape (time, n_features). One feature (one voxel).
t_r = 2.0                      # repetition time: 2 s per sample (a typical fMRI TR)
n   = 200
t   = np.arange(n) * t_r       # time axis in seconds

baseline   = 100.0                          # BOLD has a big DC offset
drift      = 0.05 * t                       # slow linear drift (scanner warm-up etc.)
slow_signal= 3.0 * np.sin(2*np.pi*0.02 * t) # the "neural" signal we want to KEEP (0.02 Hz)
fast_noise = 1.0 * np.sin(2*np.pi*0.20 * t) # high-frequency nuisance (0.20 Hz)

clean_truth = baseline + drift + slow_signal + fast_noise
signal = clean_truth.copy().reshape(-1, 1)  # (time, 1)
signal[50, 0] = np.nan                       # drop in one non-finite value

The signal and the planted `NaN`

Our synthetic voxel is baseline (100) + linear drift + slow 0.02 Hz wave + fast 0.20 Hz noise. The slow wave is the “neural” signal we want to keep; drift and fast noise are the nuisances.

We then set one sample to NaN. That isn’t artificial paranoia — non-finite values are normal in fMRI: brain masks, registration/resampling, and surface projection all leave NaN where there is no valid data. Downstream models choke on a single NaN, so scrubbing it is routine hygiene, not an edge case.

def describe(name, x):
    x = np.asarray(x).ravel()
    print(f"{name:<28} mean={np.nanmean(x):7.3f}  std={np.nanstd(x):6.3f}  "
          f"finite={np.isfinite(x).all()}")

describe("raw input", signal)

plt.title("Raw")
plt.plot(t, signal)
plt.xlabel("Time (s)")
plt.ylabel("Amplitude")
plt.grid(True, linestyle=":", alpha=0.5)
plt.show()

raw input                    mean=109.975  std= 5.999  finite=False

Knob 1 — `ensure_finite`: data hygiene

The odd one out: it’s about data validity, not signal shape. It replaces NaN / +Inf / -Inf with 0 and touches nothing else — watch sample 50 go from NaN → 0.

Note: in nilearn, ensure_finite defaults to False — you have to ask for it explicitly.

only_finite = nilearn.signal.clean(
    signal,
    detrend=False,
    standardize=False,
    ensure_finite=True
)
describe("ensure_finite only", only_finite)
print("  -> sample 50 was NaN, now:", only_finite[50, 0])

plt.title("Only Finite")
plt.plot(t, only_finite)
plt.xlabel("Time (s)")
plt.ylabel("Amplitude")
plt.grid(True, linestyle=":", alpha=0.5)
plt.show()

ensure_finite only           mean=109.425  std= 9.797  finite=True
  -> sample 50 was NaN, now: 0.0

Knob 2 — `detrend`: removes drift, and amplifies a stray `NaN`

detrend fits one straight line across the whole time series and subtracts it. So if you don’t set ensure_finite=True, the planted NaN poisons that least-squares fit and every sample comes back NaN — one bad value contaminates all 200. Try it: drop ensure_finite=True and re-run.

Lesson: a single non-finite value does not stay local once a real operation touches it. With ensure_finite=True (below), the drift is cleanly removed and the signal recenters near 0.

detrended = nilearn.signal.clean(
    signal,
    detrend=True,
    standardize=False,
    ensure_finite=True
)
describe("detrend", detrended)

plt.title("Detrended")
plt.plot(t, detrended)
plt.xlabel("Time (s)")
plt.ylabel("Amplitude")
plt.grid(True, linestyle=":", alpha=0.5)
plt.show()

detrend                      mean=  0.000  std= 7.732  finite=True

Knob 3 — `standardize`: rescales, doesn’t reshape

standardize is an affine transform: z = (x − mean) / std. Subtracting and dividing by constants changes the y-axis scale, not the shape — so plotted on its own it looks like nothing happened. The proof is in describe: mean goes ~100 → 0 and std → ~1. To see it, overlay raw vs standardized on twin y-axes: identical curves, different scales.

The spike at t≈100 is the NaN→0 value, now ~11 std below the baseline — a reminder that 0-fill is only “neutral” once the data is mean-centered.

# standardize=True/False is deprecated in recent nilearn; "zscore_sample" is the modern spelling.
standardized = nilearn.signal.clean(
    signal,
    detrend=False,
    ensure_finite=True,
    standardize="zscore_sample"
)
describe("standardize", standardized)

plt.title("Standardized")
plt.plot(t, standardized)
plt.xlabel("Time (s)")
plt.ylabel("Amplitude")
plt.grid(True, linestyle=":", alpha=0.5)
plt.show()

standardize                  mean=  0.000  std= 0.997  finite=True

Knob 4 — `high_pass` / `low_pass`: temporal filters

Mirror images. High-pass keeps fast content and strips the slow drift/baseline, so the signal recenters on 0. Low-pass keeps the slow wave and smooths away the fast noise, leaving the baseline intact.

Watch the NaN→0 sample behave like an impulse: high-pass exposes it as a spike to ≈ −100 (the ~100 baseline got subtracted), while low-pass smears it into a dip with ringing on either side. Same theme as detrend, now in the frequency domain — one bad sample bleeds into its neighbours.

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))

high_passed = nilearn.signal.clean(
    signal,
    t_r=t_r,                # sampling interval — required for filtering
    detrend=False,
    standardize=False,
    ensure_finite=True,
    high_pass=0.01
)
describe("high_pass 0.01 Hz", high_passed)

ax1.plot(t, high_passed)
ax1.set_title("High Passed")
ax1.set_xlabel("Time (s)")
ax1.set_ylabel("Amplitude")
ax1.grid(True, linestyle="--", alpha=0.5)


low_passed  = nilearn.signal.clean(
    signal,
    t_r=t_r,
    detrend=False,
    standardize=False,
    ensure_finite=True,
    low_pass=0.10
)
describe("low_pass 0.10 Hz",  low_passed)

ax2.plot(t, low_passed)
ax2.set_title("Low Passed")
ax2.set_xlabel("Time (s)")
ax2.set_ylabel("Amplitude")
ax2.grid(True, linestyle="--", alpha=0.5)

plt.tight_layout()
plt.show()

high_pass 0.01 Hz            mean=  0.026  std= 7.590  finite=True
low_pass 0.10 Hz             mean=109.422  std= 7.798  finite=True

engram Cookbook

Tue, 16 Jun 2026 00:00:00 GMT

How to use this cookbook

This is the living handbook for engram - a reference I keep coming back to and extend as I learn. It covers two things:

How the repo works - structure, conventions, and the render/publish workflow.
How to author a notebook - the Quarto features worth using.

For every visual feature in Part 2 you get two blocks: a Source block (the markup that produces it) and a Renders as block (what Quarto produces from it). Render locally with quarto preview to see the rendered halves live.

When you adopt something new, add a section and append a line to the Update log.

Note

A .ipynb carries Quarto front matter in a raw cell at the very top (the cell above this one). In a .qmd file the same YAML sits between --- fences.

Part 1 - The repo

Adding a new notebook

Drop the .ipynb into the relevant project folder (or create a new folder).
Add a front-matter raw cell at the top (see the starter).
Add a Colab badge as the first markdown cell.
Cite any papers with @key and add the entries to references.bib.
Run the notebook and save it with its outputs, then commit and push.

The notebook then appears automatically on the homepage listing - no manual index edit.

Render & publish workflow

The build never executes notebooks — it renders the outputs already saved in each .ipynb (execute: enabled: false in _quarto.yml). The runner needs no Python, no dependencies, and never downloads data.

So the rule is: run a notebook (locally or in Colab), save it with its outputs, then commit. A notebook committed without outputs renders with no figures.

quarto preview        # live preview while editing (renders saved outputs)
git add . && git commit -m "Add notebook" && git push

Pushing to main triggers the Action, which publishes to the gh-pages branch -> GitHub Pages at bkowshik.github.io/engram.

Part 2 - Authoring with Quarto

Each section below pairs the Source (what you write) with Renders as (what Quarto produces).

Front matter & metadata

Every notebook opens with a raw cell of YAML. This drives the title, the listing entry, categories, and per-document options. (The “rendered” effect here is the page’s title block and listing entry, not inline output.)

Source

---
title: 'Short, specific title'
description: 'One line - shown in the listing and the social card.'
date: '2026-06-16'
date-modified: last-modified # auto-updates from file mtime - good for living docs
categories: [eeg, pytorch, bci] # power the tag filter + listing
bibliography: references.bib # enables @citations
toc: true
code-tools: true # adds the "view source / copy" menu
image: thumbnail.png # optional - used in the social preview card
---

Callouts

Coloured boxes for asides, insights, and gotchas. Flavours: note, tip, warning, important, caution.

Source

::: {.callout-tip}

## Key insight

The takeaway in one or two sentences.
:::

::: {.callout-warning collapse="true"}

## Gotcha (collapsed by default)

Add `collapse="true"` to fold long asides.
:::

Renders as

Key insight

The takeaway in one or two sentences.

Gotcha (collapsed by default)

Add collapse="true" to fold long asides.

Math

Source

Inline: $h_t = \sigma(W x_t + b)$

$$
\mathcal{L} = \frac{1}{N}\sum_{i=1}^{N} -\,y_i \log \hat{y}_i
$$ {#eq-nll}

Reference it with `@eq-nll`.
$$

Renders as

Inline:

The negative log-likelihood in Equation 1 is the loss the Shallow ConvNet trains with. $$

Citations & bibliography

With bibliography: references.bib in the front matter, cite inline and Quarto builds the reference list automatically.

Source

The Shallow ConvNet comes from @schirrmeister2017.
A parenthetical citation looks like [@schirrmeister2017].

…resolving against this .bib entry:

@article{schirrmeister2017,
  title   = {Deep learning with convolutional neural networks for EEG decoding and visualization},
  author  = {Schirrmeister, Robin Tibor and others},
  journal = {Human Brain Mapping}, year = {2017}, volume = {38}, pages = {5391--5420}
}

Renders as

The Shallow ConvNet comes from Schirrmeister et al. (2017). A parenthetical citation looks like (Schirrmeister et al. 2017). (The full reference appears in the auto-generated list at the end of the page.)

Diagrams (Mermaid & Graphviz)

Diagram-as-code - perfect for an architecture sketch instead of an ASCII block.

Source (4 outer backticks so the inner block shows literally)

```{mermaid}
flowchart LR
  X["EEG (22 ch x 1125)"] --> T["Temporal conv"]
  T --> S["Spatial conv"] --> P["Square -> pool -> log"] --> C["Classifier"]
```

Renders as

flowchart LR
  X["EEG (22 ch x 1125)"] --> T["Temporal conv"]
  T --> S["Spatial conv"] --> P["Square -> pool -> log"] --> C["Classifier"]

Code cells: source + output together

A code cell is the clearest case: by default Quarto shows both the source and the output it produces. The cell below is labelled and captioned so the figure can be cross-referenced - and its code stays visible above the plot.

Set %config InlineBackend.figure_format = "retina" once near the top so the saved plots are crisp on hi-DPI screens.

import numpy as np
import matplotlib.pyplot as plt
%config InlineBackend.figure_format = "retina"   # crisp hi-DPI plots

t = np.linspace(0, 1, 500)
x = np.sin(2 * np.pi * 10 * t)

plt.figure(figsize=(6, 2.4))
plt.plot(t, x)
plt.xlabel("Time (s)"); plt.ylabel("Amplitude")
plt.tight_layout()
plt.show()

Figure 1: A 10 Hz sine wave - a stand-in for a band-limited neural signal.

Figure 1 shows the rendered output above, directly under the code that produced it. Control what each cell reveals with cell options:

Option	Effect
`# \| echo: false`	hide the code, keep the output
`# \| output: false`	run the code, hide the output
`# \| code-fold: true`	keep the code but collapse it behind a toggle
`# \| label: fig-x`/`tbl-x`	make it cross-referenceable (the `fig-`/`tbl-` prefix matters)
`# \| fig-cap: "..."`	figure caption
`# \| warning: false`	suppress warnings in the render

The default (echo: true) is exactly the “show both” behaviour - use the options above only when you deliberately want to hide one half.

Cross-references

Source

See @fig-signal and @eq-nll. Sections work too: tag a heading `{#sec-setup}`, then `@sec-setup`.

Renders as

See Figure 1 and Equation 1. Quarto numbers and links them automatically, so references never go stale when you reorder.

Tabsets

Stack alternatives behind tabs - handy for “same idea, two frameworks”.

Source

::: {.panel-tabset}

## NumPy

```python
import numpy as np
x = np.zeros((22, 1125))
```

## PyTorch

```python
import torch
x = torch.zeros(22, 1125)
```

:::

Renders as

import numpy as np
x = np.zeros((22, 1125))

import torch
x = torch.zeros(22, 1125)

Figures, captions & lightbox

Source

![Shallow ConvNet, Figure 2 from the paper.](architecture.png){#fig-arch}

Enable click-to-zoom for all images via _quarto.yml:

format:
  html:
    lightbox: true

Renders as: a captioned, numbered figure (Figure 1: ...) that is cross-referenceable with @fig-arch and opens in a zoom overlay on click.

Listings, categories & search (site-level)

These live in _quarto.yml / index.qmd, but every notebook feeds them:

Listing - index.qmd auto-indexes every **/*.ipynb, sorted by date.
Categories - the categories: in each notebook become clickable filters.
Full-text search - on by default; searches every notebook, client-side, free on GitHub Pages.

Social cards, comments & formats (site-level config)

These are _quarto.yml settings rather than inline output:

website:
  open-graph: true # rich link previews when shared
  twitter-card: true
  comments:
    giscus: # discussion thread per post, backed by GitHub Discussions
      repo: bkowshik/engram

format:
  html: default
  revealjs: # a speaker deck from the same notebook cells
    slide-level: 2

Render a slide deck from any notebook with quarto render notebook.ipynb --to revealjs.

No execution on build

engram sets this in _quarto.yml:

execute:
  enabled: false # render saved notebook outputs; never launch a kernel

This keeps publishing trivial: do the heavy compute wherever suits you (Colab, a GPU box, locally), save the notebook with its outputs, and the build just renders those - no kernel, no dependencies, no dataset downloads on CI.

If you would rather have the build execute notebooks and cache the results, the alternative is execute: freeze: auto plus a committed _freeze/ directory - but that needs the full environment available at render time.

Colab badge

Source (first markdown cell of a notebook)

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bkowshik/engram/blob/main/FOLDER/NOTEBOOK.ipynb)

Renders as: a clickable “Open In Colab” badge that launches the notebook in Google Colab.

Copy-paste starter

Front matter for a new notebook (raw cell at the top):

---
title: ''
description: ''
date: 'YYYY-MM-DD'
date-modified: last-modified
categories: []
bibliography: references.bib
toc: true
code-tools: true
---

Before you push:

Front matter filled in (title, description, date, categories)
Colab badge points at the right folder/filename
Papers cited with @key, entries added to references.bib
Cells reveal what you intend (echo/output/code-fold)
Notebook saved with its outputs (the build never executes it)
Plots are retina (%config InlineBackend.figure_format = "retina")
No private references (paths, personal notes)

Update log

Append a line whenever you learn or adopt something new.

Date	Change
2026-06-16	Created. Each Part 2 feature now shows Source + Renders-as; example plot cell shows code and output together.

References

Schirrmeister, Robin Tibor, Jost Tobias Springenberg, Lukas Dominique Josef Fiederer, et al. 2017. “Deep Learning with Convolutional Neural Networks for EEG Decoding and Visualization.” Human Brain Mapping 38 (11): 5391–420. https://doi.org/10.1002/hbm.23730.

Events

Thu, 25 Jun 2026 03:25:29 GMT

print('Hello, brain!')

B = "git+https://github.com/bkowshik/neuroai.git@main"

!uv pip install -q --system \
  "moabb" \
  "neuralset[all] @ {B}#subdirectory=neuralset-repo" \
  "{B}#subdirectory=neuralfetch-repo"

!uv pip install -q --system globus-sdk

!uv pip freeze | grep neural

import os, getpass
import pandas as pd

import neuralset as ns
from neuralset import events
from neuralset.events import etypes
from neuralfetch.utils import compute_study_info

import globus_sdk

# To download data from https://www.globus.org/ Ex: Brennan2019Hierarchical
os.environ["NEURALFETCH_GLOBUS_CLIENT_ID"] = getpass.getpass("Globus Client UUID: ")
os.environ["NEURALFETCH_GLOBUS_CLIENT_SECRET"] = getpass.getpass("Globus Client Secret: ")

len(etypes.Event._CLASSES), list(etypes.Event._CLASSES.keys())[:5]

# Create event from a dictionary
data = {
    "type": "Word",
    "start": 1.0,
    "timeline": "run-01",
    "text": "hello",
    "surprisal": 3.2,
}
event = etypes.Event.from_dict(data)
event

# Create event using the class
word = etypes.Word(
    start=1.5,
    duration=0.3,
    timeline="sub-01_run-01",
    text="hello"
)
word

# Create a timeline using a Pandas DataFrame
tl = "sub-01_run-01"
rows = [
    dict(type="Word", start=10.5, duration=0.3, timeline=tl, text="The"),
    dict(type="Word", start=11.0, duration=0.4, timeline=tl, text="cat"),
    dict(type="Word", start=11.6, duration=0.3, timeline=tl, text="sat"),
    dict(type="Sentence", start=10.5, duration=1.4, timeline=tl, text="The cat sat", language='en', subject='bkowshik', session=1, run=1)
]
df = events.standardize_events(pd.DataFrame(rows))
df

Studies

catalog = ns.Study.catalog()
len(catalog), list(catalog.keys())[:5]

study = ns.Study(name="Fake2025Meg", path=ns.CACHE_FOLDER)
events = study.run()

columns = ["subject", "type", "start", "duration", "timeline"]
events[columns]

Thu, 25 Jun 2026 03:25:29 GMT

Ref: https://docs.pytorch.org/tutorials/beginner/deep_learning_60min_blitz.html

import numpy as np

import torch
from torch import optim
from torch import nn
import torch.nn.functional as F

data = [[1, 2], [3, 4], [5, 6]]
t = torch.tensor(data)
t

tensor([[1, 2],
        [3, 4],
        [5, 6]])

torch.rand_like(t, dtype=torch.float)

tensor([[0.6160, 0.9337],
        [0.7736, 0.9430],
        [0.5630, 0.0227]])

t = torch.rand(3, 4)
t.shape, t.dtype, t.device

(torch.Size([3, 4]), torch.float32, device(type='cpu'))

device = torch.accelerator.current_accelerator() if torch.accelerator.is_available() else 'cpu'
t = t.to(device)
t.shape, t.dtype, t.device

(torch.Size([3, 4]), torch.float32, device(type='cuda', index=0))

t = torch.ones(5, 5, dtype=int)
t[:, 3] = 0
t

tensor([[1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1]])

torch.cat([t, t, t], dim=1)

tensor([[1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1],
        [1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1]])

Minimal PyTorch neural network

X = torch.randn(10, 1); y = 2 * X                        # data: y = 2x
model = nn.Linear(1, 1)                                  # model
opt = torch.optim.SGD(model.parameters(), lr=0.05)       # optimizer
loss_fn = nn.MSELoss()                                   # loss

for epoch in range(25):
    opt.zero_grad()                                      # 1. reset grads
    loss = loss_fn(model(X), y)                          # 2. forward + loss
    loss.backward()                                      # 3. backprop  ← grads now exist
    parts = [f"loss {loss.item():.4f}"] + [              # print after backward
        f"{name} {param.item():.4f} (grad {param.grad.item():.4f})"
        for name, param in model.named_parameters()
    ]
    print(" | ".join(parts))
    opt.step()                                           # 4. update weights

loss 7.2326 | weight -0.8592 (grad -5.0265) | bias -0.3763 (grad -0.2476)
loss 6.0221 | weight -0.6079 (grad -4.5810) | bias -0.3639 (grad -0.2673)
loss 5.0156 | weight -0.3789 (grad -4.1754) | bias -0.3506 (grad -0.2810)
loss 4.1784 | weight -0.1701 (grad -3.8060) | bias -0.3365 (grad -0.2898)
loss 3.4819 | weight 0.0202 (grad -3.4696) | bias -0.3220 (grad -0.2944)
loss 2.9023 | weight 0.1937 (grad -3.1632) | bias -0.3073 (grad -0.2956)
loss 2.4197 | weight 0.3519 (grad -2.8841) | bias -0.2925 (grad -0.2940)
loss 2.0178 | weight 0.4961 (grad -2.6298) | bias -0.2778 (grad -0.2900)
loss 1.6831 | weight 0.6275 (grad -2.3982) | bias -0.2633 (grad -0.2843)
loss 1.4042 | weight 0.7475 (grad -2.1871) | bias -0.2491 (grad -0.2770)
loss 1.1718 | weight 0.8568 (grad -1.9947) | bias -0.2353 (grad -0.2686)
loss 0.9780 | weight 0.9565 (grad -1.8195) | bias -0.2218 (grad -0.2594)
loss 0.8165 | weight 1.0475 (grad -1.6597) | bias -0.2089 (grad -0.2495)
loss 0.6817 | weight 1.1305 (grad -1.5141) | bias -0.1964 (grad -0.2392)
loss 0.5693 | weight 1.2062 (grad -1.3814) | bias -0.1844 (grad -0.2287)
loss 0.4756 | weight 1.2753 (grad -1.2604) | bias -0.1730 (grad -0.2180)
loss 0.3973 | weight 1.3383 (grad -1.1500) | bias -0.1621 (grad -0.2073)
loss 0.3320 | weight 1.3958 (grad -1.0494) | bias -0.1517 (grad -0.1967)
loss 0.2774 | weight 1.4483 (grad -0.9577) | bias -0.1419 (grad -0.1863)
loss 0.2319 | weight 1.4962 (grad -0.8741) | bias -0.1326 (grad -0.1762)
loss 0.1938 | weight 1.5399 (grad -0.7978) | bias -0.1238 (grad -0.1663)
loss 0.1621 | weight 1.5797 (grad -0.7282) | bias -0.1155 (grad -0.1567)
loss 0.1355 | weight 1.6162 (grad -0.6647) | bias -0.1076 (grad -0.1474)
loss 0.1133 | weight 1.6494 (grad -0.6068) | bias -0.1002 (grad -0.1386)
loss 0.0948 | weight 1.6797 (grad -0.5540) | bias -0.0933 (grad -0.1301)

# Input, output and prediction
with np.printoptions(precision=4, suppress=True):
    print(torch.cat([X, y, model(X)], dim=1).detach().numpy())

[[-0.9295 -1.859  -1.6739]
 [-0.384  -0.768  -0.7425]
 [ 1.663   3.3259  2.7526]
 [ 1.0355  2.071   1.6813]
 [ 0.1104  0.2209  0.1017]
 [-1.2856 -2.5712 -2.2819]
 [-0.3015 -0.603  -0.6016]
 [-1.3607 -2.7215 -2.4102]
 [ 0.6638  1.3276  1.0466]
 [-0.0945 -0.189  -0.2482]]

engram

FmriCleaner — nilearn.signal.clean, wrapped

A config object, not a function

The data contract: (n_features, time)

The guard — and the bug (#130)

The takeaway

nilearn.signal.clean — the five knobs

The signal and the planted NaN

Knob 1 — ensure_finite: data hygiene

Knob 2 — detrend: removes drift, and amplifies a stray NaN

Knob 3 — standardize: rescales, doesn’t reshape

Knob 4 — high_pass / low_pass: temporal filters

engram Cookbook

How to use this cookbook

Part 1 - The repo

Adding a new notebook

Render & publish workflow

Part 2 - Authoring with Quarto

Front matter & metadata

Callouts

Math

Citations & bibliography

Diagrams (Mermaid & Graphviz)

Code cells: source + output together

Cross-references

Tabsets

Figures, captions & lightbox

Listings, categories & search (site-level)

Social cards, comments & formats (site-level config)

No execution on build

Colab badge

Copy-paste starter

Update log

References

Events

Studies

Minimal PyTorch neural network

The data contract: `(n_features, time)`

The signal and the planted `NaN`

Knob 1 — `ensure_finite`: data hygiene

Knob 2 — `detrend`: removes drift, and amplifies a stray `NaN`

Knob 3 — `standardize`: rescales, doesn’t reshape

Knob 4 — `high_pass` / `low_pass`: temporal filters