A geometry-first tutorial for time-resolved morphological analysis with PyPETANA

This paper presents a step-by-step, reproducible tutorial for PyPETANA, an open-source Python framework that enables geometry-first, time-resolved quantification of evolving morphologies from image data through direct mask extraction and multiscale boundary analysis without assuming specific growth mechanisms.

The Gist

Imagine you are watching a time-lapse video of a drop of ink spreading in water, or a bacterial colony growing on a petri dish. To the naked eye, it looks like a messy, evolving blob. But to a scientist, that blob is a story waiting to be read.

This paper introduces PyPETANA, a new software tool designed to read that story. Think of PyPETANA not as a scientist guessing why the blob is growing, but as a very precise, super-organized measuring tape and camera that never gets tired, never changes its mind, and never guesses.

Here is how it works, broken down into simple concepts:

1. The "Geometry-First" Philosophy

Most software tries to guess the rules of biology (e.g., "This cell is moving because it wants food"). PyPETANA takes a different approach. It says, "Let's just measure the shape first."

Imagine you are an art critic. Instead of asking the painter why they chose blue, you simply measure the exact area of the blue paint, the length of the brushstrokes, and how jagged the edges are. PyPETANA does exactly this. It ignores the "why" (the microscopic biology) and focuses entirely on the "what" (the geometry). This ensures that the measurements are purely about the shape, not about a theory the software might be wrong about.

2. The Workflow: From Video to Numbers

The paper describes a step-by-step recipe for turning a video into a spreadsheet of numbers:

• The Input (The Movie): You feed the software a time-lapse video (like a .mov file) or a folder of photos.
• The "Cut and Paste" (Segmentation): The software looks at each frame and draws a line around the object of interest, separating it from the background. It turns the picture into a black-and-white "mask."
  • Analogy: Imagine using a cookie cutter to trace the outline of a cookie on a piece of paper. PyPETANA does this automatically for every single frame of the video.
• The "Smart Selection" (Contour Selection): Sometimes, the software sees many shapes (like a big blob with a hole in the middle, or a few tiny specks nearby). PyPETANA uses a clever math trick to pick the main shape. It looks for the biggest shape that is also closest to the center of the image. It ignores the noise and the holes unless you specifically tell it to count the holes.
• The "Ruler" (Data Extraction): Once the shape is isolated, PyPETANA measures it:
  • Area: How much space does it take up?
  • Perimeter: How long is the edge?
  • Circularity: Is it a perfect circle, or is it a jagged, star-shaped mess? (A perfect circle gets a score of 1; a jagged shape gets a lower score).
  • Fractal Dimensions: This is the "super-measure." It asks, "How rough is the edge at different zoom levels?" It's like checking if a coastline looks rough when you look at it from a plane, or if it looks even rougher when you look at it from a boat.

3. The "Human-in-the-Loop" Safety Net

One of the biggest problems with computer analysis is that it can get confused by bad lighting or shadows. PyPETANA solves this with a Graphical User Interface (GUI).

• Analogy: Think of the GUI as a rehearsal stage. Before the software runs the full movie (which might take hours), you can pause on one frame, adjust the "cookie cutter" settings, and see if the outline looks right.
• Once you are happy with the settings on that one frame, you save them. The software then applies those exact same settings to every other frame in the video. This ensures that the software doesn't accidentally change its mind halfway through the movie, which would ruin the data.

4. Why "Reproducible" Matters

The paper emphasizes that if you give PyPETANA the same video and the same settings, it will give you the exact same numbers every single time, no matter who runs it or what computer they use.

• Analogy: Imagine a recipe for a cake. If you follow the recipe exactly, the cake should taste the same whether you bake it in New York or London. PyPETANA is like a digital recipe book that ensures every scientist gets the exact same "cake" (data) from the same "ingredients" (video).

