API reference
microrheology — video in, rheology out.
Two roads from a microscopy movie to material properties:
microrheology.tracking— particle-tracking microrheology (locate → link → MSD → viscosity / moduli)microrheology.ddm— differential dynamic microscopy (image structure function → diffusion → viscosity / radius)
Shared pieces:
microrheology.video— lightweight video container + readingmicrorheology.gser— MSD → G*(ω) via the generalized Stokes–Einstein relationmicrorheology.data— bundled example videos
- class microrheology.Video(frames, fps=100.0, muperpix=0.1, **info)
Frames + metadata + slots for analysis results.
- Parameters:
frames (array-like, shape (n_frames, height, width[, channels]))
fps (frames per second)
muperpix (microns per pixel)
**info (extra metadata (temperature_C, tracer_diameter_um, filename, ...))
- property frame_shape
Shape of a single frame (h, w[, c]).
- property interval
Seconds between frames.
- microrheology.read_video(path, fps=None, muperpix=0.1, max_frames=None, to_gray=True)
Read a video file into a
Video(OpenCV backend).Works with mp4/avi/mov — and inside JupyterLite/Pyodide, where the
opencv-pythonbuild is available. For.cinPhantom files usepims.Cineinstead (desktop only).fps: explicit frames-per-second. When omitted, the container’s metadata is used (falling back to 100). Pass it explicitly when the container metadata is wrong — e.g. the water test videos are 100 fps despite their mp4 headers.
Lightweight video container and readers.
The analysis routines in microrheology.ddm and
microrheology.tracking operate on a Video: an object
with len(), integer indexing (frames as numpy arrays), a
frame_shape attribute, and an info dict for metadata
(fps, microns-per-pixel, temperature, tracer size, …).
Use read_video() for mp4 files (OpenCV backend, works in
JupyterLite/Pyodide). For Phantom .cin files use pims.Cine
directly and wrap it — the analysis code only needs the duck-typed
interface above.
- class microrheology.video.Video(frames, fps=100.0, muperpix=0.1, **info)
Frames + metadata + slots for analysis results.
- Parameters:
frames (array-like, shape (n_frames, height, width[, channels]))
fps (frames per second)
muperpix (microns per pixel)
**info (extra metadata (temperature_C, tracer_diameter_um, filename, ...))
- property frame_shape
Shape of a single frame (h, w[, c]).
- property interval
Seconds between frames.
- microrheology.video.read_video(path, fps=None, muperpix=0.1, max_frames=None, to_gray=True)
Read a video file into a
Video(OpenCV backend).Works with mp4/avi/mov — and inside JupyterLite/Pyodide, where the
opencv-pythonbuild is available. For.cinPhantom files usepims.Cineinstead (desktop only).fps: explicit frames-per-second. When omitted, the container’s metadata is used (falling back to 100). Pass it explicitly when the container metadata is wrong — e.g. the water test videos are 100 fps despite their mp4 headers.
Differential dynamic microscopy (DDM).
DDM turns a plain bright-field microscopy movie into a scattering
experiment: for each lag time Δt, the power spectrum of image
differences is computed and azimuthally averaged to give the image
structure function D(q, Δt). For Brownian particles
so fitting each q-slice gives a relaxation time τ(q) = 1/(D q²);
a power-law fit τ = 1/(D q²) over q yields the diffusion
coefficient, and Stokes–Einstein gives viscosity (or radius).
Reference: Cerbino, R. & Trappe, V., Phys. Rev. Lett. 100, 188102 (2008). https://doi.org/10.1103/PhysRevLett.100.188102
The video argument is any object with len(), integer frame
indexing and frame_shape — e.g. microrheology.video.Video
or a pims reader.
- microrheology.ddm.azimuthal_average(image, center=None)
Azimuthally averaged radial profile of a 2D image.
Bins pixels by integer radius from
center(defaults to the image center) and returns the mean value per bin.
- microrheology.ddm.structure_function(video, delta, n_average=None, start_frame=0, end_frame=None, progress=None)
Mean azimuthally-averaged power spectrum of frame differences.
Averages the
|FFT(I(t+Δt) − I(t))|²radial profile overn_averageframe pairs separated bydeltaframes.
- microrheology.ddm.calculate_ddm(video, n_average=10, n_deltas=20, interval=None, muperpix=None, start_frame=0, end_frame=None, show_progress=True)
Compute the DDM matrix
D(q, Δt)for a video.Returns a
pandas.DataFrameindexed by lag time (s) with wavevectorq(µm⁻¹) columns; also stored asvideo.result_ddm.interval/muperpixdefault to the video metadata.
- microrheology.ddm.ddm_decay(x, off, amp, tau)
Single-exponential DDM relaxation for Brownian particles.
- microrheology.ddm.viscosity_from_ddm(video, radius_um, muperpix=None, qmin=1, qmax=None, temperature_C=25.0, plot=False)
Viscosity (Pa·s) from a DDM-analyzed video.
Needs
video.result_ddm(seecalculate_ddm()).radius_umis the tracer radius in microns. Assumes dilute Brownian tracers via Stokes–Einstein.
- microrheology.ddm.radius_from_ddm(video, viscosity, muperpix=None, qmin=1, qmax=None, temperature_C=25.0, plot=False)
Tracer radius (µm) from a DDM-analyzed video of known viscosity.
- microrheology.ddm.browse_ddm(video, interval=None, start_frame=0, end_frame=None)
Interactive widget: frame pair → difference → FFT → radial profile.
- microrheology.ddm.explore_ddm(video, interval=None)
Interactive widget: inspect D(q,Δt) slices and per-q fits.
Particle-tracking microrheology.
Thin, documented wrappers around trackpy implementing the classic
Crocker–Grier workflow: locate → link → mean-squared displacement →
viscosity / moduli.
Reference: Crocker, J. C. & Grier, D. G., J. Colloid Interface Sci. 179, 298–310 (1996). https://doi.org/10.1006/jcis.1996.0217
trackpy is imported lazily so import microrheology stays light;
these functions raise a clear error if it is missing
(pip install trackpy). Note: trackpy ships no wheels, so this path
is desktop/Colab only — the DDM path in microrheology.ddm is the
browser-friendly one.
- microrheology.tracking.locate_frame(frame, diameter=15, minmass=1000, invert=True)
Locate particles in a single frame (Crocker–Grier).
Returns a DataFrame with
x,y(px) andmasscolumns.
- microrheology.tracking.batch_locate(video, diameter=15, minmass=1000, invert=True, start_frame=0, end_frame=None)
Locate particles in every frame; returns a stacked DataFrame.
- microrheology.tracking.link_trajectories(features, search_range=5, memory=3, min_length=50)
Link per-frame features into trajectories; drop short stubs.
- microrheology.tracking.mean_squared_displacement(traj, muperpix, fps, max_lagtime=100, ensemble=True)
Mean-squared displacement (µm²) vs lag time (s).
Uses the ensemble MSD by default (
trackpy.emsd); setensemble=Falsefor per-particle MSDs (trackpy.imsd). Returns a pandas Series indexed by lag time in seconds.
- microrheology.tracking.viscosity_from_msd(tau, msd, temperature_C=25.0, radius_um=0.2, dim=2)
Viscosity (Pa·s) from a Newtonian MSD via Stokes–Einstein.
Fits
MSD = 2·dim·D·τin log space;Dthen givesη. For water-like tracers expectn ≈ 1(diffusive).
MSD → viscoelastic moduli via the generalized Stokes–Einstein relation.
Implements T. Mason’s algebraic approximation to the GSER: the
mean-squared displacement’s local log-log slope and curvature give
|G*(ω)|, and a second-order analytic continuation splits it into
G′(ω) and G″(ω).
References:
Mason, T. G. & Weitz, D. A., Phys. Rev. Lett. 74, 1250–1253 (1995). https://doi.org/10.1103/PhysRevLett.74.1250
Mason, T. G., Rheol. Acta 39, 371–378 (2000). https://doi.org/10.1007/s003970000094
Mason, T. G. et al., Phys. Rev. Lett. 79, 3284–3287 (1997) (second-order corrections).
This is an independent implementation of the published method.
- microrheology.gser.msd_to_moduli(tau, msd, radius_um, temperature_K, dim=2, clip=0.03, smooth_width=0.7)
Convert MSD(τ) to the complex modulus G*(ω).
- Parameters:
tau (array, seconds — lag times)
msd (array, µm² — mean-squared displacement)
radius_um (tracer radius in microns)
temperature_K (absolute temperature)
dim (dimensionality of the MSD data (2 for video tracking))
clip (moduli below
clip×|G*|are set to zero (unreliable))smooth_width (Gaussian width for the local log-derivative fits;) – increase for noisy data
- Returns:
omega (array, rad/s)
G_star (complex array, Pa (
.real= G′,.imag= G″))Needs ~8 points per decade; warns if the local curvature is high.
Bundled example videos: download-once, cache, reuse.
The two water test videos (400 nm tracers in water, 0.1 µm/px,
100 fps) live in the repo under data/; the full-fidelity
.cin Phantom files stay on the releases page. Videos are never
shipped inside the wheel — water_video() fetches and caches
them under ~/.cache/microrheology/.
- microrheology.data.WATER_LOW = {'description': '400 nm tracers in water, low concentration (particle tracking)', 'filename': '400nm_100dil_water_01umpix_100fps_short.mp4', 'fps': 100.0, 'muperpix': 0.1, 'temperature_C': 25.0, 'tracer_diameter_um': 0.4}
Low tracer concentration — suited to particle tracking.
- microrheology.data.WATER_HIGH = {'description': '400 nm tracers in water, high concentration (DDM)', 'filename': '400nm_water_01umpix_100fps_short.mp4', 'fps': 100.0, 'muperpix': 0.1, 'temperature_C': 25.0, 'tracer_diameter_um': 0.4}
High tracer concentration — DDM territory (tracking infeasible).
- microrheology.data.water_video(which='low')
Local path to a water test video, downloading once if needed.
- Parameters:
which ("low" (tracking) or "high" (DDM))
- microrheology.data.CIN_URLS = {'high': 'https://github.com/marcocaggioni/microrheology_water_test/releases/download/1.0/400nm_water_01umpix_100fps_short.cine', 'low': 'https://github.com/marcocaggioni/microrheology_water_test/releases/download/1.0/400nm_100dil_water_01umpix_100fps_short.cin'}
Full-fidelity Phantom files (large; desktop only, via pims).