shnitsel.data.shnitsel_db.combiner_methods
==========================================

.. py:module:: shnitsel.data.shnitsel_db.combiner_methods


Attributes
----------

.. autoapisummary::

   shnitsel.data.shnitsel_db.combiner_methods._coordinate_meta_keys


Functions
---------

.. autoapisummary::

   shnitsel.data.shnitsel_db.combiner_methods._check_matching_dimensions
   shnitsel.data.shnitsel_db.combiner_methods._compare_dicts_of_values
   shnitsel.data.shnitsel_db.combiner_methods._check_matching_var_meta
   shnitsel.data.shnitsel_db.combiner_methods._merge_traj_metadata
   shnitsel.data.shnitsel_db.combiner_methods.concat_trajs
   shnitsel.data.shnitsel_db.combiner_methods.db_from_trajs
   shnitsel.data.shnitsel_db.combiner_methods.layer_trajs


Module Contents
---------------

.. py:data:: _coordinate_meta_keys
   :value: ['trajid', 'delta_t', 'max_ts', 't_max', 'completed', 'nsteps']


.. py:function:: _check_matching_dimensions(datasets, excluded_dimensions = set(), limited_dimensions = None)

   Function to check whether all/certain dimensions are equally sized.

   Excluded dimensions can be provided as a set of strings.

   :param datasets: The series of datasets to be checked for equal dimensions
   :type datasets: Iterable[Trajectory]
   :param excluded_dimensions: The set of dimension names to be excluded from the comparison. Defaults to set().
   :type excluded_dimensions: Set[str], optional
   :param limited_dimensions: Optionally set a list of dimensions to which the analysis should be limited.
   :type limited_dimensions: Set[str], optional

   :returns: True if all non-excluded (possibly limited) dimensions match in size.  False otherwise.
   :rtype: bool


.. py:function:: _compare_dicts_of_values(curr_root_a, curr_root_b, base_key = [])

   Compare two dicts and return the lists of matching and non-matching recursive keys.

   :param curr_root_a: Root of the first tree
   :type curr_root_a: Any
   :param curr_root_b: Root of the second tree
   :type curr_root_b: Any
   :param base_key: The current key associated with the root. Starts with [] for the initial call.
   :type base_key: List[str]

   :returns:

             A tuple, where the first list is the list of chains of keys of all matching sub-trees,
                         the second entry is the same but for identifying distinct sub-trees.
                         If a matching key points to a sub-tree, the entire sub-tree is identical.
   :rtype: Tuple[List[List[str]]|None, List[List[str]]|None]


.. py:function:: _check_matching_var_meta(datasets)

   Function to check if all of the variables have matching metadata.

   We do not want to merge trajectories with different metadata on variables.

   TODO: Allow for variables being denoted that we do not care for.

   :param datasets: The trajectories to compare the variable metadata for.
   :type datasets: List[Trajectory]

   :returns: True if the metadata matches on all trajectories, False otherwise
   :rtype: bool


.. py:function:: _merge_traj_metadata(datasets)

   Function to gather metadate from a set of trajectories.

   Used to combine trajectories into one aggregate Dataset.

   :param datasets: The sequence of trajctories for which metadata should be collected
   :type datasets: Iterable[Trajectory]

   :returns:

             The resulting meta information shared across all trajectories (first),
                     and then the distinct meta information (second) in a key -> Array_of_values fashion.
   :rtype: Tuple[Dict[str,Any],Dict[str,np.ndarray]]


.. py:function:: concat_trajs(datasets)

   Function to concatenate multiple trajectories along their `time` dimension.

   Will create one continuous time dimension like an extended trajectory. The concatenated dimension will be renamed `frame`

   :param datasets: Datasets representing the individual trajectories
   :type datasets: Iterable[Trajectory]

   :raises ValueError: Raised if there is conflicting input dimensions.
   :raises ValueError: Raised if there is conflicting input variable meta data.
   :raises ValueError: Raised if there is conflicting global input attributes that are relevant to the merging process.
   :raises ValueError: Raised if there are no trajectories provided to this function.

   :returns: The combined and extended trajectory with a new leading `frame` dimension
   :rtype: Trajectory


.. py:function:: db_from_trajs(datasets)

   Function to merge multiple trajectories of the same molecule into a single ShnitselDB instance.

   :param datasets: The individual loaded trajectories.
   :type datasets: Iterable[Trajectory]

   :returns: The resulting ShnitselDB structure with a ShnitselDBRoot, CompoundGroup and TrajectoryData layers.
   :rtype: ShnitselDB


.. py:function:: layer_trajs(datasets)

   Function to combine trajectories into one Dataset by creating a new dimension 'trajid' and indexing the different trajectories along that.

   Will create one new trajid dimension.

   :param datasets: Datasets representing the individual trajectories
   :type datasets: Iterable[xr.Dataset]

   :raises ValueError: Raised if there is conflicting input meta data.
   :raises ValueError: Raised if there are no trajectories provided to this function.

   :returns: The combined and extended trajectory with a new leading `trajid` dimension
   :rtype: xr.Dataset