5. What It Can Do (and What It Can't)

The paper uses this tool to analyze tumor growth and bacterial colonies.

• What it found: It successfully distinguished between "compact" tumors (smooth, round shapes) and "invasive" tumors (jagged, rough shapes that are spreading out). It showed that as invasive tumors grow, their edges get progressively rougher and more complex.
• What it doesn't do: The paper is very clear: PyPETANA does not tell you why the tumor is growing, it doesn't track individual cells, and it doesn't predict the future. It is strictly a tool for measuring the shape of things as they change over time.

Summary

PyPETANA is a geometry-first, time-resolved measuring tool. It takes a video of a growing shape, lets a human verify the outline once, and then automatically measures the size, edge length, and roughness of that shape for every second of the video. It turns messy, evolving pictures into clean, reliable data that scientists can trust and compare.

Technical Summary

Technical Summary: A Geometry-First Tutorial for Time-Resolved Morphological Analysis with PyPETANA

Problem Statement

Morphological pattern formation is a ubiquitous feature of non-equilibrium systems, ranging from bacterial colony growth to invasive tumor interfaces. While advances in microscopy and time-lapse imaging have made large image sequences accessible, a significant challenge remains in the reproducible quantification of evolving morphology. Existing workflows often prioritize endpoint characterization, segmentation, or classification, frequently relying on implicit mappings from pixel data to observables or being heavily dependent on specific preprocessing and thresholding choices. This dependence makes it difficult to disentangle genuine morphological evolution from variations introduced by parameter tuning or analysis strategies. Furthermore, many tools couple image analysis to specific biological, agent-based, or statistical growth models, limiting their applicability to systems where microscopic dynamics are unknown or difficult to parameterize.

Methodology

The paper introduces PyPETANA, an open-source Python framework designed for "geometry-first," time-resolved quantification of evolving morphology. The framework operates on the principle that morphology should be treated as a dynamical geometric object reconstructed from segmented images, maintaining a strict separation between image preprocessing and the mathematical definition of observables.

Core Architecture and Workflow

The analysis pipeline is deterministic and frame-by-frame, consisting of four primary computational stages:

1. Preprocessing: Input frames undergo optional operations to improve segmentation robustness against non-uniform illumination and noise. These include luminance-tilt correction, cropping (square or circular), contrast remapping, morphological closing, and Gaussian blurring.
2. Thresholding: Preprocessed frames are converted into binary masks using user-defined intensity thresholds. This step separates the morphology from the background.
3. Contour Selection: Using OpenCV's hierarchical retrieval (RETR_TREE), the system detects all contours. A dominant contour is selected based on a geometric weighting criterion that combines area and proximity to a reference center (the image center after cropping). This score, $S_i = A_i / (1 + d_i^2)$, stabilizes contour identity across frames. Fully enclosed interior contours (holes) are retained for optional hole-aware analysis.
4. Data Extraction:
   • Geometric Observables: Area ($A$), Perimeter ($P$), and Circularity ($C = 4\pi A/P^2$) are computed directly from the dominant contour.
   • Fractal Observables: The framework computes effective box-counting dimensions for both the filled morphology ($D_f$, mass scaling) and a finite-width boundary band ($D_b$, roughness scaling). To mitigate grid-alignment artifacts, PyPETANA employs a supersampled box-counting strategy. This involves zero-padding masks and evaluating four distinct padding placements (shifts) for each box size, averaging the results to ensure robustness.

Reproducibility and Interface

• GUI Orchestration: A Graphical User Interface (GUI) allows users to interactively select parameters and validate segmentation via real-time overlays. Crucially, the GUI acts solely as an orchestration layer; it does not perform the numerical analysis.
• Parameter Records: Users store parameter snapshots ("records") at specific key frames. For intermediate frames, parameters are linearly interpolated between these records, ensuring temporally smooth execution without adaptive parameter drift.
• Determinism: All reported observables are deterministic. A run is reproducible given the input media, the exported records.json (GUI snapshots), and the specific Zenodo-tagged code version.

Key Contributions

1. Geometry-First Framework: PyPETANA provides a measurement protocol that is agnostic to microscopic growth mechanisms. It does not infer biological rules, agent dynamics, or biochemical mechanisms, focusing instead on explicit geometric descriptors.
2. Multiscale Boundary Analysis: The implementation of supersampled box-counting for both filled regions and controlled boundary bands allows for the quantification of multiscale spatial complexity (mass scaling and roughness scaling) with reduced discretization bias.
3. Strict Separation of Concerns: The architecture enforces a clear divide between image preprocessing (GUI/validation) and the mathematical definition of observables (backend), ensuring that variations in results reflect morphological changes rather than analysis strategy shifts.
4. Reproducibility Infrastructure: The framework includes a lightweight provenance system where numerical outputs include a meta_json header, and GUI settings are stored in records.json, allowing for exact replay of analyses.

Results and Benchmarks

The paper validates the framework through a benchmark suite applied to invasive tumor morphologies:

• Benchmark B1 (Perimeter-Sensitive Descriptors): The framework successfully distinguished between compact and invasive tumor morphologies. Compact morphologies yielded complexity ratios ($\chi = P / 2\sqrt{\pi A}$) close to unity ($\approx 1.1$), while invasive morphologies yielded significantly higher values ($\approx 1.7\text{--}1.8$), consistent with reference data. This confirmed the reliability of the contour extraction and geometric measurement.
• Benchmark B2 (Boundary-Fractal Evolution): Applied to time-resolved MDA-MB-231 tumor growth data, the framework captured the progressive increase in boundary roughness. The boundary fractal dimension ($D_b$) for matrix-associated morphologies increased monotonically from $\approx 1.22$ to $\approx 1.48$ over four days. A hole-aware variant further demonstrated how interior topology influences scaling exponents, rising from $\approx 1.31$ to $\approx 1.66$.

Significance and Claims

The paper positions PyPETANA not as an inference engine for microscopic growth rules, but as a transparent, reproducible measurement protocol for evolving morphology. Its significance lies in:

• Standardization: Providing a consistent geometric description that can be compared across experiments, growth conditions, and imaging modalities without the confounding variables of model-dependent assumptions.
• Auditability: Enabling direct visual validation of segmentation, contour selection, and multiscale counting assumptions on a frame-by-frame basis through diagnostic exports.
• Applicability: While demonstrated on biological systems (bacterial colonies and tumor interfaces), the workflow is applicable to any evolving non-equilibrium interface, including diffusion-limited aggregation and interfacial instabilities.

The authors emphasize that the physical interpretation of these observables in specific biological contexts is discussed in separate works; this tutorial focuses strictly on the computational workflow and the reproducible extraction of geometric data.