docs: def gen_subject_info_tree(subject_info_pyxb, authn_subj, include_duplicates=False):
      """Convert the flat, self referential lists in the SubjectInfo to a tree structure.
  
      Args:
          subject_info_pyxb: SubjectInfo PyXB object
  
          authn_subj: str
              The authenticated subject that becomes the root subject in the tree of
              subjects built from the SubjectInfo.
  
              Only subjects that are authenticated by a direct or indirect connection to
              this subject are included in the tree.
  
          include_duplicates:
              Include branches of the tree that contain subjects that have already been
              included via other branches.
  
              If the tree is intended for rendering, including the duplicates will
              provide a more complete view of the SubjectInfo.
  
      Returns:
          SubjectInfoNode : Tree of nodes holding information about subjects that are
          directly or indirectly connected to the authenticated subject in the root.
  
      """
  
      class State:
          """self."""
  
          pass
  
      state = State()
  
      state.subject_info_pyxb = subject_info_pyxb
      state.include_duplicates = include_duplicates
      state.visited_set = set()
      state.tree = SubjectInfoNode("Root", TYPE_NODE_TAG)
  
      _add_subject(state, state.tree, authn_subj)
      symbolic_node = state.tree.add_child("Symbolic", TYPE_NODE_TAG)
      _add_subject(state, symbolic_node, d1_common.const.SUBJECT_AUTHENTICATED)
      _trim_tree(state)
  
      return state.tree