Skip to content

Molecular Analysis Analysis

Provide engine-agnostic molecular-population analyzer tasks.

This module derives dominant species, molecule lifetimes, and largest-molecule summaries from molecular analysis datasets. It is scoped to population-level molecular metrics and not to per-bond event detection.

Usage context

  • Species tracking: Identify dominant molecular formulas over selected frames.
  • Lifetime studies: Measure persistence of molecular species through time.
  • Composition summaries: Extract largest-molecule mass/composition diagnostics.

Request: DominantSpeciesRequest

Request payload for dominant-species extraction.

This request configures frame sampling and ranking criteria used to keep the most frequent species per sampled iteration.

Fields

Field Type Default Help Choices
frames Optional[Sequence[int]] Optional frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames. 1, 2, 5, 10
top_n int 1 Number of dominant species retained per sampled frame/iteration. 1, 3, 5, 10
min_freq float 0.0 Minimum species frequency threshold used before ranking. 0.0, 1.0, 2.0

Examples

request = DominantSpeciesRequest(frames=[0, 10, 20], every=1, top_n=3, min_freq=1.0)

The request keeps up to 3 dominant species for each selected frame.

Task: DominantSpeciesTask

Return the dominant molecular species per selected iteration.

Recommend table and species-frequency plot views.

Returns a table presentation by default and adds frequency-vs-iteration plotting when required fields exist in serialized rows.

Works on Analyzer task output for get_dominant_species.

Parameters

Name Type Description
_result DominantSpeciesResult Typed analyzer result instance (unused by current logic).
payload dict[str, Any] Serialized payload expected to include table rows.

Returns

Type Description
list[PresentationSpec] Recommended renderer specifications.

Examples

specs = DominantSpeciesTask.recommended_presentations(
    _result,
    {"table": [{"iter": 10, "molecular_formula": "H2O", "freq": 4.0}]},
)

The returned list includes a table and a grouped frequency plot.

Method: run(data: MolecularAnalysisData, request: DominantSpeciesRequest, reporter=None)

Run dominant-species ranking on sampled molecular-analysis frames.

Filters molecular species to sampled iterations, applies frequency thresholds, ranks species per iteration, and returns top-N rows.

Works on MolecularAnalysisData.

Parameters

Name Type Description
data MolecularAnalysisData Parsed molecular analysis dataset containing species frequencies.
request DominantSpeciesRequest Sampling and ranking configuration.
reporter Any, optional Progress callback accepted by analyzer tasks.

Returns

Type Description
DominantSpeciesResult Result containing ranked dominant species rows.

Examples

result = DominantSpeciesTask().run(
    data,
    DominantSpeciesRequest(top_n=3, min_freq=1.0),
)

result.table contains up to 3 ranked species per sampled iteration.

Result: DominantSpeciesResult

Result payload for dominant-species analysis.

The analyzer returns ranked species rows per sampled iteration, including frequency and molecular mass values used in ranking.

Fields

Field Type Default Help Choices
table pd.DataFrame
request DominantSpeciesRequest

Examples

row = {
    "frame_index": 10,
    "iter": 1000,
    "rank": 1,
    "molecular_formula": "H2O",
    "freq": 24.0,
    "molecular_mass": 18.015,
}

The row represents the top-ranked species at one sampled iteration.

Request: MoleculeLifetimeRequest

Request payload for molecule lifetime segmentation.

This request selects formulas, frame sampling, and the activity threshold used to detect contiguous lifetime segments.

Fields

Field Type Default Help Choices
molecules Optional[Sequence[str]] Optional molecular formulas to track (for example ['H2O', 'OH']). Empty means all formulas. H2O, OH, CO2
frames Optional[Sequence[int]] Optional frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames. 1, 2, 5, 10
min_freq float 1.0 Minimum frequency threshold for a species to be considered active. 0.0, 1.0, 2.0

Examples

request = MoleculeLifetimeRequest(molecules=["H2O", "OH"], every=5, min_freq=1.0)

The request tracks lifetime segments for selected formulas at stride 5.

Task: MoleculeLifetimeTask

Compute active lifetimes and birth/death events for molecular species.

Recommend table and lifetime-segment plot views.

Returns a table presentation and adds a lifetime length plot when required segment fields are present in serialized rows.

Works on Analyzer task output for get_molecule_lifetime.

Parameters

Name Type Description
_result MoleculeLifetimeResult Typed analyzer result instance (unused by current logic).
payload dict[str, Any] Serialized payload expected to include table rows.

Returns

Type Description
list[PresentationSpec] Recommended presentation specifications.

Examples

specs = MoleculeLifetimeTask.recommended_presentations(
    _result,
    {"table": [{"start_iter": 10, "molecular_formula": "OH", "lifetime_segment_sampled_step_count": 3}]},
)

The returned list includes a table and a lifetime-length plot.

Method: run(data: MolecularAnalysisData, request: MoleculeLifetimeRequest, reporter=None)

Run molecule lifetime segmentation on sampled species frequencies.

Samples iterations, tracks per-formula active periods above threshold, and returns contiguous segment statistics for each tracked formula.

Works on MolecularAnalysisData.

Parameters

Name Type Description
data MolecularAnalysisData Parsed molecular analysis dataset containing frequency time series.
request MoleculeLifetimeRequest Formula selection, sampling, and activity-threshold configuration.
reporter Any, optional Progress callback accepted by analyzer tasks.

Returns

Type Description
MoleculeLifetimeResult Result containing lifetime segment rows per molecular formula.

Examples

result = MoleculeLifetimeTask().run(
    data,
    MoleculeLifetimeRequest(min_freq=1.0),
)

result.table lists active segments with start/end iteration bounds.

Result: MoleculeLifetimeResult

Result payload for molecule lifetime analysis.

