shnitsel.analyze.hops#

Attributes#

TrajectoryOrFrames

Functions#

hops_mask_from_active_state(…)

Generate boolean masks marking hopping points by identifying changes in the active state of provided

hops(frames[, hop_type_selection])

Select hops

filter_data_at_hops(…)

Filter data to only retain data at points where hops of selected transitions occur.

focus_hops(frames[, hop_types, window])

For each hop, create a copy of its trajectory centered on the hop; align these

assign_hop_time(frames[, hop_types, which])

Assign a hop_time coordinate along the frames axis giving times

Module Contents#

TrajectoryOrFrames#
hops_mask_from_active_state(active_state_source: xarray.Dataset | xarray.DataArray | shnitsel.data.dataset_containers.data_series.DataSeries, hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None, dim: shnitsel.core.typedefs.DimName | None = None) → xarray.DataArray#
hops_mask_from_active_state(active_state_source: shnitsel.data.tree.node.TreeNode[Any, xarray.Dataset | xarray.DataArray | shnitsel.data.dataset_containers.data_series.DataSeries], hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None, dim: shnitsel.core.typedefs.DimName | None = None) → shnitsel.data.tree.node.TreeNode[Any, xarray.DataArray]

Generate boolean masks marking hopping points by identifying changes in the active state of provided data source.

Needs to be fed either with (hierarchical) trajectory data that has active_state (astate) information or directly with the xr.DataArray holding astate information.

Parameters:

  • active_state_source (xr.Dataset | Trajectory | Frames | xr.DataArray | TreeNode[Any, xr.Dataset | Trajectory | Frames | xr.DataArray]) – A potential source for extracting the active state along a leading dimension and the leading dimension name.

  • hop_type_selection (StateSelection | StateSelectionDescriptor, optional) – A state selection holding state transitions that should be used in hop filtering.

  • dim (DimName, optional,) – The dimension along which the hops should be detected. For most cases, this should be frame or time.

Returns:

Either the flat boolean mask of leading dimension instances where a hop happens or a hierarchical structure holding such a flat mask for every original data entry in the hierarchical input data

Return type:

xr.DataArray | TreeNode[Any, xr.DataArray]

Raises:

ValueError – If an unsupported input type was provided

hops(frames, hop_type_selection=None)#

Select hops

Parameters:

  • frames – An Xarray object (Dataset or DataArray) with a frames dimension

  • hop_type_selection (shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None) – A list of pairs of states, e.g.: [(1, 2), (2, 1), (3, 1)] to select only hops between states 1 and 2 as well as from 3 to 1 (but not from 1 to 3). Alternatively, hops may be specified as a single string in the following style: '1<>2, 3->1' – this specification selects the same hops as in the previous example, with <> selecting hops in either direction and -> being one- directional.

Returns:

  • An indexed version of frames, where each entry in the

  • frames dimension represents a hop.

  • The following coordinates are added along frames –

    • tidx: the time-step index of the hop in its trajectory

    • hop_from: the active state before the hop

    • hop_to: the active state after the hop

filter_data_at_hops(active_state_and_data_source: xarray.DataArray, hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None) → xarray.DataArray#
filter_data_at_hops(active_state_and_data_source: xarray.Dataset | shnitsel.data.dataset_containers.data_series.DataSeries, hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None) → shnitsel.data.dataset_containers.data_series.DataSeries
filter_data_at_hops(active_state_and_data_source: shnitsel.data.tree.node.TreeNode[Any, xarray.Dataset | shnitsel.data.dataset_containers.data_series.DataSeries], hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None) → shnitsel.data.tree.node.TreeNode[Any, shnitsel.data.dataset_containers.data_series.DataSeries]
filter_data_at_hops(active_state_and_data_source: shnitsel.data.tree.node.TreeNode[Any, xarray.DataArray], hop_type_selection: shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None = None) → shnitsel.data.tree.node.TreeNode[Any, xarray.DataArray]

Filter data to only retain data at points where hops of selected transitions occur.

Needs to be fed either with (hierarchical) trajectory data that has active_state (astate) information or with simple (single) trajectory data with an active_state (astate) variable.

If you wish to perform arbitrary filtering, you can employ the hops_mask_from_active_state() function to just get the boolean mask of hop positions and perform the filtering yourself.

Parameters:

  • active_state_and_data_source (xr.Dataset | xr.DataArray | DataSeries | TreeNode[Any, xr.Dataset | DataSeries]| TreeNode[Any, xr.DataArray]) – A source for extracting the active state along a leading dimension and the leading dimension name as well as to filter the data from.

  • hop_type_selection (StateSelection, optional) – A state selection holding state transitions that should be used in hop filtering.

Returns:

Filtered version of the input data source, where a selection was performed to only retain data at points where a hop was happening. Each entry along the leading dimension (time or frame) represents a hop. The following coordinates are added along the leading dimension:

  • hop_from: the active state before the hop

  • hop_to: the active state after the hop

Return type:

DataSeries | xr.DataArray | TreeNode[Any, DataSeries] | TreeNode[Any, xr.DataArray]

focus_hops(frames, hop_types=None, window=None)#

For each hop, create a copy of its trajectory centered on the hop; align these

Parameters:

  • frames – An Xarray object (Dataset or DataArray) with a frames dimension

  • hop_types (list[tuple[int, int]] | None) – Types of hops to include See like-named parameter in shnitsel.analyze.hops.hops()

  • window (slice | None) – Clip the range of hop-relative times included to this slice; values are interpreted as relative times (not indices), e.g.: focus_hops(..., window=slice(-1.5, 2.5)) clips each trajectorial copy to the region between 1.5 time-units (probably fs) before the hop to 2.5 time-units after the hop.

Returns:

  • An object with hop and hop_time dimensions.

  • Each entry in hop represents a trajectory;

  • there is one trajectory per hop, so possibly more than

  • one copy of a given trajectory in the object.

  • The following coordinates are added along dimension hop_time, and do not vary

  • by hop (i.e. do not contain a hop dimension) –

    • hop_time: the trajectory time coordinate relative to the hop

    • hop_tidx: the trajectory time-step index relative to the hop

  • The following coordinates are added along dimensions hop_time and hop –

    • time: the original time coordinate relative to the start of the trajectory

    • tidx: the trajectory time-step index relative to the start of the trajectory

  • The following coordinates are added along dimension hop –

    • hop_from: the active state before the hop

    • hop_to: the active state after the hop

    • trajid: the ID of the trajectory in which the hop occurred

assign_hop_time(frames, hop_types=None, which='last')#

Assign a hop_time coordinate along the frames axis giving times relative to hops

Parameters:

  • frames – An Xarray object (Dataset or DataArray) with a frames dimension

  • hop_types (list[tuple[int, int]] | None) – Types of hops to include See like-named parameter in shnitsel.analyze.hops.hops()

  • which (Literal['first', 'last']) – Which hop to take, in case multiple hops present within a single trajectory; either ‘first’ or ‘last’ (the default)

Returns:

  • The same frames object with – –

    • the hop_time coordinate added along the frame dimension, containing all times relative to one chosen hop in each trajectory,

    • the time_at_hop coordinate added along the trajectory dimension, containing the time at which each chosen hop occurred

  • Both of these coordinates contain nan for trajectories lacking any hops of the

  • types specified