docs: 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