docs: def relate_obs_ids_to_chosen_alts(obs_id_array,
                                    alt_id_array,
                                    choice_array):
      """
      Creates a dictionary that relates each unique alternative id to the set of
      observations ids that chose the given alternative.
  
      Parameters
      ----------
      obs_id_array : 1D ndarray of ints.
          Should be a long-format array of observation ids. Each element should
          correspond to the unique id of the unit of observation that corresponds
          to the given row of the long-format data. Note that each unit of
          observation may have more than one associated choice situation.
      alt_id_array : 1D ndarray of ints.
          Should be a long-format array of alternative ids. Each element should
          denote the unique id of the alternative that corresponds to the given
          row of the long format data.
      choice_array : 1D ndarray of ints.
          Each element should be either a one or a zero, indicating whether the
          alternative on the given row of the long format data was chosen or not.
  
      Returns
      -------
      chosen_alts_to_obs_ids : dict.
          Each key will be a unique value from `alt_id_array`. Each key's value
          will be a 1D ndarray that contains the sorted, unique observation ids
          of those observational units that chose the given alternative.
      """
      # Figure out which units of observation chose each alternative.
      chosen_alts_to_obs_ids = {}
  
      for alt_id in np.sort(np.unique(alt_id_array)):
          # Determine which observations chose the current alternative.
          selection_condition =\
              np.where((alt_id_array == alt_id) & (choice_array == 1))
  
          # Store the sorted, unique ids that chose the current alternative.
          chosen_alts_to_obs_ids[alt_id] =\
              np.sort(np.unique(obs_id_array[selection_condition]))
  
      # Return the desired dictionary.
      return chosen_alts_to_obs_ids