Skip to content

README.md

Latest commit

 

History

History
186 lines (135 loc) · 6.95 KB

README.md

File metadata and controls

186 lines (135 loc) · 6.95 KB
Raw

Soft-matter particle analysis

Small, runnable Python examples for analysing two-dimensional colloidal crystals from microscopy images and particle trajectories.

The repository covers four common tasks:

  1. detecting particles in microscopy images;
  2. calculating local area fraction and six-fold bond-orientational order;
  3. linking particle positions and correcting sample drift;
  4. calculating the angular velocity of a rotating crystal domain.

Quick start

Download the repository, open a terminal in its folder, and run:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python example/run_example.py

The first example uses a real microscopy frame for particle detection and structural analysis, plus compact synthetic trajectories for the rotation calculation. It writes its results to example/expected_output/. See example/README.md for the image details.

Example two-dimensional colloidal crystal

Paper examples

Experimental subsets are included so the paper workflows can be tried without downloading a separate archive.

Local structure - Figure 8

python paper-examples/figure8_structure/run_analysis.py

This example detects particles in four TIFF snapshots and calculates:

  • the Voronoi area of each particle;
  • local area fraction;
  • complex hexatic order parameter psi6;
  • local crystal orientation.

The main result is paper-examples/figure8_structure/expected_output/figure8_reproduction.png. Rows show the microscopy image, Voronoi local area fraction, and Voronoi local orientation. The calculations use the complete supplied right-field images; the display crop changes only the figure framing.

Angular velocity - Figure 4

python paper-examples/figure4_rotation/run_analysis.py

For each of four movies, the script:

  1. selects frames 200-1200 and sufficiently long trajectories;
  2. measures every particle relative to the fitted rotation centre;
  3. keeps particles inside the coherently rotating crystal domain;
  4. averages angular velocity along each particle trajectory;
  5. reports the median particle value and particle-to-particle standard deviation.

Results are written to:

  • paper-examples/figure4_rotation/expected_output/angular_velocity.csv
  • paper-examples/figure4_rotation/expected_output/angular_velocity.png

Angular velocity is reported in degrees per minute, matching Figure 4 of the paper. Error bars describe variation among particles in one movie, not variation between repeated experiments.

Repository layout

code/                    Reusable analysis functions
example/                 Real image and synthetic trajectory starter example
paper-examples/
  figure4_rotation/      Four compact trajectory datasets
  figure8_structure/     Four microscopy snapshots
tests/                   Automated correctness checks
Module Main purpose
particle_detection.py Particle localisation with Trackpy
structural_analysis.py Voronoi cells, local area fraction, psi6, and orientation
trajectory_tracking.py Trajectory linking, filtering, and drift correction
rotational_analysis.py Rotation-centre estimation and angular velocity

The scripts in example/ and paper-examples/ are the best starting points. The modules in code/ contain the underlying reusable functions.

Using your own data

Copy an example parameter file and change only values that are known for your experiment. Do not reuse this microscope's calibration blindly.

Important image parameters:

  • pixel_size_x_um, pixel_size_y_um: calibrated micrometres per pixel;
  • particle_diameter_um: physical particle diameter;
  • diameter_px, separation_px, minmass: Trackpy detection settings.

Important movie parameters:

  • frame_rate_hz: acquisition frame rate;
  • analysis_start_frame, analysis_end_frame: analysed time window;
  • rotation_center_um: centre fitted for that movie;
  • radial limits: region safely inside the rotating grain boundary.

Figure 4 panels c-e use 7 µm radial bins labelled 0, 7, 14, and 21 µm, corresponding to approximately radius < 28 µm. Panel f uses the two inner bins, approximately radius < 14 µm, because its coherently rotating grain is smaller. For another experiment, inspect the images or trajectories first and choose the largest complete bin that stays inside the coherently rotating crystal throughout the analysed interval. Record the choice before calculating velocity; do not adjust the radius to obtain a preferred result.

Input trajectory tables for rotational analysis require these columns:

Column Meaning
frame Frame number
particle Persistent particle identifier
x_um_post_drift Drift-corrected x coordinate in micrometres
y_um_post_drift Drift-corrected y coordinate in micrometres

Scientific notes

Structural geometry is calculated in physical micrometre coordinates. Local area fraction is particle cross-sectional area divided by clipped Voronoi-cell area. Raw and smoothed values are retained in separate columns. For Figure 8, the particle diameter is 2.84 µm and smoothing covers two Delaunay-neighbour shells. The optional 30-degree orientation offset is used only for display and does not alter the scientific orientation.

The Figure 4 calculation preserves the operation used for the paper dataset. The module also provides compute_rotational_dynamics for new datasets; this version accounts explicitly for skipped frames through delta_time = delta_frame / frame_rate.

Testing

pytest -q

The tests cover calibration, anisotropic pixels, Voronoi clipping, structural order, drift correction, skipped frames, and the supplied paper examples.

Data use

The Apache license covers software. Experimental TIFF and Parquet files are available under the Creative Commons Attribution-NonCommercial 4.0 International license. See DATA_USE.md for the file scope and attribution request.

Citation

If this repository helps your research, please cite it using the CITATION.cff file or GitHub's Cite this repository button. When the paper DOI is available, please cite the paper as well. Particle localisation and tracking use Trackpy 0.6.4:

D. B. Allan, T. A. Caswell, N. C. Keim, C. M. van der Wel, and R. W. Verweij, soft-matter/trackpy: v0.6.4 (2024), https://doi.org/10.5281/zenodo.12708864.

Contributions

Contributions are welcome through GitHub issues and pull requests. See CONTRIBUTING.md for the short development workflow. Contributors will be credited for their work in the Git history and relevant releases.

Author and software license

The software in this release was developed and is maintained by Habib Moradi, Dullens Lab, Radboud University.

Copyright 2026 Stichting Radboud Universiteit. Software is released under the Apache License 2.0; see LICENSE and NOTICE.