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:

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-python build is available. For .cin Phantom files use pims.Cine instead (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-python build is available. For .cin Phantom files use pims.Cine instead (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

\[D(q, \Delta t) = A(q)\,[1 - e^{-D q^2 \Delta t}] + B(q)\]

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 over n_average frame pairs separated by delta frames.

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.DataFrame indexed by lag time (s) with wavevector q (µm⁻¹) columns; also stored as video.result_ddm. interval/muperpix default 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 (see calculate_ddm()). radius_um is 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) and mass columns.

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.

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); set ensemble=False for 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; D then gives η. For water-like tracers expect n ≈ 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:

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).