docs: def choice(key: str, index: Index, choices: Array, p: Array=None, index_map: IndexMap=None) -> pd.Series:
      """Decides between a weighted or unweighted set of choices.
  
      Given a a set of choices with or without corresponding weights,
      returns an indexed set of decisions from those choices. This is
      simply a vectorized way to make decisions with some book-keeping.
  
      Parameters
      ----------
      key :
          A string used to create a seed for the random number generation.
      index : `pandas.Index`
          An index whose length is the number of random draws made
          and which indexes the returned `pandas.Series`.
      choices :
          A set of options to choose from.
      p :
          The relative weights of the choices.  Can be either a 1-d array of
          the same length as `choices` or a 2-d array with `len(index)` rows
          and `len(choices)` columns.  In the 1-d case, the same set of weights
          are used to decide among the choices for every item in the `index`.
          In the 2-d case, each row in `p` contains a separate set of weights
          for every item in the `index`.
      index_map :
          A mapping between the provided index (which may contain ints, floats,
          datetimes or any arbitrary combination of them) and an integer index
          into the random number array.
  
      Returns
      -------
      pd.Series
          An indexed set of decisions from among the available `choices`.
  
      Raises
      ------
      RandomnessError
          If any row in `p` contains `RESIDUAL_CHOICE` and the remaining
          weights in the row are not normalized or any row of `p` contains
          more than one reference to `RESIDUAL_CHOICE`.
      """
      # Convert p to normalized probabilities broadcasted over index.
      p = _set_residual_probability(_normalize_shape(p, index)) if p is not None else np.ones((len(index), len(choices)))
      p = p/p.sum(axis=1, keepdims=True)
  
      draw = random(key, index, index_map)
  
      p_bins = np.cumsum(p, axis=1)
      # Use the random draw to make a choice for every row in index.
      choice_index = (draw.values[np.newaxis].T > p_bins).sum(axis=1)
  
      return pd.Series(np.array(choices)[choice_index], index=index)