playnano.analysis.utils.particles module

Particle-based postprocessing helpers.

These functions take the raw outputs of feature detection and particle tracking modules and turn them into tabular data, plots, and CSV/HDF5 exports.

playnano.analysis.utils.particles.export_particle_csv(df: DataFrame, out_path: Path) → None[source]

Write the flattened track DataFrame to CSV.

Parameters:

  • df (pandas.DataFrame)

  • out_path (Path) – Path to write the .csv file (will create parent dirs).

playnano.analysis.utils.particles.flatten_particle_features(grouping_output: Mapping[str, Any], detection_output: Mapping[str, Any], *, object_key: str | None = None, object_id_field: str = 'cluster_id', frame_key: str = 'frames', index_key: str = 'point_indices') → DataFrame[source]

Build a DataFrame linking each grouping analysis results to detected features.

Each object (e.g. cluster or track) is linked to its corresponding detected feature metadata using (frame index, point index) pairs to locate features in the output of a feature detection step and merges metadata into one flattened table.

Parameters:

  • grouping_output (dict) – Dictionary from a grouping module (e.g. clustering or tracking). Must contain a list of group objects under the object_key, where each object has lists of frames and point_indices.

  • detection_output (dict) – Dictionary from a detection module (e.g. feature_detection), which must contain the key ‘features_per_frame’: a list of feature dicts per frame.

  • object_key (str, optional) – Key in grouping_output pointing to the list of group objects. Default is “clusters”.

  • object_id_field (str, optional) – Column name to use in the output DataFrame to identify the group, e.g., “cluster_id” or “track_id”. Default is “cluster_id”.

  • frame_key (str, optional) – Key in each group object listing the frames the object appears in. Default is “frames”.

  • index_key (str, optional) – Key in each group object listing the per-frame point indices (used to match detections in features_per_frame). Default is “point_indices”.

Returns:

Flattened DataFrame linking features to group membership. Includes feature metadata and: - object_id_field (e.g. “cluster_id”) - frame - timestamp - label - centroid_x, centroid_y - area - mean_intensity - min_intensity - max_intensity

Return type:

pd.DataFrame

playnano.analysis.utils.particles.plot_particle_labels_3d(df: DataFrame, object_id_field: str = 'track_id', ax: Axes | None = None, save_to: Path | None = None, cmap: str = 'tab10') → Axes[source]

Plot particle ids in 3D (x, y, time), colored by object ID.

Parameters:

  • df (pandas.DataFrame) – Must contain [‘centroid_x’,’centroid_y’,’timestamp’, object_id_field]

  • object_id_field (str) – Column to use for color grouping (e.g. “track_id”, “cluster_id”)

  • ax (matplotlib Axes, optional) – A 3D Axes to draw into, or None to create a new one.

  • save_to (Path, optional) – If given, save the figure to file.

  • cmap (str) – Colormap name for particle group colors.

Returns:

ax – The 3D axes used.

Return type:

Axes