docstr: Sampling by rolling for machine learning/deep learning models.
  
  :param lookback: int, lookback value. Default to 'auto',
         if 'auto', the mode of time series' cycle length will be taken as the lookback.
  :param horizon: int or list.
         If `horizon` is an int, we will sample `horizon` step
         continuously after the forecasting point.
         If `horizon` is a list, we will sample discretely according
         to the input list. 1 means the timestamp just after the observed data.
         specially, when `horizon` is set to 0, ground truth will be generated as None.
  :param feature_col: str or list, indicates the feature col name. Default to None,
         where we will take all available feature in rolling.
  :param target_col: str or list, indicates the target col name. Default to None,
         where we will take all target in rolling. It should be a subset of target_col
         you used to initialize the tsdataset.
  :param id_sensitive: bool.
         If `id_sensitive` is False, we will rolling on each id's sub dataframe
         and fuse the sampings.
         The shape of rolling will be
         x: (num_sample, lookback, num_feature_col + num_target_col)
         y: (num_sample, horizon + label_len, num_target_col)
         where num_sample is the summation of sample number of each dataframe.
  
         If `id_sensitive` is True, we will rolling on the wide dataframe whose
         columns are cartesian product of id_col and feature_col.
         The shape of rolling will be
         x: (num_sample, lookback, new_num_feature_col + new_num_target_col)
         y: (num_sample, horizon + label_len, new_num_target_col)
         where num_sample is the sample number of the wide dataframe,
         new_num_feature_col is the product of the number of id and the number of feature_col,
         new_num_target_col is the product of the number of id and the number of target_col.
  :param time_enc: bool.
         This parameter should be set to True only when you are using Autoformer model. With
         time_enc to be true, 2 additional numpy ndarray will be returned when you call
         `.to_numpy()`. Be sure to have a time type for dt_col if you set time_enc to True.
  :param label_len: int.
         This parameter should be set to True only when you are using Autoformer model. This
         indicates the length of overlap area of output(y) and input(x) on time axis.
  :param is_predict: bool.
         This parameter indicates if the dataset will be sampled as a prediction dataset
         (without groud truth).
  
  :return: the tsdataset instance.
  
  roll() can be called by:
  
  >>> # Here is a df example:
  >>> # id        datetime      value   "extra feature 1"   "extra feature 2"
  >>> # 00        2019-01-01    1.9     1                   2
  >>> # 01        2019-01-01    2.3     0                   9
  >>> # 00        2019-01-02    2.4     3                   4
  >>> # 01        2019-01-02    2.6     0                   2
  >>> tsdataset = TSDataset.from_pandas(df, dt_col="datetime",
  >>>                                   target_col="value", id_col="id",
  >>>                                   extra_feature_col=["extra feature 1",
  >>>                                                      "extra feature 2"])
  >>> horizon, lookback = 1, 1
  >>> tsdataset.roll(lookback=lookback, horizon=horizon, id_sensitive=False)
  >>> x, y = tsdataset.to_numpy()
  >>> print(x, y) # x = [[[1.9, 1, 2 ]], [[2.3, 0, 9 ]]] y = [[[ 2.4 ]], [[ 2.6 ]]]
  >>> print(x.shape, y.shape) # x.shape = (2, 1, 3) y.shape = (2, 1, 1)
  >>> tsdataset.roll(lookback=lookback, horizon=horizon, id_sensitive=True)
  >>> x, y = tsdataset.to_numpy()
  >>> print(x, y) # x = [[[ 1.9, 2.3, 1, 2, 0, 9 ]]] y = [[[ 2.4, 2.6]]]
  >>> print(x.shape, y.shape) # x.shape = (1, 1, 6) y.shape = (1, 1, 2)
