docs: def combine_time_series(
      time_series_dict: Dict, kind: str, *, split_directions: bool = False
  ) -> DataFrame:
      """
      Combine the many time series DataFrames in the given dictionary
      into one time series DataFrame with hierarchical columns.
  
      Parameters
      ----------
      time_series_dict : dictionary
          Has the form string -> time series
      kind : string
          ``'route'`` or ``'stop'``
      split_directions : boolean
          If ``True``, then assume the original time series contains data
          separated by trip direction; otherwise, assume not.
          The separation is indicated by a suffix ``'-0'`` (direction 0)
          or ``'-1'`` (direction 1) in the route ID or stop ID column
          values.
  
      Returns
      -------
      DataFrame
          Columns are hierarchical (multi-index).
          The top level columns are the keys of the dictionary and
          the second level columns are ``'route_id'`` and
          ``'direction_id'``, if ``kind == 'route'``, or 'stop_id' and
          ``'direction_id'``, if ``kind == 'stop'``.
          If ``split_directions``, then third column is
          ``'direction_id'``; otherwise, there is no ``'direction_id'``
          column.
  
      """
      if kind not in ["stop", "route"]:
          raise ValueError("kind must be 'stop' or 'route'")
  
      names = ["indicator"]
      if kind == "stop":
          names.append("stop_id")
      else:
          names.append("route_id")
  
      if split_directions:
          names.append("direction_id")
  
      def process_index(k):
          a, b = k.rsplit("-", 1)
          return a, int(b)
  
      frames = list(time_series_dict.values())
      new_frames = []
      if split_directions:
          for f in frames:
              ft = f.T
              ft.index = pd.MultiIndex.from_tuples(
                  [process_index(k) for (k, __) in ft.iterrows()]
              )
              new_frames.append(ft.T)
      else:
          new_frames = frames
      result = pd.concat(
          new_frames, axis=1, keys=list(time_series_dict.keys()), names=names
      )
  
      return result