def related_linkage_states_and_scoped_variables(self, state_ids, scoped_variables):
        """ TODO: document
        """

        # find all related transitions
        related_transitions = {'enclosed': [], 'ingoing': [], 'outgoing': []}
        for t in self.transitions.values():
            # check if internal of new hierarchy state
            if t.from_state in state_ids and t.to_state in state_ids:
                related_transitions['enclosed'].append(t)
            elif t.to_state in state_ids:
                related_transitions['ingoing'].append(t)
            elif t.from_state in state_ids:
                related_transitions['outgoing'].append(t)

        # find all related data flows
        related_data_flows = {'enclosed': [], 'ingoing': [], 'outgoing': []}
        for df in self.data_flows.values():
            # check if internal of new hierarchy state
            if df.from_state in state_ids and df.to_state in state_ids or \
                    df.from_state in state_ids and self.state_id == df.to_state and df.to_key in scoped_variables or \
                    self.state_id == df.from_state and df.from_key in scoped_variables and df.to_state in state_ids:
                related_data_flows['enclosed'].append(df)
            elif df.to_state in state_ids or \
                    self.state_id == df.to_state and df.to_key in scoped_variables:
                related_data_flows['ingoing'].append(df)
            elif df.from_state in state_ids or \
                    self.state_id == df.from_state and df.from_key in scoped_variables:
                related_data_flows['outgoing'].append(df)

        return related_transitions, related_data_flows