Frame selection

FrameSelection maps PolyzyMD equilibration/window semantics to MDAnalysis AnalysisBase.run() kwargs. It supports either start/stop/step or an explicit frames selector, but not both.

Frame-selection helpers for MDAnalysis extension-layer jobs.

class polyzymd.analyses.mda.frame_selection.FrameSelection(start=None, stop=None, step=None, frames=None, equilibration=None, equilibration_start=None, equilibration_ps=None, timestep_ps=None, first_frame_time_ps=None, selected_start_time_ps=None, equilibration_time_reference=None, n_frames_total=None, warning_message=None)[source]

Bases: object

Validated MDAnalysis run() frame-selection arguments.

FrameSelection is the import-light bridge between PolyzyMD’s equilibration/window semantics and MDAnalysis AnalysisBase.run keyword arguments. Explicit frames selectors are mutually exclusive with start, stop, and step because MDAnalysis treats them as separate selection modes.

Parameters:

  • start (int | None, optional) – Inclusive start frame passed to run(start=...).

  • stop (int | None, optional) – Exclusive stop frame passed to run(stop=...).

  • step (int | None, optional) – Frame stride passed to run(step=...).

  • frames (Any, optional) – Explicit frame indices or boolean mask passed to run(frames=...).

  • equilibration (str | None, optional) – Original equilibration setting used to derive this selection.

  • equilibration_start (int | None, optional) – Start frame implied by equilibration alone.

  • equilibration_ps (float | None, optional) – Equilibration time converted to picoseconds.

  • timestep_ps (float | None, optional) – Trajectory timestep in picoseconds.

  • first_frame_time_ps (float | None, optional) – Absolute MDAnalysis timestamp of loaded frame 0 in picoseconds, when available.

  • selected_start_time_ps (float | None, optional) – Timestamp of the selected start frame in the active time reference.

  • equilibration_time_reference (str | None, optional) – Time reference used to interpret equilibration.

  • n_frames_total (int | None, optional) – Total trajectory frame count when known.

  • warning_message (str | None, optional) – Non-fatal warning from equilibration/window validation.

start: int | None = None
stop: int | None = None
step: int | None = None
frames: Any = None
equilibration: str | None = None
equilibration_start: int | None = None
equilibration_ps: float | None = None
timestep_ps: float | None = None
first_frame_time_ps: float | None = None
selected_start_time_ps: float | None = None
equilibration_time_reference: str | None = None
n_frames_total: int | None = None
warning_message: str | None = None
n_frames_selected: int | None = None
__post_init__()[source]

Validate mutually exclusive MDAnalysis frame-selection modes.

Raises:

ValueError – Raised when the selector would produce invalid MDAnalysis run keyword arguments or an empty known frame selection.

run_kwargs()[source]

Return keyword arguments for MDAnalysis AnalysisBase.run.

Returns:

frames alone when explicit frames are set, otherwise the non-None start, stop, and step values.

Return type:

MDARunKwargs

classmethod from_trajectory_window(window)[source]

Build a frame selection from a resolved PolyzyMD trajectory window.

Parameters:

window (TrajectoryWindow) – Existing validated shared trajectory window.

Returns:

Selection that forwards the same start, stop, and step values to MDAnalysis while preserving window provenance.

Return type:

FrameSelection

classmethod from_equilibration(*, equilibration, n_frames_total, timestep_ps, start=None, stop=None, step=1, min_frames=1, first_frame_time_ps=None)[source]

Resolve PolyzyMD equilibration/window settings to a frame selection.

Finite first-frame timestamps make equilibration absolute in MDAnalysis trajectory time; missing timestamps keep the stale loaded-frame-relative origin.

Parameters:

  • equilibration (str) – Equilibration time string such as "10ns".

  • n_frames_total (int) – Total number of trajectory frames.

  • timestep_ps (float) – Trajectory timestep in picoseconds.

  • start (int | None, optional) – Absolute start frame. When None, equilibration determines the start frame.

  • stop (int | None, optional) – Absolute exclusive stop frame. When None, the trajectory end is used.

  • step (int, optional) – Frame stride, by default 1.

  • min_frames (int, optional) – Minimum required number of selected frames, by default 1.

  • first_frame_time_ps (float | None, optional) – Absolute MDAnalysis timestamp of loaded frame 0 in picoseconds.

Returns:

Validated selection suitable for MDAnalysis run().

Return type:

FrameSelection

__init__(start=None, stop=None, step=None, frames=None, equilibration=None, equilibration_start=None, equilibration_ps=None, timestep_ps=None, first_frame_time_ps=None, selected_start_time_ps=None, equilibration_time_reference=None, n_frames_total=None, warning_message=None)