shnitsel.analyze.hops ===================== .. py:module:: shnitsel.analyze.hops Attributes ---------- .. autoapisummary:: shnitsel.analyze.hops.TrajectoryOrFrames Functions --------- .. autoapisummary:: shnitsel.analyze.hops.hops_mask_from_active_state shnitsel.analyze.hops.hops shnitsel.analyze.hops.filter_data_at_hops shnitsel.analyze.hops.focus_hops shnitsel.analyze.hops.assign_hop_time Module Contents --------------- .. py:data:: TrajectoryOrFrames .. py:function:: 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. :param active_state_source: A potential source for extracting the active state along a leading dimension and the leading dimension name. :type active_state_source: xr.Dataset | Trajectory | Frames | xr.DataArray | TreeNode[Any, xr.Dataset | Trajectory | Frames | xr.DataArray] :param hop_type_selection: A state selection holding state transitions that should be used in hop filtering. :type hop_type_selection: StateSelection | StateSelectionDescriptor, optional :param dim: The dimension along which the hops should be detected. For most cases, this should be `frame` or `time`. :type dim: DimName, optional, :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 :rtype: xr.DataArray | TreeNode[Any, xr.DataArray] :raises ValueError: If an unsupported input type was provided .. py:function:: hops(frames, hop_type_selection = None) Select hops :param frames: An Xarray object (Dataset or DataArray) with a ``frames`` dimension :param hop_type_selection: 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 .. py:function:: 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. :param active_state_and_data_source: A source for extracting the active state along a leading dimension and the leading dimension name as well as to filter the data from. :type active_state_and_data_source: xr.Dataset | xr.DataArray | DataSeries | TreeNode[Any, xr.Dataset | DataSeries]| TreeNode[Any, xr.DataArray] :param hop_type_selection: A state selection holding state transitions that should be used in hop filtering. :type hop_type_selection: StateSelection, optional :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 :rtype: DataSeries | xr.DataArray | TreeNode[Any, DataSeries] | TreeNode[Any, xr.DataArray] .. py:function:: focus_hops(frames, hop_types = None, window = None) For each hop, create a copy of its trajectory centered on the hop; align these :param frames: An Xarray object (Dataset or DataArray) with a ``frames`` dimension :param hop_types: Types of hops to include See like-named parameter in :py:func:`shnitsel.analyze.hops.hops` :param window: 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 .. py:function:: assign_hop_time(frames, hop_types = None, which = 'last') Assign a ``hop_time`` coordinate along the ``frames`` axis giving times relative to hops :param frames: An Xarray object (Dataset or DataArray) with a ``frames`` dimension :param hop_types: Types of hops to include See like-named parameter in :py:func:`shnitsel.analyze.hops.hops` :param which: 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*