The analyzer returns contiguous active segments for each tracked molecular formula, including segment bounds and summary frequency statistics.

Fields

Field Type Default Help Choices
table pd.DataFrame
request MoleculeLifetimeRequest

Examples

row = {
    "molecular_formula": "OH",
    "lifetime_segment_id": 1,
    "start_iter": 10,
    "end_iter": 30,
    "lifetime_segment_sampled_step_count": 3,
    "peak_freq": 5.0,
    "mean_freq": 3.3333333333,
}

The sample row captures one contiguous active interval for OH.

Request: LargestMoleculeByMassRequest

Request payload for largest-molecule-by-mass extraction.

This request configures frame sampling used to pick the heaviest species per sampled iteration.

Fields

Field Type Default Help Choices
frames Optional[Sequence[int]] Optional frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames. Example: every=5 evaluates frames 0,5,10,... 1, 2, 5, 10

Examples

request = LargestMoleculeByMassRequest(frames=[0, 5, 10], every=1)

The request evaluates the heaviest species on selected frames.

Task: LargestMoleculeByMassTask

Return the heaviest individual molecular species per selected iteration.

Recommend table and mass-vs-iteration plot views.

Returns a table presentation and adds a molecular-mass trend plot when required fields are present in serialized rows.

Works on Analyzer task output for get_largest_molecule_by_mass.

Parameters

Name Type Description
_result LargestMoleculeByMassResult Typed analyzer result instance (unused by current logic).
payload dict[str, Any] Serialized payload expected to include table rows.

Returns

Type Description
list[PresentationSpec] Recommended presentation specifications.

Examples

specs = LargestMoleculeByMassTask.recommended_presentations(
    _result,
    {"table": [{"iter": 100, "molecular_formula": "Al2O3", "molecular_mass": 101.96}]},
)

The output includes a table and a mass trend plot.

Method: run(data: MolecularAnalysisData, request: LargestMoleculeByMassRequest, reporter=None)

Run largest-molecule-by-mass selection on sampled iterations.

Samples iterations, filters molecular rows, and selects the heaviest species at each sampled iteration.

Works on MolecularAnalysisData.

Parameters

Name Type Description
data MolecularAnalysisData Parsed molecular analysis dataset.
request LargestMoleculeByMassRequest Sampling configuration for iteration selection.
reporter Any, optional Progress callback accepted by analyzer tasks.

Returns

Type Description
LargestMoleculeByMassResult Result containing one heaviest-species row per sampled iteration.

Examples

result = LargestMoleculeByMassTask().run(
    data,
    LargestMoleculeByMassRequest(every=2),
)

result.table contains heaviest species rows for sampled iterations.

Result: LargestMoleculeByMassResult

Result payload for largest-molecule-by-mass analysis.

The analyzer returns one selected heaviest species row per sampled iteration with associated frequency and molecular mass.

Fields

Field Type Default Help Choices
table pd.DataFrame
request LargestMoleculeByMassRequest

Examples

row = {
    "frame_index": 20,
    "iter": 100,
    "molecular_formula": "Al2O3",
    "freq": 3.0,
    "molecular_mass": 101.96,
}

The row indicates the heaviest species at one sampled iteration.

Request: LargestMoleculeCompositionRequest

Request payload for largest-molecule composition expansion.

This request controls frame sampling used before decomposing each selected heaviest formula into per-element counts.

Fields

Field Type Default Help Choices
frames Optional[Sequence[int]] Optional frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames. Example: every=5 evaluates frames 0,5,10,... 1, 2, 5, 10

Examples

request = LargestMoleculeCompositionRequest(every=5)

The request expands composition on every fifth sampled frame.

Task: LargestMoleculeCompositionTask

Return per-element composition of the heaviest molecule per selected iteration.

Recommend table and element-count plot views.

Returns a table by default and adds an element-count trend plot when required fields are present in serialized rows.

Works on Analyzer task output for get_largest_molecule_composition.

Parameters

Name Type Description
_result LargestMoleculeCompositionResult Typed analyzer result instance (unused by current logic).
payload dict[str, Any] Serialized payload expected to include table rows.

Returns

Type Description
list[PresentationSpec] Recommended presentation specifications.

Examples

specs = LargestMoleculeCompositionTask.recommended_presentations(
    _result,
    {"table": [{"iter": 100, "element": "O", "count": 3}]},
)

The returned list includes a table and grouped element-count plot.

Method: run(data: MolecularAnalysisData, request: LargestMoleculeCompositionRequest, reporter=None)

Run largest-molecule composition expansion from sampled iterations.

Reuses largest-molecule-by-mass selection, parses selected formulas into element/count pairs, and emits long-form composition rows.

Works on MolecularAnalysisData.

Parameters

Name Type Description
data MolecularAnalysisData Parsed molecular analysis dataset.
request LargestMoleculeCompositionRequest Sampling configuration for iteration selection.
reporter Any, optional Progress callback accepted by analyzer tasks.

Returns

Type Description
LargestMoleculeCompositionResult Result containing long-form element composition rows.

Examples

result = LargestMoleculeCompositionTask().run(
    data,
    LargestMoleculeCompositionRequest(frames=[0, 1, 2]),
)

result.table contains one row per element per sampled iteration.

Result: LargestMoleculeCompositionResult

Result payload for largest-molecule composition analysis.

The analyzer expands each selected largest molecular formula into element-count rows per sampled iteration.

Fields

Field Type Default Help Choices
table pd.DataFrame
request LargestMoleculeCompositionRequest

Examples

rows = [
    {"frame_index": 20, "iter": 100, "element": "Al", "count": 2},
    {"frame_index": 20, "iter": 100, "element": "O", "count": 3},
]

The sample rows represent composition for Al2O3 at one iteration.