Reproducible analysis of high-speed AFM videos, in Python.
Poster 32

1Load

Raw file, every frame's time kept

2Process

Levelled, denoised, aligned

3Analyse

Detect and track: an antibody stepping on DNA origami

4Share

playNano OME-TIFF open in napari
OME-TIFF in napari and Fiji · HDF5 / NPZ · MP4 / GIF
Built for HS-AFM video
Raw files in, timing kept
Provenance
Every step and parameter saved
Expandable
Your code becomes a recorded step

Explore

QR code: github.com/derollins/playNano
code
QR code: derollins.github.io/playNano
docs

Try it

pip install playnano playnano play video.h5-jpk

Free and open source (GPL-3.0). Plugins and contributions welcome.

Swipe left and right, or use the bar below. Tap any video to enlarge.

Raw files in, timing kept

Each video opened straight from the instrument's own files. Time stamps and scale bars come from each file's metadata: nothing typed in by hand.

Annexin lattice

JPK NanoRacer
.jpk folder

0.875 s/frame · 232 frames · 0.33 nm/px. The dark holes are gaps in the lattice.

Fast

JPK NanoRacer
.jpk folder

0.035 s/frame: 28 frames a second · 198 frames, shown in real time. 128 × 64 px over a 20 × 20 nm square.

Bacteriorhodopsin

JPK NanoRacer
.jpk folder

0.10 nm/px · 1.04 s/frame · 35 frames

Antibody walking

JPK NanoRacer
.h5-jpk, one file

0.27 s/frame · 273 frames · interlaced scanning handled

DNA origami landing on mica

JPK NanoWizard ULTRA Speed 3
.jpk folder

1.03 s/frame · 598 frames over 10 minutes · 5 nm/px

Data: Pothineni, Barner & Keller, Zenodo 2024 (CC BY 4.0)

Collagen fibrils forming

Asylum Research Cypher VRS
.ARIS, one file

1.1 s/frame · 520 frames over 9 minutes · 7.8 nm/px

Data: Roth, Hoop, Williams, Nanda & Baum, figshare 2024 (CC BY 4.0)

Peptide on a membrane

Bruker
Nanoscope files (2014)

10.5 s/frame · 111 frames over 19 minutes · 512 × 256 px over 1 × 1 µm

.asd

Ando-type HS-AFM
.asd, one file (2019)

1.0 s/frame · 34 frames · 300 × 200 px over 139 × 139 nm

Each opened with the same short recipe: plane, mask, row alignment, flatten, smooth (walking: its own recipe). Fast scans often use fewer lines than columns; these are drawn at the true scan shape from each file's metadata.

Following drift

The sample drifts under the tip, so each frame is shifted to line up with the others. Usually that just works. On a repeating lattice it can quietly fail.

1 · Standard alignment: line every frame up with frame 1

Annexin lattice, 8 nm of slow drift over 200 s. Raw: the picture slides inside the box where frame 1 was. Aligned: the box moves instead, and the lattice stays still.
Average of all frames, before and after alignment
Average of every frame: raw, the lattice smears; aligned, it comes out sharp. (Drift here stays under one unit cell, so frame 1 works as the reference.)

2 · A lattice: every unit looks the same

Bacteriorhodopsin crystal, 100 frames. Grey = outside the frame. Rolling: the frame moves steadily with the drift. Standard: it keeps jumping back.
The drift each method found. Rolling: a smooth 30 nm path. Standard: stuck near the start.

Why it fails silently

Matched against frame 1, the closest copy of the lattice wins. Once the drift passes one unit cell, that's the wrong copy. The images still look perfect (the average is just as sharp), but positions over time are off by whole unit cells.

6.3 nm
typical snap back: one lattice spacing (BR ≈ 6.2 nm)
9 snaps
in 100 frames

Rolling alignment

Match each frame to the average of the last few aligned frames instead, so the reference moves with the drift. A built-in playNano step, recorded like any other.

filters: - name: rolling_frame_align window: 5 # frames in the reference max_jump: 4 # px per frame, rides over glitches

Antibody walking

unpublished · please don't photograph

An antibody steps between two binding sites on a DNA origami tile. Find it, follow it, and fit the steps.

Tracked on the drift-corrected video; green line = path so far
Position along the origami (grey), with the fitted steps (gold) drawn as the video plays
11.7 nm
between the two sites
4 steps
in 59 s of tracking
0.27 s
per frame, 273 frames
Raw: tilt, line noise, drift
Processed: levelled, filtered, aligned and cropped

Processing: the recipe, saved with the result

drop_final_framesremove_plane mask_mean_offset · 0.5polynomial_flatten · 2 cleargaussian_filter · σ 1 align_frames · crop_squarezero_mean

Analysis: my notebook, on the processed stack

find the origamire-align on itthreshold the antibody trackposition along the origamiGaussian mixture + BIC → steps

The number of sites isn't fixed in advance: the data picks it, as on the BRCA1–BARD1 page. Still in a notebook, so a candidate plugin.

