docs: def create_long_form_mappings(long_form,
                                obs_id_col,
                                alt_id_col,
                                choice_col=None,
                                nest_spec=None,
                                mix_id_col=None,
                                dense=False):
      """
      Parameters
      ----------
      long_form : pandas dataframe.
          Contains one row for each available alternative for each observation.
      obs_id_col : str.
          Denotes the column in `long_form` which contains the choice situation
          observation ID values for each row of `long_form`. Note each value in
          this column must be unique (i.e., individuals with repeat observations
          have unique `obs_id_col` values for each choice situation, and
          `obs_id_col` values are unique across individuals).
      alt_id_col : str.
          Denotes the column in long_form which contains the alternative ID
          values for each row of `long_form`.
      choice_col : str, optional.
          Denotes the column in long_form which contains a one if the alternative
          pertaining to the given row was the observed outcome for the
          observation pertaining to the given row and a zero otherwise.
          Default == None.
      nest_spec : OrderedDict, or None, optional.
          Keys are strings that define the name of the nests. Values are lists of
          alternative ids, denoting which alternatives belong to which nests.
          Each alternative id must only be associated with a single nest!
          Default == None.
      mix_id_col : str, optional.
          Denotes the column in long_form that contains the identification values
          used to denote the units of observation over which parameters are
          randomly distributed.
      dense : bool, optional.
          Determines whether or not scipy sparse matrices will be returned or
          dense numpy arrays.
  
      Returns
      -------
      mapping_dict : OrderedDict.
          Keys will be `["rows_to_obs", "rows_to_alts", "chosen_row_to_obs",
          "rows_to_nests"]`. If `choice_col` is None, then the value for
          `chosen_row_to_obs` will be None. Likewise, if `nest_spec` is None,
          then the value for `rows_to_nests` will be None. The value for
          "rows_to_obs" will map the rows of the `long_form` to the unique
          observations (on the columns) in their order of appearance. The value
          for `rows_to_alts` will map the rows of the `long_form` to the unique
          alternatives which are possible in the dataset (on the columns), in
          sorted order--not order of appearance. The value for
          `chosen_row_to_obs`, if not None, will map the rows of the `long_form`
          that contain the chosen alternatives to the specific observations those
          rows are associated with (denoted by the columns). The value of
          `rows_to_nests`, if not None, will map the rows of the `long_form` to
          the nest (denoted by the column) that contains the row's alternative.
          If `dense==True`, the returned values will be dense numpy arrays.
          Otherwise, the returned values will be scipy sparse arrays.
      """
      # Get the id_values from the long_form dataframe
      obs_id_values = long_form[obs_id_col].values
      alt_id_values = long_form[alt_id_col].values
  
      # Create a matrix with the same number of rows as long_form but a single
      # column for each of the unique IDs. This matrix will associate each row
      # as belonging to a particular observation using a one and using a zero to
      # show non-association.
      rows_to_obs = create_sparse_mapping(obs_id_values)
  
      # Determine all of the unique alternative IDs
      all_alternatives = np.sort(np.unique(alt_id_values))
  
      # Create a matrix with the same number of rows as long_form but a single
      # column for each of the unique alternatives. This matrix will associate
      # each row as belonging to a particular alternative using a one and using
      # a zero to show non-association.
      rows_to_alts = create_sparse_mapping(alt_id_values,
                                           unique_ids=all_alternatives)
  
      if choice_col is not None:
          # Create a matrix to associate each row with the same number of
          # rows as long_form but a 1 only if that row corresponds to an
          # alternative that a given observation (denoted by the columns)
          # chose.
          chosen_row_to_obs = csr_matrix(rows_to_obs.multiply(
                                  long_form[choice_col].values[:, None]))
      else:
          chosen_row_to_obs = None
  
      if nest_spec is not None:
          # Determine how many nests there are
          num_nests = len(nest_spec)
          # Create a mapping between the alternative ids and their nests
          alt_id_to_nest_name = {}
          for key in nest_spec:
              for element in nest_spec[key]:
                  alt_id_to_nest_name[element] = key
  
          # Create a mapping between nest names and nest ids
          nest_ids = np.arange(1, num_nests + 1)
          nest_name_to_nest_id = dict(zip(nest_spec.keys(), nest_ids))
  
          # Create an array of the nest ids of each row
          nest_id_vec = np.array([nest_name_to_nest_id[alt_id_to_nest_name[x]]
                                  for x in alt_id_values])
  
          # Create the mapping matrix between each row and the nests
          rows_to_nests = create_sparse_mapping(nest_id_vec, unique_ids=nest_ids)
  
      else:
          rows_to_nests = None
  
      if mix_id_col is not None:
          # Create a mapping matrix between each row and each 'mixing unit'
          mix_id_array = long_form[mix_id_col].values
          rows_to_mixers = create_sparse_mapping(mix_id_array)
  
      else:
          rows_to_mixers = None
  
      # Create the dictionary of mapping matrices that is to be returned
      mapping_dict = OrderedDict()
      mapping_dict["rows_to_obs"] = rows_to_obs
      mapping_dict["rows_to_alts"] = rows_to_alts
      mapping_dict["chosen_row_to_obs"] = chosen_row_to_obs
      mapping_dict["rows_to_nests"] = rows_to_nests
      mapping_dict["rows_to_mixers"] = rows_to_mixers
  
      # Return the dictionary of mapping matrices.
      # If desired, convert the mapping matrices to dense matrices
      if dense:
          for key in mapping_dict:
              if mapping_dict[key] is not None:
                  mapping_dict[key] = mapping_dict[key].A
  
      return mapping_dict