docstr_tok: ["Sampling","by","rolling","for","machine","learning\/deep","learning","models",".",":","param","lookback",":","int",",","lookback","value",".","Default","to","'auto","'",",","if","'auto","'",",","the","mode","of","time","series","'","cycle","length","will","be","taken","as","the","lookback",".",":","param","horizon",":","int","or","list",".","If","`","horizon","`","is","an","int",",","we","will","sample","`","horizon","`","step","continuously","after","the","forecasting","point",".","If","`","horizon","`","is","a","list",",","we","will","sample","discretely","according","to","the","input","list",".","1","means","the","timestamp","just","after","the","observed","data",".","specially",",","when","`","horizon","`","is","set","to","0",",","ground","truth","will","be","generated","as","None",".",":","param","feature_col",":","str","or","list",",","indicates","the","feature","col","name",".","Default","to","None",",","where","we","will","take","all","available","feature","in","rolling",".",":","param","target_col",":","str","or","list",",","indicates","the","target","col","name",".","Default","to","None",",","where","we","will","take","all","target","in","rolling",".","It","should","be","a","subset","of","target_col","you","used","to","initialize","the","tsdataset",".",":","param","id_sensitive",":","bool",".","If","`","id_sensitive","`","is","False",",","we","will","rolling","on","each","id","'s","sub","dataframe","and","fuse","the","sampings",".","The","shape","of","rolling","will","be","x",":","(","num_sample",",","lookback",",","num_feature_col","+","num_target_col",")","y",":","(","num_sample",",","horizon","+","label_len",",","num_target_col",")","where","num_sample","is","the","summation","of","sample","number","of","each","dataframe",".","If","`","id_sensitive","`","is","True",",","we","will","rolling","on","the","wide","dataframe","whose","columns","are","cartesian","product","of","id_col","and","feature_col",".","The","shape","of","rolling","will","be","x",":","(","num_sample",",","lookback",",","new_num_feature_col","+","new_num_target_col",")","y",":","(","num_sample",",","horizon","+","label_len",",","new_num_target_col",")","where","num_sample","is","the","sample","number","of","the","wide","dataframe",",","new_num_feature_col","is","the","product","of","the","number","of","id","and","the","number","of","feature_col",",","new_num_target_col","is","the","product","of","the","number","of","id","and","the","number","of","target_col",".",":","param","time_enc",":","bool",".","This","parameter","should","be","set","to","True","only","when","you","are","using","Autoformer","model",".","With","time_enc","to","be","true",",","2","additional","numpy","ndarray","will","be","returned","when","you","call","`",".to_numpy","(",")","`",".","Be","sure","to","have","a","time","type","for","dt_col","if","you","set","time_enc","to","True",".",":","param","label_len",":","int",".","This","parameter","should","be","set","to","True","only","when","you","are","using","Autoformer","model",".","This","indicates","the","length","of","overlap","area","of","output","(","y",")","and","input","(","x",")","on","time","axis",".",":","param","is_predict",":","bool",".","This","parameter","indicates","if","the","dataset","will","be","sampled","as","a","prediction","dataset","(","without","groud","truth",")",".",":","return",":","the","tsdataset","instance",".","roll","(",")","can","be","called","by",":",">",">",">","#","Here","is","a","df","example",":",">",">",">","#","id","datetime","value","``","extra","feature","1","''","``","extra","feature","2","''",">",">",">","#","00","2019-01-01","1.9","1","2",">",">",">","#","01","2019-01-01","2.3","0","9",">",">",">","#","00","2019-01-02","2.4","3","4",">",">",">","#","01","2019-01-02","2.6","0","2",">",">",">","tsdataset","=","TSDataset.from_pandas","(","df",",","dt_col=","''","datetime","''",",",">",">",">","target_col=","''","value","''",",","id_col=","''","id","''",",",">",">",">","extra_feature_col=","[","``","extra","feature","1","''",",",">",">",">","``","extra","feature","2","''","]",")",">",">",">","horizon",",","lookback","=","1",",","1",">",">",">","tsdataset.roll","(","lookback=lookback",",","horizon=horizon",",","id_sensitive=False",")",">",">",">","x",",","y","=","tsdataset.to_numpy","(",")",">",">",">","print","(","x",",","y",")","#","x","=","[","[","[","1.9",",","1",",","2","]","]",",","[","[","2.3",",","0",",","9","]","]","]","y","=","[","[","[","2.4","]","]",",","[","[","2.6","]","]","]",">",">",">","print","(","x.shape",",","y.shape",")","#","x.shape","=","(","2",",","1",",","3",")","y.shape","=","(","2",",","1",",","1",")",">",">",">","tsdataset.roll","(","lookback=lookback",",","horizon=horizon",",","id_sensitive=True",")",">",">",">","x",",","y","=","tsdataset.to_numpy","(",")",">",">",">","print","(","x",",","y",")","#","x","=","[","[","[","1.9",",","2.3",",","1",",","2",",","0",",","9","]","]","]","y","=","[","[","[","2.4",",","2.6","]","]","]",">",">",">","print","(","x.shape",",","y.shape",")","#","x.shape","=","(","1",",","1",",","6",")","y.shape","=","(","1",",","1",",","2",")"]
code: def roll(
      self,
      horizon,
      lookback="auto",
      feature_col=None,
      target_col=None,
      id_sensitive=False,
      time_enc=False,
      label_len=0,
      is_predict=False,
  ):
      """
      Sampling by rolling for machine learning/deep learning models.
  
      :param lookback: int, lookback value. Default to 'auto',
             if 'auto', the mode of time series' cycle length will be taken as the lookback.
      :param horizon: int or list.
             If `horizon` is an int, we will sample `horizon` step
             continuously after the forecasting point.
             If `horizon` is a list, we will sample discretely according
             to the input list. 1 means the timestamp just after the observed data.
             specially, when `horizon` is set to 0, ground truth will be generated as None.
      :param feature_col: str or list, indicates the feature col name. Default to None,
             where we will take all available feature in rolling.
      :param target_col: str or list, indicates the target col name. Default to None,
             where we will take all target in rolling. It should be a subset of target_col
             you used to initialize the tsdataset.
      :param id_sensitive: bool.
             If `id_sensitive` is False, we will rolling on each id's sub dataframe
             and fuse the sampings.
             The shape of rolling will be
             x: (num_sample, lookback, num_feature_col + num_target_col)
             y: (num_sample, horizon + label_len, num_target_col)
             where num_sample is the summation of sample number of each dataframe.
  
             If `id_sensitive` is True, we will rolling on the wide dataframe whose
             columns are cartesian product of id_col and feature_col.
             The shape of rolling will be
             x: (num_sample, lookback, new_num_feature_col + new_num_target_col)
             y: (num_sample, horizon + label_len, new_num_target_col)
             where num_sample is the sample number of the wide dataframe,
             new_num_feature_col is the product of the number of id and the number of feature_col,
             new_num_target_col is the product of the number of id and the number of target_col.
      :param time_enc: bool.
             This parameter should be set to True only when you are using Autoformer model. With
             time_enc to be true, 2 additional numpy ndarray will be returned when you call
             `.to_numpy()`. Be sure to have a time type for dt_col if you set time_enc to True.
      :param label_len: int.
             This parameter should be set to True only when you are using Autoformer model. This
             indicates the length of overlap area of output(y) and input(x) on time axis.
      :param is_predict: bool.
             This parameter indicates if the dataset will be sampled as a prediction dataset
             (without groud truth).
  
      :return: the tsdataset instance.
  
      roll() can be called by:
  
      >>> # Here is a df example:
      >>> # id        datetime      value   "extra feature 1"   "extra feature 2"
      >>> # 00        2019-01-01    1.9     1                   2
      >>> # 01        2019-01-01    2.3     0                   9
      >>> # 00        2019-01-02    2.4     3                   4
      >>> # 01        2019-01-02    2.6     0                   2
      >>> tsdataset = TSDataset.from_pandas(df, dt_col="datetime",
      >>>                                   target_col="value", id_col="id",
      >>>                                   extra_feature_col=["extra feature 1",
      >>>                                                      "extra feature 2"])
      >>> horizon, lookback = 1, 1
      >>> tsdataset.roll(lookback=lookback, horizon=horizon, id_sensitive=False)
      >>> x, y = tsdataset.to_numpy()
      >>> print(x, y) # x = [[[1.9, 1, 2 ]], [[2.3, 0, 9 ]]] y = [[[ 2.4 ]], [[ 2.6 ]]]
      >>> print(x.shape, y.shape) # x.shape = (2, 1, 3) y.shape = (2, 1, 1)
      >>> tsdataset.roll(lookback=lookback, horizon=horizon, id_sensitive=True)
      >>> x, y = tsdataset.to_numpy()
      >>> print(x, y) # x = [[[ 1.9, 2.3, 1, 2, 0, 9 ]]] y = [[[ 2.4, 2.6]]]
      >>> print(x.shape, y.shape) # x.shape = (1, 1, 6) y.shape = (1, 1, 2)
  
      """
      if not self.deploy_mode:
          from bigdl.nano.utils.common import invalidInputError
  
          if id_sensitive and not _check_is_aligned(
              self.df, self.id_col, self.dt_col
          ):
              invalidInputError(
                  False,
                  "The time series data should be "
                  "aligned if id_sensitive is set to True.",
              )
      else:
          is_predict = True
  
      feature_col = (
          _to_list(
              feature_col, "feature_col", deploy_mode=self.deploy_mode
          )
          if feature_col is not None
          else self.feature_col
      )
      target_col = (
          _to_list(
              target_col, "target_col", deploy_mode=self.deploy_mode
          )
          if target_col is not None
          else self.target_col
      )
      if self.roll_additional_feature:
          additional_feature_col = list(
              set(feature_col).intersection(
                  set(self.roll_additional_feature)
              )
          )
          feature_col = list(
              set(feature_col) - set(self.roll_additional_feature)
          )
          self.roll_feature = feature_col + additional_feature_col
      else:
          additional_feature_col = None
          self.roll_feature = feature_col
  
      self.roll_target = target_col
      num_id = len(self._id_list)
      num_feature_col = len(self.roll_feature)
      num_target_col = len(self.roll_target)
      self.id_sensitive = id_sensitive
      roll_feature_df = (
          None
          if self.roll_feature_df is None
          else self.roll_feature_df[additional_feature_col]
      )
  
      if time_enc and label_len == 0:
          label_len = max(lookback // 2, 1)
  
      self.lookback, self.horizon, self.label_len = (
          lookback,
          horizon,
          label_len,
      )
      # horizon_time is only for time_enc, the time_enc numpy ndarray won't have any
      # shape change when the dataset is for prediction.
      horizon_time = self.horizon
      if is_predict:
          self.horizon = 0
  
      if self.lookback == "auto":
          self.lookback = self.get_cycle_length("mode", top_k=3)
      groups = self.df.groupby([self.id_col])
      rolling_result = []
      for _, group in groups:
          rolling_result.append(
              roll_timeseries_dataframe(
                  df=group,
                  roll_feature_df=roll_feature_df,
                  lookback=self.lookback,
                  horizon=self.horizon,
                  feature_col=feature_col,
                  target_col=target_col,
                  label_len=label_len,
                  deploy_mode=self.deploy_mode,
              )
          )
  
      # concat the result on required axis
      concat_axis = 2 if id_sensitive else 0
      self.numpy_x = np.concatenate(
          [rolling_result[i][0] for i in range(len(self._id_list))],
          axis=concat_axis,
      ).astype(np.float32)
      if (horizon != 0 and is_predict is False) or time_enc:
          self.numpy_y = np.concatenate(
              [rolling_result[i][1] for i in range(len(self._id_list))],
              axis=concat_axis,
          ).astype(np.float32)
      else:
          self.numpy_y = None
  
      # time_enc
      if time_enc:
          time_enc_arr = []
          for _, group in groups:
              time_enc_arr.append(
                  gen_time_enc_arr(
                      df=group,
                      dt_col=self.dt_col,
                      freq=self._freq,
                      horizon_time=horizon_time,
                      is_predict=is_predict,
                      lookback=lookback,
                      label_len=label_len,
                  )
              )
          self.numpy_x_timeenc = np.concatenate(
              [time_enc_arr[i][0] for i in range(len(self._id_list))],
              axis=0,
          ).astype(np.float32)
          self.numpy_y_timeenc = np.concatenate(
              [time_enc_arr[i][1] for i in range(len(self._id_list))],
              axis=0,
          ).astype(np.float32)
      else:
          self.numpy_x_timeenc = None
          self.numpy_y_timeenc = None
  
      # target first
      # TODO: check id_sensitive effectiveness for the time_enc=True cases.
      if self.id_sensitive:
          feature_start_idx = num_target_col * num_id
          reindex_list = [
              list(range(i * num_target_col, (i + 1) * num_target_col))
              + list(
                  range(
                      feature_start_idx + i * num_feature_col,
                      feature_start_idx + (i + 1) * num_feature_col,
                  )
              )
              for i in range(num_id)
          ]
          reindex_list = functools.reduce(
              lambda a, b: a + b, reindex_list
          )
          sorted_index = sorted(
              range(len(reindex_list)), key=reindex_list.__getitem__
          )
          self.numpy_x = self.numpy_x[:, :, sorted_index]
  
      # scaler index
      num_roll_target = len(self.roll_target)
      repeat_factor = len(self._id_list) if self.id_sensitive else 1
      scaler_index = [
          self.target_col.index(self.roll_target[i])
          for i in range(num_roll_target)
      ] * repeat_factor
      self.scaler_index = scaler_index
  
      return self
  
imports: import pandas
  import numpy
  import functools
  import logging
  from bigdl.chronos.data.utils.feature import generate_dt_features, generate_global_features
  from bigdl.chronos.data.utils.impute import impute_timeseries_dataframe
  from bigdl.chronos.data.utils.deduplicate import deduplicate_timeseries_dataframe
  from bigdl.chronos.data.utils.roll import roll_timeseries_dataframe
  from bigdl.chronos.data.utils.time_feature import time_features, gen_time_enc_arr
  from bigdl.chronos.data.utils.scale import unscale_timeseries_numpy, scale_timeseries_numpy
  from bigdl.chronos.data.utils.resample import resample_timeseries_dataframe
  from bigdl.chronos.data.utils.split import split_timeseries_dataframe
  from bigdl.chronos.data.utils.cycle_detection import cycle_length_est
  from bigdl.chronos.data.utils.quality_inspection import quality_check_timeseries_dataframe, _abnormal_value_repair
  from bigdl.chronos.data.utils.utils import _to_list, _check_type, _check_col_within, _check_col_no_na, _check_is_aligned, _check_dt_is_sorted
label_desc: Use image node_id 12 for calling the TSDataset obj's underlying member method code with example usage: obj.roll(horizon, lookback, feature_col, target_col, id_sensitive, time_enc, label_len, is_predict) and returns: self