Skip to content

Relabel Analysis

Relabel trajectory atom types using analyzer-derived classification signals.

This module rewrites trajectory-facing atom labels based on coordination status or related analyzer outputs while preserving framewise coordinate alignment. It is scoped to relabeling transformations and does not recompute raw dynamics.

Usage context

  • State-aware relabeling: Convert raw atom labels into context-specific labels.
  • Pipeline preparation: Produce relabeled trajectories for downstream analyses.
  • Comparative workflows: Align labeling conventions across simulation runs.

Request: TrajectoryRelabelByCoordinationRequest

Request to relabel trajectory atom labels from coordination status.

Fields

Field Type Default Help Choices
labels Optional[Mapping[int, str]] Optional status->tag mapping. Example: {-1:'UN', 0:'OK', 1:'OV'}.
mode str global Relabeling mode. 'global' uses only status tags, 'by_type' appends tags to original atom types. global, by_type
keep_coord_original bool False In by_type mode, keep original label for coordinated atoms (status=0). True, False
frames Optional[Sequence[int]] Optional frame indices to relabel. Example: [0, 10, 20].
every int 1 Stride for selected frames. Example: every=5.
valences Optional[Mapping[str, float]] Optional element->valence map for coordination classification. Example: {'C': 4, 'O': 2, 'H': 1}.
threshold float 0.9 Absolute tolerance used to classify under/coord/over status. Example: 0.9.
require_all_valences bool True If true, fail when any selected atom type has no valence mapping. True, False

Examples

req = TrajectoryRelabelByCoordinationRequest(
    mode="by_type",
    labels={-1: "UN", 0: "OK", 1: "OV"},
    frames=[0, 10, 20],
)

Sample output: TrajectoryRelabelByCoordinationRequest(...) Meaning: The request configures coordination-driven relabeling on sampled frames.

Task: TrajectoryRelabelByCoordinationTask

Build a relabeled trajectory from coordination-status output.

Build default presentations for relabel-by-coordination outputs.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result TrajectoryRelabelByCoordinationResult Analysis result object for the executed task.
payload dict[str, Any] Serialized result payload.

Returns

Type Description
list[PresentationSpec] Table-only presentation configuration.

Examples

specs = TrajectoryRelabelByCoordinationTask.recommended_presentations(result, payload)

Sample output: [PresentationSpec(renderer="table", ...)] Meaning: The primary default representation is the coordination/relabel table.

Method: run(data: ConnectivityTrajectoryData, request: TrajectoryRelabelByCoordinationRequest, reporter=None)

Relabel trajectory atom labels using coordination-status analysis.

Computes coordination status from connectivity + valence information and applies requested relabeling mode to produce a relabeled trajectory subset aligned to selected frames.

Works on

ConnectivityTrajectoryData plus TrajectoryRelabelByCoordinationRequest

Parameters

Name Type Description
data ConnectivityTrajectoryData Bundle containing trajectory coordinates, connectivity, and optional force-field parameter data for valence lookup.
request TrajectoryRelabelByCoordinationRequest Relabeling configuration, frame sampling, and coordination options.
reporter Any, optional Optional progress callback passed through downstream operations.

Returns

Type Description
TrajectoryRelabelByCoordinationResult Result containing relabeled trajectory subset and coordination table.

Examples

req = TrajectoryRelabelByCoordinationRequest(mode="global")
result = TrajectoryRelabelByCoordinationTask().run(bundle, req)

Sample output: A result with trajectory.atom_labels and a coordination table. Meaning: Labels are transformed according to coordination status on sampled frames.

Result: TrajectoryRelabelByCoordinationResult

Relabeled trajectory generated from computed coordination status.

Fields

Field Type Default Help Choices
trajectory TrajectoryData
table pd.DataFrame
request TrajectoryRelabelByCoordinationRequest

Notes

The table usually includes columns such as frame_index, iter, atom_id, atom_type, sum_BOs, valence, delta, status, and status_label.

Examples

result = TrajectoryRelabelByCoordinationTask().run(data, req)
result.trajectory.atom_labels.shape

Sample output: (n_selected_frames, n_atoms) Meaning: Relabeled atom labels are stored per selected frame and atom.