BRCA1–BARD1 on two nucleosomes

data & Fig. 6: Burdett, Foglizzo et al., NAR 2023 (CC BY 4.0)

A DNA-repair protein reaching from one nucleosome to the next. The paper tracked it by eye. playNano reproduces that, then lets the movement itself pick out the states.

1 · Reproduce the paper: three points chosen by eye

Tracked and aligned: the box (inset) follows the particle, so p1–p3 stay on the same spot of the molecule
playNano: height under each point
The paper's Fig. 6D: heights at p1, p2 and p3 over time
Paper, Fig. 6D: the same three traces. p2 drops at 10–20 s; p3 rises from ~50 s, falls at ~100 s.

2 · Let the movement decide

Subtract the average image and everything that stays still disappears; only what moves is left. Our eyes notice movement the same way. PCA then finds the main patterns of movement.

The three main patterns of movement around the nucleosomes
The three main patterns (nucleosomes masked). Red and blue swap: height appears in one place as it disappears in another.

3 · From movement to states

Every frame is a point: how much of pattern 1 and pattern 2 it contains. Frames that move alike land together.
1

Subtract the average

Only what moved in this frame is left.

2

Score each frame

How much of each pattern it contains: 5 numbers per frame. Each frame becomes a point.

3

Find the groups

Fit 2 to 8 groups (Gaussian mixture); BIC picks the number that explains the most without over-fitting. Each group is a state.

4

Use time

A state usually lasts more than one frame, so a hidden Markov model removes one-frame flickers (13 changes → 7).

Every frame labelled: frames that move the same way are grouped
When the state changes
54 s · 96 s
the two big changes, in all 45 settings I tried. Paper: bridging at 50–70 s, p3 drops at ~100 s
4–5
states, chosen by the data (BIC), not set in advance. Paper: "at least four"
The paper's four states above playNano's four state averages and their differences from the overall average
Found without picking frames: states 3 and 4 line up with the paper's bridged and released forms, in look and in timing. Each average uses 20–71 frames.
playNano: load, level, track, alignPCA: patterns of movement Gaussian mixture + BIC: how many stateshidden Markov model: no one-frame flicker

One molecule, one movie. Built in a marimo notebook on top of the recorded processing; next step: a plugin (see Plugins).

Antibody shape

unpublished · please don't photograph

An antibody can sit compact or extended. Following one for 8.5 minutes: which is it, frame by frame?

Detected and tracked: green outline; box turns gold when extended
Following the particle
Largest dimension of the box, every frame; dashed line = threshold (38.7 nm, chosen by eye)
26 → 42 nm
typical compact → extended
11%
of frames extended
14
switches in 238 frames
2.2 s
per frame

How long does each state last?

State timeline and dwell times
Most extended visits last a single frame: faster switching than 2.2 s per frame can resolve. One long visit of 41 s.

The analysis: three recorded steps

feature_detection

Mask everything above the background (mean + 3σ), keep objects > 300 px

particle_tracking

Link objects frame to frame (≤ 80 px jump); keep the longest track

particle_boundary_size

Bounding box of the tracked mask → largest dimension

threshold=66 px

Parameter of the same step: each frame labelled compact or extended

Teal = built in, gold = my plugin (see Plugins). Run twice from the same recipe: identical results. A box depends on rotation; the true longest length (Feret) changes 1 frame of 238.

Raw
ML levelling (afMLevel plugin, twice) + smoothing, before any analysis

Plugins: your code as a recorded step

A recipe is a list of step names. playNano looks each name up among its own steps and every installed package, so a new step is just a package that registers a name.

Processing plugins

functions
playnano.filters
one frame in → one frame out
playnano.video_processing
whole video in → whole video out

Your own filter, or a scikit-image one

Both live in your own small plugin package. You don't edit playNano or scikit-image.

my_playnano_plugin/src/my_playnano_plugin/filters.py
def remove_background(frame, sigma=20): return frame - gaussian_filter(frame, sigma) def tv_denoise(frame, weight=0.1): # wraps scikit-image return denoise_tv_chambolle(frame, weight=weight) tv_denoise.__version__ = skimage.__version__
my_playnano_plugin/pyproject.toml
[project.entry-points."playnano.filters"] remove_background = "my_playnano_plugin.filters:remove_background" tv_denoise = "my_playnano_plugin.filters:tv_denoise"

pip install -e ./my_playnano_plugin, and both names work in any recipe.

Run in the demo notebook

tap to zoom
Notebook: built-in, own and scikit-image steps run in one pipeline, with the recorded versions
Built-in, my own and scikit-image steps in one pipeline; the record has scikit-image's version (0.26.0).
Notebook: the plugin's pyproject.toml
pyproject.toml
Notebook: filters.py
filters.py

Already wrapped

afMLevel ML levelling · whole video or per framepnanolocz levelling · per frameTopoStats filters · per frame

Analysis modules

