docs: def reindex(prices, index, limit):
      """
      Reindex a pd.Series of prices such that when instrument level returns are
      calculated they are compatible with a pd.MultiIndex of instrument weights
      in calc_rets(). This amount to reindexing the series by an augmented
      version of index which includes the preceding date for the first appearance
      of each instrument. Fill forward missing values with previous price up to
      some limit.
  
      Parameters
      ----------
      prices: pandas.Series
          A Series of instrument prices with a MultiIndex where the top level is
          pandas.Timestamps and the second level is instrument names.
      index: pandas.MultiIndex
          A MultiIndex where the top level contains pandas.Timestamps and the
          second level is instrument names.
      limt: int
          Number of periods to fill prices forward.
  
      Returns
      -------
      A pandas.Series of reindexed prices where the top level is
      pandas.Timestamps and the second level is instrument names.
  
      See also: calc_rets()
  
      Example
      -------
      >>> import pandas as pd
      >>> from pandas import Timestamp as TS
      >>> import mapping.util as util
      >>> idx = pd.MultiIndex.from_tuples([(TS('2015-01-04'), 'CLF5'),
      ...                                  (TS('2015-01-05'), 'CLF5'),
      ...                                  (TS('2015-01-05'), 'CLH5'),
      ...                                  (TS('2015-01-06'), 'CLF5'),
      ...                                  (TS('2015-01-06'), 'CLH5'),
      ...                                  (TS('2015-01-07'), 'CLF5'),
      ...                                  (TS('2015-01-07'), 'CLH5')])
      >>> prices = pd.Series([100.12, 101.50, 102.51, 103.51, 102.73, 102.15,
      ...                     104.37], index=idx)
      >>> widx = pd.MultiIndex.from_tuples([(TS('2015-01-05'), 'CLF5'),
      ...                                   (TS('2015-01-05'), 'CLH5'),
      ...                                   (TS('2015-01-07'), 'CLF5'),
      ...                                   (TS('2015-01-07'), 'CLH5')])
      >>> util.reindex(prices, widx, limit=0)
      """
      if not index.is_unique:
          raise ValueError("'index' must be unique")
  
      index = index.sort_values()
      index.names = ["date", "instrument"]
      price_dts = prices.sort_index().index.unique(level=0)
      index_dts = index.unique(level=0)
  
      mask = price_dts < index_dts[0]
      leading_price_dts = price_dts[mask]
      if len(leading_price_dts) == 0:
          raise ValueError("'prices' must have a date preceding first date in "
                           "'index'")
      prev_dts = index_dts.tolist()
      prev_dts.insert(0, leading_price_dts[-1])
      # avoid just lagging to preserve the calendar
      previous_date = dict(zip(index_dts, prev_dts))
  
      first_instr = index.to_frame(index=False)
      first_instr = (
          first_instr.drop_duplicates(subset=["instrument"], keep="first")
      )
      first_instr.loc[:, "prev_date"] = (
          first_instr.loc[:, "date"].apply(lambda x: previous_date[x])
      )
      additional_indices = pd.MultiIndex.from_tuples(
          first_instr.loc[:, ["prev_date", "instrument"]].values.tolist()
      )
  
      augmented_index = index.union(additional_indices).sort_values()
      prices = prices.reindex(augmented_index)
      if limit != 0:
          prices = prices.groupby(level=1).fillna(method="ffill", limit=limit)
      return prices