classes

Built on playNano's abstract base class: a template that says what every module must have. Leave one out and Python won't create it.

class AnalysisModule(ABC): @property @abstractmethod def name(self) -> str: ... # the name used in recipes @abstractmethod def run(self, stack, previous_results=None, **params) -> dict: ... # results, saved + recorded

previous_results hands over earlier steps' outputs, e.g. the particle tracks.

A one-off analysis becomes a shareable module

demo notebook · tap to zoom
1

One-off, in a project notebook

One-off notebook cell counting DNA origami triangles per frame, with the plot and why it is hard to share
Counting origami triangles landing (public data). Works, but the settings are buried, sizes are in pixels, and the output is only a plot.
2

Copy the key parts into the template

The empty AnalysisModule template
The template
The filled-in ParticleCountModule
Settings → parameters; the loop copied as is
3

Same answer, and now it's recorded

Module gives identical counts; the recipe records its name, version and parameters
4

Share it

Register the name in your package's pyproject.toml and pip install
One line in your package's pyproject.toml; anyone can then use it in a recipe.

My real one

particle_bounding.ipynb → particle_boundary_size in playNano-plugins, version 0.1.0: the antibody shape analysis.

Use it your way

Same recipe, same results, from a viewer, a script or the command line. Outputs open in the tools you already use.

playNano viewer

BRCA1–BARD1 on nucleosomes, NAR 2023
Raw → apply recipe → processed. Change the colour map and z-scale, then export GIF / MP4 / OME-TIFF / HDF5.

napari

OME-TIFF
Opens with the standard reader, at the right pixel size. Nothing added.

Fiji

Bio-Formats
Scale bar and time stamp drawn by Fiji from the file's own metadata: 0.39 nm/px, 0.655 s/frame.

Command line

playnano process video.h5-jpk \ --processing-file recipe.yaml \ --export tif,h5,npz --make-gif playnano analyze out.h5 \ --analysis-file analysis.yaml # a whole experiment for d in imaging-*/; do playnano process "$d" --processing-file recipe.yaml --export tif done
Batch of processed videos
Batch: every video from one experiment, same recipe, one loop.

Python

from playnano.afm_stack import AFMImageStack from playnano.processing.pipeline import ProcessingPipeline stack = AFMImageStack.load_data("imaging.h5-jpk") pipe = ProcessingPipeline(stack) pipe.add_filter("remove_plane") pipe.add_mask("mask_mean_offset", factor=0.6) pipe.add_filter("gaussian_filter", sigma=0.8) pipe.add_filter("align_frames") record = pipe.run() # every step + parameter

The same steps can be saved as a YAML recipe and rerun from the command line.

Run it twice

d7e54c73…
SHA-256 of the BRCA1–BARD1 result, run 1
d7e54c73…
run 2: every pixel identical
saved in the file: provenance
{ "name": "align_frames", "version": "0.2.0", "params": { "max_shift": 30, "pre_filter_sigma": 6, ... }, "metadata": { "shifts": [[0,0], [0,0], [-1,-1], ...] } } # + playnano 0.5.2, numpy 2.5.5, scipy 1.18.1, ...

Jupyter

playNano demo notebook · test data
playNano demo notebook in Jupyter: processing pipeline cell and its output
Build the pipeline, run it, print the record, and plot the result in the notebook.

marimo

BRCA1–BARD1 analysis notebook
marimo notebook: point inputs, a switch, and height-over-time plots of the aligned BRCA1–BARD1 particle
Reactive: move a point or flip the switch and the plots update. Height over time at three spots on the drift-corrected particle.

Colour maps are a measurement scale

If lightness doesn't rise evenly with height, low features vanish and HS-AFM videos flicker.

afm_brown

default
Linear lightness · R² 0.996

playnano_gold

high contrast
Full black → white · R² 0.978

classic_afm

legacy look
Dark plateau hides the substrate · R² 0.763

afmhot

matplotlib
Kinked lightness · R² 0.872

Same published video (BRCA1–BARD1, NAR 2023), with the height range re-fitted every frame as auto-scaling does. Watch the background.

Test patterns

idea from ehtplot (Event Horizon Telescope)
Pyramid and bump test patterns in four colour maps
A bent lightness curve invents features and hides others. classic_afm draws a dark ring and a bright square that aren't in the data, and loses the bumps in its dark third; afmhot loses them at the bright end.

Why I made new ones

Equal steps in height should look like equal steps in brightness. The familiar AFM browns bend: a long black stretch at the bottom, then a jump.

import playnano # registers them plt.imshow(h, cmap="afm_brown")

Ordinary matplotlib colour maps: use them in any script, or in napari and Fiji via exports.

Perceived lightness along each colour map
Perceived lightness (CIE L*) along each map. Dashed straight line = perfectly linear.

Inspired by the colour-map work in ehtplot (github.com/liamedeiros/ehtplot): "a poorly chosen colormap … can fool the human eyes".

×