class_docstr: Defines univariate time series input. The dataset can include regressors,
  but only one metric is designated as the target metric to forecast.
  
  Loads time series into a standard format. Provides statistics, plotting
  functions, and ability to generate future dataframe for prediction.
  
  Attributes
  ----------
  df: `pandas.DataFrame`
      Data frame containing timestamp and value, with standardized column names for internal use
      (TIME_COL, VALUE_COL). Rows are sorted by time index, and missing gaps between dates are filled
      in so that dates are spaced at regular intervals. Values are adjusted for anomalies
      according to ``anomaly_info``.
      The index can be timezone aware (but TIME_COL is not).
  y: `pandas.Series`, dtype float64
      Value of time series to forecast.
  time_stats: `dict`
      Summary statistics about the timestamp column.
  value_stats: `dict`
      Summary statistics about the value column.
  original_time_col: `str`
      Name of time column in original input data.
  original_value_col: `str`
      Name of value column in original input data.
  regressor_cols: `list` [`str`]
      A list of regressor columns in the training and prediction DataFrames.
  lagged_regressor_cols: `list` [`str`]
      A list of additional columns needed for lagged regressors in the training and prediction DataFrames.
  last_date_for_val: `datetime.datetime` or None, default None
      Date or timestamp corresponding  to last non-null value in ``df[original_value_col]``.
  last_date_for_reg: `datetime.datetime` or None, default None
      Date or timestamp corresponding to last non-null value in ``df[regressor_cols]``.
      If ``regressor_cols`` is None, ``last_date_for_reg`` is None.
  last_date_for_lag_reg: `datetime.datetime` or None, default None
      Date or timestamp corresponding to last non-null value in ``df[lagged_regressor_cols]``.
      If ``lagged_regressor_cols`` is None, ``last_date_for_lag_reg`` is None.
  train_end_date: `datetime.datetime`
      Last date or timestamp in ``fit_df``. It is always less than or equal to
      minimum non-null values of ``last_date_for_val`` and ``last_date_for_reg``.
  fit_cols: `list` [`str`]
      A list of columns used in the training and prediction DataFrames.
  fit_df: `pandas.DataFrame`
      Data frame containing timestamp and value, with standardized column names for internal use.
      Will be used for fitting (train, cv, backtest).
  fit_y: `pandas.Series`, dtype float64
      Value of time series for fit_df.
  freq: `str`
      timeseries frequency, DateOffset alias, e.g. {'T' (minute), 'H', D', 'W', 'M' (month end), 'MS' (month start),
      'Y' (year end), 'Y' (year start)}
      See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases
  anomaly_info : `dict` or `list` [`dict`] or None, default None
      Anomaly adjustment info. Anomalies in ``df``
      are corrected before any forecasting is done.
      See ``self.load_data()``
  df_before_adjustment : `pandas.DataFrame` or None, default None
      ``self.df`` before adjustment by ``anomaly_info``.
      Used by ``self.plot()`` to show the adjustment.
class_docstr_tok: ["Defines","univariate","time","series","input",".","The","dataset","can","include","regressors",",","but","only","one","metric","is","designated","as","the","target","metric","to","forecast",".","Loads","time","series","into","a","standard","format",".","Provides","statistics",",","plotting","functions",",","and","ability","to","generate","future","dataframe","for","prediction",".","Attributes","--","--","--","--","--","df",":","`","pandas.DataFrame","`","Data","frame","containing","timestamp","and","value",",","with","standardized","column","names","for","internal","use","(","TIME_COL",",","VALUE_COL",")",".","Rows","are","sorted","by","time","index",",","and","missing","gaps","between","dates","are","filled","in","so","that","dates","are","spaced","at","regular","intervals",".","Values","are","adjusted","for","anomalies","according","to","``","anomaly_info","``",".","The","index","can","be","timezone","aware","(","but","TIME_COL","is","not",")",".","y",":","`","pandas.Series","`",",","dtype","float64","Value","of","time","series","to","forecast",".","time_stats",":","`","dict","`","Summary","statistics","about","the","timestamp","column",".","value_stats",":","`","dict","`","Summary","statistics","about","the","value","column",".","original_time_col",":","`","str","`","Name","of","time","column","in","original","input","data",".","original_value_col",":","`","str","`","Name","of","value","column","in","original","input","data",".","regressor_cols",":","`","list","`","[","`","str","`","]","A","list","of","regressor","columns","in","the","training","and","prediction","DataFrames",".","lagged_regressor_cols",":","`","list","`","[","`","str","`","]","A","list","of","additional","columns","needed","for","lagged","regressors","in","the","training","and","prediction","DataFrames",".","last_date_for_val",":","`","datetime.datetime","`","or","None",",","default","None","Date","or","timestamp","corresponding","to","last","non-null","value","in","``","df","[","original_value_col","]","``",".","last_date_for_reg",":","`","datetime.datetime","`","or","None",",","default","None","Date","or","timestamp","corresponding","to","last","non-null","value","in","``","df","[","regressor_cols","]","``",".","If","``","regressor_cols","``","is","None",",","``","last_date_for_reg","``","is","None",".","last_date_for_lag_reg",":","`","datetime.datetime","`","or","None",",","default","None","Date","or","timestamp","corresponding","to","last","non-null","value","in","``","df","[","lagged_regressor_cols","]","``",".","If","``","lagged_regressor_cols","``","is","None",",","``","last_date_for_lag_reg","``","is","None",".","train_end_date",":","`","datetime.datetime","`","Last","date","or","timestamp","in","``","fit_df","``",".","It","is","always","less","than","or","equal","to","minimum","non-null","values","of","``","last_date_for_val","``","and","``","last_date_for_reg","``",".","fit_cols",":","`","list","`","[","`","str","`","]","A","list","of","columns","used","in","the","training","and","prediction","DataFrames",".","fit_df",":","`","pandas.DataFrame","`","Data","frame","containing","timestamp","and","value",",","with","standardized","column","names","for","internal","use",".","Will","be","used","for","fitting","(","train",",","cv",",","backtest",")",".","fit_y",":","`","pandas.Series","`",",","dtype","float64","Value","of","time","series","for","fit_df",".","freq",":","`","str","`","timeseries","frequency",",","DateOffset","alias",",","e.g",".","{","'T","'","(","minute",")",",","'","H","'",",","D","'",",","'","W","'",",","'M","'","(","month","end",")",",","'MS","'","(","month","start",")",",","'","Y","'","(","year","end",")",",","'","Y","'","(","year","start",")","}","See","https",":","\/\/pandas.pydata.org\/pandas-docs\/stable\/user_guide\/timeseries.html","#","offset-aliases","anomaly_info",":","`","dict","`","or","`","list","`","[","`","dict","`","]","or","None",",","default","None","Anomaly","adjustment","info",".","Anomalies","in","``","df","``","are","corrected","before","any","forecasting","is","done",".","See","``","self.load_data","(",")","``","df_before_adjustment",":","`","pandas.DataFrame","`","or","None",",","default","None","``","self.df","``","before","adjustment","by","``","anomaly_info","``",".","Used","by","``","self.plot","(",")","``","to","show","the","adjustment","."]
docstr: Plots mean, quantiles, and overlays by the requested grouping dimension.
  
  The grouping dimension goes on the x-axis, and one line is shown for the mean,
  each quantile, and each level of the overlay dimension, as requested. By default,
  shading is applied between the quantiles.
  
  Exactly one of: ``groupby_time_feature``, ``groupby_sliding_window_size``,
  ``groupby_custom_column`` must be provided as the grouping dimension.
  
  If ``show_overlays`` is True, exactly one of: ``overlay_label_time_feature``,
  ``overlay_label_sliding_window_size``, ``overlay_label_custom_column`` can be
  provided to specify the ``label_col`` (overlay dimension). Internally, the
  function calls `pandas.DataFrame.pivot_table` with ``index=groupby_col``,
  ``columns=label_col``, ``values=value_col`` to get the overlay values for plotting.
  You can pass additional parameters to `pandas.DataFrame.pivot_table` via
  ``overlay_pivot_table_kwargs``, e.g. to change the aggregation method. If an explicit
  label is not provided, the records are labeled by their position within the group.
  
  For example, to show yearly seasonality mean, quantiles, and overlay plots for
  each individual year, use::
  
      self.plot_quantiles_and_overlays(
          groupby_time_feature="doy",         # Rows: a row for each day of year (1, 2, ..., 366)
          show_mean=True,                     # mean value on that day
          show_quantiles=[0.1, 0.9],          # quantiles of the observed distribution on that day
          show_overlays=True,                 # Include overlays defined by ``overlay_label_time_feature``
          overlay_label_time_feature="year")  # One column for each observed "year" (2016, 2017, 2018, ...)
  
  To show weekly seasonality over time, use::
  
      self.plot_quantiles_and_overlays(
          groupby_time_feature="dow",            # Rows: a row for each day of week (1, 2, ..., 7)
          show_mean=True,                        # mean value on that day
          show_quantiles=[0.1, 0.5, 0.9],        # quantiles of the observed distribution on that day
          show_overlays=True,                    # Include overlays defined by ``overlay_label_time_feature``
          overlay_label_sliding_window_size=90,  # One column for each 90 period sliding window in the dataset,
          aggfunc="median")                      # overlay value is the median value for the dow over the period (default="mean").
  
  It may be difficult to assess the weekly seasonality from the previous result,
  because overlays shift up/down over time due to trend/yearly seasonality.
  Use ``center_values=True`` to adjust each overlay so its average value is centered at 0.
  Mean and quantiles are shifted by a single constant to center the mean at 0, while
  preserving their relative values::
  
      self.plot_quantiles_and_overlays(
          groupby_time_feature="dow",
          show_mean=True,
          show_quantiles=[0.1, 0.5, 0.9],
          show_overlays=True,
          overlay_label_sliding_window_size=90,
          aggfunc="median",
          center_values=True)  # Centers the output
  
  Centering reduces the variability in the overlays to make it easier to isolate
  the effect by the groupby column. As a result, centered overlays have smaller
  variability than that reported by the quantiles, which operate on the original,
  uncentered data points. Similarly, if overlays are aggregates of individual values
  (i.e. ``aggfunc`` is needed in the call to `pandas.DataFrame.pivot_table`),
  the quantiles of overlays will be less extreme than those of the original data.
  
      - To assess variability conditioned on the groupby value, check the quantiles.
      - To assess variability conditioned on both the groupby and overlay value,
        after any necessary aggregation, check the variability of the overlay values.
        Compute quantiles of overlays from the return value if desired.
  
  Parameters
  ----------
  groupby_time_feature : `str` or None, default None
      If provided, groups by a column generated by
      `~greykite.common.features.timeseries_features.build_time_features_df`.
      See that function for valid values.
  groupby_sliding_window_size : `int` or None, default None
      If provided, sequentially partitions data into groups of size
      ``groupby_sliding_window_size``.
  groupby_custom_column : `pandas.Series` or None, default None
      If provided, groups by this column value. Should be same length as the DataFrame.
  show_mean : `bool`, default False
      Whether to return the mean value by the groupby column.
  show_quantiles : `bool` or `list` [`float`] or `numpy.array`, default False
      Whether to return the quantiles of the value by the groupby column.
      If False, does not return quantiles. If True, returns default
      quantiles (0.1 and 0.9). If array-like, a list of quantiles
      to compute (e.g. (0.1, 0.25, 0.75, 0.9)).
  show_overlays : `bool` or `int` or array-like [`int` or `str`], default False
      Whether to return overlays of the value by the groupby column.
  
      If False, no overlays are shown.
  
      If True and ``label_col`` is defined, calls `pandas.DataFrame.pivot_table` with
      ``index=groupby_col``, ``columns=label_col``, ``values=value_col``.
      ``label_col`` is defined by one of ``overlay_label_time_feature``,
      ``overlay_label_sliding_window_size``, or ``overlay_label_custom_column``.
      Returns one column for each value of the ``label_col``.
  
      If True and the ``label_col`` is not defined, returns the raw values within
      each group. Values across groups are put into columns by their position in
      the group (1st element in group, 2nd, 3rd, etc.). Positional order in a group
      is not guaranteed to correspond to anything meaningful, so the items within a
      column may not have anything in common. It is better to specify one of ``overlay_*``
      to explicitly define the overlay labels.
  
      If an integer, the number of overlays to randomly sample. The same as True,
      then randomly samples up to `int` columns. This is useful if there are too many values.
  
      If a list [int], a list of column indices (int type). The same as True,
      then selects the specified columns by index.
  
      If a list [str], a list of column names. Column names are matched by their
      string representation to the names in this list. The same as True,
      then selects the specified columns by name.
  
  overlay_label_time_feature : `str` or None, default None
      If ``show_overlays`` is True, can be used to define ``label_col``,
      i.e. which dimension to show separately as overlays.
  
      If provided, uses a column generated by
      `~greykite.common.features.timeseries_features.build_time_features_df`.
      See that function for valid values.
  overlay_label_sliding_window_size : `int` or None, default None
      If ``show_overlays`` is True, can be used to define ``label_col``,
      i.e. which dimension to show separately as overlays.
  
      If provided, uses a column that sequentially partitions data into groups
      of size ``groupby_sliding_window_size``.
  overlay_label_custom_column : `pandas.Series` or None, default None
      If ``show_overlays`` is True, can be used to define ``label_col``,
      i.e. which dimension to show separately as overlays.
  
      If provided, uses this column value. Should be same length as the DataFrame.
  
  value_col : `str`, default VALUE_COL
      The column name for the value column. By default,
      shows the univariate time series value, but it can be any
      other column in ``self.df``.
  
  mean_col_name : `str`, default "mean"
      The name to use for the mean column in the output.
      Applies if ``show_mean=True``.
  
  quantile_col_prefix : `str`, default "Q"
      The prefix to use for quantile column names in the output.
      Columns are named with this prefix followed by the quantile,
      rounded to 2 decimal places.
  
  center_values : `bool`, default False
      Whether to center the return values.
      If True, shifts each overlay so its average value is centered at 0.
      Shifts mean and quantiles by a constant to center the mean at 0, while
      preserving their relative values.
  
      If False, values are not centered.
  
  mean_style: `dict` or None, default None
      How to style the mean line, passed as keyword arguments to
      `plotly.graph_objects.Scatter`. If None, the default is::
  
          mean_style = {
              "line": dict(
                  width=2,
                  color="#595959"),  # gray
              "legendgroup": MEAN_COL_GROUP}
  
  quantile_style: `dict` or None, default None
      How to style the quantile lines, passed as keyword arguments to
      `plotly.graph_objects.Scatter`. If None, the default is::
  
          quantile_style = {
              "line": dict(
                  width=2,
                  color="#1F9AFF",  # blue
                  dash="solid"),
              "legendgroup": QUANTILE_COL_GROUP,  # show/hide them together
              "fill": "tonexty"}
  
      Note that fill style is removed from to the first quantile line, to
      fill only between items in the same category.
  
  overlay_style: `dict` or None, default None
      How to style the overlay lines, passed as keyword arguments to
      `plotly.graph_objects.Scatter`. If None, the default is::
  
          overlay_style = {
              "opacity": 0.5,  # makes it easier to see density
              "line": dict(
                  width=1,
                  color="#B3B3B3",  # light gray
                  dash="solid"),
              "legendgroup": OVERLAY_COL_GROUP}
  
  xlabel : `str`, optional, default None
      X-axis label of the plot.
  ylabel : `str`, optional, default None
      Y-axis label of the plot. If None, uses ``value_col``.
  title : `str` or None, default None
      Plot title. If None, default is based on axis labels.
  showlegend : `bool`, default True
      Whether to show the legend.
  overlay_pivot_table_kwargs : additional parameters
      Additional keyword parameters to pass to `pandas.DataFrame.pivot_table`,
      used in generating the overlays.
      See `~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays`
      description for details.
  
  Returns
  -------
  fig : `plotly.graph_objects.Figure`
      plotly graph object showing the mean, quantiles, and overlays.
  
  See Also
  --------
  `~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays`
      To get the mean, quantiles, and overlays as a `pandas.DataFrame` without plotting.
docstr_tok: ["Plots","mean",",","quantiles",",","and","overlays","by","the","requested","grouping","dimension",".","The","grouping","dimension","goes","on","the","x-axis",",","and","one","line","is","shown","for","the","mean",",","each","quantile",",","and","each","level","of","the","overlay","dimension",",","as","requested",".","By","default",",","shading","is","applied","between","the","quantiles",".","Exactly","one","of",":","``","groupby_time_feature","``",",","``","groupby_sliding_window_size","``",",","``","groupby_custom_column","``","must","be","provided","as","the","grouping","dimension",".","If","``","show_overlays","``","is","True",",","exactly","one","of",":","``","overlay_label_time_feature","``",",","``","overlay_label_sliding_window_size","``",",","``","overlay_label_custom_column","``","can","be","provided","to","specify","the","``","label_col","``","(","overlay","dimension",")",".","Internally",",","the","function","calls","`","pandas.DataFrame.pivot_table","`","with","``","index=groupby_col","``",",","``","columns=label_col","``",",","``","values=value_col","``","to","get","the","overlay","values","for","plotting",".","You","can","pass","additional","parameters","to","`","pandas.DataFrame.pivot_table","`","via","``","overlay_pivot_table_kwargs","``",",","e.g",".","to","change","the","aggregation","method",".","If","an","explicit","label","is","not","provided",",","the","records","are","labeled","by","their","position","within","the","group",".","For","example",",","to","show","yearly","seasonality","mean",",","quantiles",",","and","overlay","plots","for","each","individual","year",",","use",":",":","self.plot_quantiles_and_overlays","(","groupby_time_feature=","''","doy","''",",","#","Rows",":","a","row","for","each","day","of","year","(","1",",","2",",","...",",","366",")","show_mean=True",",","#","mean","value","on","that","day","show_quantiles=","[","0.1",",","0.9","]",",","#","quantiles","of","the","observed","distribution","on","that","day","show_overlays=True",",","#","Include","overlays","defined","by","``","overlay_label_time_feature","``","overlay_label_time_feature=","''","year","''",")","#","One","column","for","each","observed","``","year","''","(","2016",",","2017",",","2018",",","...",")","To","show","weekly","seasonality","over","time",",","use",":",":","self.plot_quantiles_and_overlays","(","groupby_time_feature=","''","dow","''",",","#","Rows",":","a","row","for","each","day","of","week","(","1",",","2",",","...",",","7",")","show_mean=True",",","#","mean","value","on","that","day","show_quantiles=","[","0.1",",","0.5",",","0.9","]",",","#","quantiles","of","the","observed","distribution","on","that","day","show_overlays=True",",","#","Include","overlays","defined","by","``","overlay_label_time_feature","``","overlay_label_sliding_window_size=90",",","#","One","column","for","each","90","period","sliding","window","in","the","dataset",",","aggfunc=","''","median","''",")","#","overlay","value","is","the","median","value","for","the","dow","over","the","period","(","default=","''","mean","''",")",".","It","may","be","difficult","to","assess","the","weekly","seasonality","from","the","previous","result",",","because","overlays","shift","up\/down","over","time","due","to","trend\/yearly","seasonality",".","Use","``","center_values=True","``","to","adjust","each","overlay","so","its","average","value","is","centered","at","0",".","Mean","and","quantiles","are","shifted","by","a","single","constant","to","center","the","mean","at","0",",","while","preserving","their","relative","values",":",":","self.plot_quantiles_and_overlays","(","groupby_time_feature=","''","dow","''",",","show_mean=True",",","show_quantiles=","[","0.1",",","0.5",",","0.9","]",",","show_overlays=True",",","overlay_label_sliding_window_size=90",",","aggfunc=","''","median","''",",","center_values=True",")","#","Centers","the","output","Centering","reduces","the","variability","in","the","overlays","to","make","it","easier","to","isolate","the","effect","by","the","groupby","column",".","As","a","result",",","centered","overlays","have","smaller","variability","than","that","reported","by","the","quantiles",",","which","operate","on","the","original",",","uncentered","data","points",".","Similarly",",","if","overlays","are","aggregates","of","individual","values","(","i.e",".","``","aggfunc","``","is","needed","in","the","call","to","`","pandas.DataFrame.pivot_table","`",")",",","the","quantiles","of","overlays","will","be","less","extreme","than","those","of","the","original","data",".","-","To","assess","variability","conditioned","on","the","groupby","value",",","check","the","quantiles",".","-","To","assess","variability","conditioned","on","both","the","groupby","and","overlay","value",",","after","any","necessary","aggregation",",","check","the","variability","of","the","overlay","values",".","Compute","quantiles","of","overlays","from","the","return","value","if","desired",".","Parameters","--","--","--","--","--","groupby_time_feature",":","`","str","`","or","None",",","default","None","If","provided",",","groups","by","a","column","generated","by","`","~greykite.common.features.timeseries_features.build_time_features_df","`",".","See","that","function","for","valid","values",".","groupby_sliding_window_size",":","`","int","`","or","None",",","default","None","If","provided",",","sequentially","partitions","data","into","groups","of","size","``","groupby_sliding_window_size","``",".","groupby_custom_column",":","`","pandas.Series","`","or","None",",","default","None","If","provided",",","groups","by","this","column","value",".","Should","be","same","length","as","the","DataFrame",".","show_mean",":","`","bool","`",",","default","False","Whether","to","return","the","mean","value","by","the","groupby","column",".","show_quantiles",":","`","bool","`","or","`","list","`","[","`","float","`","]","or","`","numpy.array","`",",","default","False","Whether","to","return","the","quantiles","of","the","value","by","the","groupby","column",".","If","False",",","does","not","return","quantiles",".","If","True",",","returns","default","quantiles","(","0.1","and","0.9",")",".","If","array-like",",","a","list","of","quantiles","to","compute","(","e.g",".","(","0.1",",","0.25",",","0.75",",","0.9",")",")",".","show_overlays",":","`","bool","`","or","`","int","`","or","array-like","[","`","int","`","or","`","str","`","]",",","default","False","Whether","to","return","overlays","of","the","value","by","the","groupby","column",".","If","False",",","no","overlays","are","shown",".","If","True","and","``","label_col","``","is","defined",",","calls","`","pandas.DataFrame.pivot_table","`","with","``","index=groupby_col","``",",","``","columns=label_col","``",",","``","values=value_col","``",".","``","label_col","``","is","defined","by","one","of","``","overlay_label_time_feature","``",",","``","overlay_label_sliding_window_size","``",",","or","``","overlay_label_custom_column","``",".","Returns","one","column","for","each","value","of","the","``","label_col","``",".","If","True","and","the","``","label_col","``","is","not","defined",",","returns","the","raw","values","within","each","group",".","Values","across","groups","are","put","into","columns","by","their","position","in","the","group","(","1st","element","in","group",",","2nd",",","3rd",",","etc.",")",".","Positional","order","in","a","group","is","not","guaranteed","to","correspond","to","anything","meaningful",",","so","the","items","within","a","column","may","not","have","anything","in","common",".","It","is","better","to","specify","one","of","``","overlay_","*","``","to","explicitly","define","the","overlay","labels",".","If","an","integer",",","the","number","of","overlays","to","randomly","sample",".","The","same","as","True",",","then","randomly","samples","up","to","`","int","`","columns",".","This","is","useful","if","there","are","too","many","values",".","If","a","list","[","int","]",",","a","list","of","column","indices","(","int","type",")",".","The","same","as","True",",","then","selects","the","specified","columns","by","index",".","If","a","list","[","str","]",",","a","list","of","column","names",".","Column","names","are","matched","by","their","string","representation","to","the","names","in","this","list",".","The","same","as","True",",","then","selects","the","specified","columns","by","name",".","overlay_label_time_feature",":","`","str","`","or","None",",","default","None","If","``","show_overlays","``","is","True",",","can","be","used","to","define","``","label_col","``",",","i.e",".","which","dimension","to","show","separately","as","overlays",".","If","provided",",","uses","a","column","generated","by","`","~greykite.common.features.timeseries_features.build_time_features_df","`",".","See","that","function","for","valid","values",".","overlay_label_sliding_window_size",":","`","int","`","or","None",",","default","None","If","``","show_overlays","``","is","True",",","can","be","used","to","define","``","label_col","``",",","i.e",".","which","dimension","to","show","separately","as","overlays",".","If","provided",",","uses","a","column","that","sequentially","partitions","data","into","groups","of","size","``","groupby_sliding_window_size","``",".","overlay_label_custom_column",":","`","pandas.Series","`","or","None",",","default","None","If","``","show_overlays","``","is","True",",","can","be","used","to","define","``","label_col","``",",","i.e",".","which","dimension","to","show","separately","as","overlays",".","If","provided",",","uses","this","column","value",".","Should","be","same","length","as","the","DataFrame",".","value_col",":","`","str","`",",","default","VALUE_COL","The","column","name","for","the","value","column",".","By","default",",","shows","the","univariate","time","series","value",",","but","it","can","be","any","other","column","in","``","self.df","``",".","mean_col_name",":","`","str","`",",","default","``","mean","''","The","name","to","use","for","the","mean","column","in","the","output",".","Applies","if","``","show_mean=True","``",".","quantile_col_prefix",":","`","str","`",",","default","``","Q","''","The","prefix","to","use","for","quantile","column","names","in","the","output",".","Columns","are","named","with","this","prefix","followed","by","the","quantile",",","rounded","to","2","decimal","places",".","center_values",":","`","bool","`",",","default","False","Whether","to","center","the","return","values",".","If","True",",","shifts","each","overlay","so","its","average","value","is","centered","at","0",".","Shifts","mean","and","quantiles","by","a","constant","to","center","the","mean","at","0",",","while","preserving","their","relative","values",".","If","False",",","values","are","not","centered",".","mean_style",":","`","dict","`","or","None",",","default","None","How","to","style","the","mean","line",",","passed","as","keyword","arguments","to","`","plotly.graph_objects.Scatter","`",".","If","None",",","the","default","is",":",":","mean_style","=","{","``","line","''",":","dict","(","width=2",",","color=","''","#","595959","''",")",",","#","gray","``","legendgroup","''",":","MEAN_COL_GROUP","}","quantile_style",":","`","dict","`","or","None",",","default","None","How","to","style","the","quantile","lines",",","passed","as","keyword","arguments","to","`","plotly.graph_objects.Scatter","`",".","If","None",",","the","default","is",":",":","quantile_style","=","{","``","line","''",":","dict","(","width=2",",","color=","''","#","1F9AFF","''",",","#","blue","dash=","''","solid","''",")",",","``","legendgroup","''",":","QUANTILE_COL_GROUP",",","#","show\/hide","them","together","``","fill","''",":","``","tonexty","''","}","Note","that","fill","style","is","removed","from","to","the","first","quantile","line",",","to","fill","only","between","items","in","the","same","category",".","overlay_style",":","`","dict","`","or","None",",","default","None","How","to","style","the","overlay","lines",",","passed","as","keyword","arguments","to","`","plotly.graph_objects.Scatter","`",".","If","None",",","the","default","is",":",":","overlay_style","=","{","``","opacity","''",":","0.5",",","#","makes","it","easier","to","see","density","``","line","''",":","dict","(","width=1",",","color=","''","#","B3B3B3","''",",","#","light","gray","dash=","''","solid","''",")",",","``","legendgroup","''",":","OVERLAY_COL_GROUP","}","xlabel",":","`","str","`",",","optional",",","default","None","X-axis","label","of","the","plot",".","ylabel",":","`","str","`",",","optional",",","default","None","Y-axis","label","of","the","plot",".","If","None",",","uses","``","value_col","``",".","title",":","`","str","`","or","None",",","default","None","Plot","title",".","If","None",",","default","is","based","on","axis","labels",".","showlegend",":","`","bool","`",",","default","True","Whether","to","show","the","legend",".","overlay_pivot_table_kwargs",":","additional","parameters","Additional","keyword","parameters","to","pass","to","`","pandas.DataFrame.pivot_table","`",",","used","in","generating","the","overlays",".","See","`","~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays","`","description","for","details",".","Returns","--","--","--","-","fig",":","`","plotly.graph_objects.Figure","`","plotly","graph","object","showing","the","mean",",","quantiles",",","and","overlays",".","See","Also","--","--","--","--","`","~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays","`","To","get","the","mean",",","quantiles",",","and","overlays","as","a","`","pandas.DataFrame","`","without","plotting","."]
code: def plot_quantiles_and_overlays(
      self,
      groupby_time_feature=None,
      groupby_sliding_window_size=None,
      groupby_custom_column=None,
      show_mean=False,
      show_quantiles=False,
      show_overlays=False,
      overlay_label_time_feature=None,
      overlay_label_sliding_window_size=None,
      overlay_label_custom_column=None,
      center_values=False,
      value_col=VALUE_COL,
      mean_col_name="mean",
      quantile_col_prefix="Q",
      mean_style=None,
      quantile_style=None,
      overlay_style=None,
      xlabel=None,
      ylabel=None,
      title=None,
      showlegend=True,
      **overlay_pivot_table_kwargs,
  ):
      """Plots mean, quantiles, and overlays by the requested grouping dimension.
  
      The grouping dimension goes on the x-axis, and one line is shown for the mean,
      each quantile, and each level of the overlay dimension, as requested. By default,
      shading is applied between the quantiles.
  
      Exactly one of: ``groupby_time_feature``, ``groupby_sliding_window_size``,
      ``groupby_custom_column`` must be provided as the grouping dimension.
  
      If ``show_overlays`` is True, exactly one of: ``overlay_label_time_feature``,
      ``overlay_label_sliding_window_size``, ``overlay_label_custom_column`` can be
      provided to specify the ``label_col`` (overlay dimension). Internally, the
      function calls `pandas.DataFrame.pivot_table` with ``index=groupby_col``,
      ``columns=label_col``, ``values=value_col`` to get the overlay values for plotting.
      You can pass additional parameters to `pandas.DataFrame.pivot_table` via
      ``overlay_pivot_table_kwargs``, e.g. to change the aggregation method. If an explicit
      label is not provided, the records are labeled by their position within the group.
  
      For example, to show yearly seasonality mean, quantiles, and overlay plots for
      each individual year, use::
  
          self.plot_quantiles_and_overlays(
              groupby_time_feature="doy",         # Rows: a row for each day of year (1, 2, ..., 366)
              show_mean=True,                     # mean value on that day
              show_quantiles=[0.1, 0.9],          # quantiles of the observed distribution on that day
              show_overlays=True,                 # Include overlays defined by ``overlay_label_time_feature``
              overlay_label_time_feature="year")  # One column for each observed "year" (2016, 2017, 2018, ...)
  
      To show weekly seasonality over time, use::
  
          self.plot_quantiles_and_overlays(
              groupby_time_feature="dow",            # Rows: a row for each day of week (1, 2, ..., 7)
              show_mean=True,                        # mean value on that day
              show_quantiles=[0.1, 0.5, 0.9],        # quantiles of the observed distribution on that day
              show_overlays=True,                    # Include overlays defined by ``overlay_label_time_feature``
              overlay_label_sliding_window_size=90,  # One column for each 90 period sliding window in the dataset,
              aggfunc="median")                      # overlay value is the median value for the dow over the period (default="mean").
  
      It may be difficult to assess the weekly seasonality from the previous result,
      because overlays shift up/down over time due to trend/yearly seasonality.
      Use ``center_values=True`` to adjust each overlay so its average value is centered at 0.
      Mean and quantiles are shifted by a single constant to center the mean at 0, while
      preserving their relative values::
  
          self.plot_quantiles_and_overlays(
              groupby_time_feature="dow",
              show_mean=True,
              show_quantiles=[0.1, 0.5, 0.9],
              show_overlays=True,
              overlay_label_sliding_window_size=90,
              aggfunc="median",
              center_values=True)  # Centers the output
  
      Centering reduces the variability in the overlays to make it easier to isolate
      the effect by the groupby column. As a result, centered overlays have smaller
      variability than that reported by the quantiles, which operate on the original,
      uncentered data points. Similarly, if overlays are aggregates of individual values
      (i.e. ``aggfunc`` is needed in the call to `pandas.DataFrame.pivot_table`),
      the quantiles of overlays will be less extreme than those of the original data.
  
          - To assess variability conditioned on the groupby value, check the quantiles.
          - To assess variability conditioned on both the groupby and overlay value,
            after any necessary aggregation, check the variability of the overlay values.
            Compute quantiles of overlays from the return value if desired.
  
      Parameters
      ----------
      groupby_time_feature : `str` or None, default None
          If provided, groups by a column generated by
          `~greykite.common.features.timeseries_features.build_time_features_df`.
          See that function for valid values.
      groupby_sliding_window_size : `int` or None, default None
          If provided, sequentially partitions data into groups of size
          ``groupby_sliding_window_size``.
      groupby_custom_column : `pandas.Series` or None, default None
          If provided, groups by this column value. Should be same length as the DataFrame.
      show_mean : `bool`, default False
          Whether to return the mean value by the groupby column.
      show_quantiles : `bool` or `list` [`float`] or `numpy.array`, default False
          Whether to return the quantiles of the value by the groupby column.
          If False, does not return quantiles. If True, returns default
          quantiles (0.1 and 0.9). If array-like, a list of quantiles
          to compute (e.g. (0.1, 0.25, 0.75, 0.9)).
      show_overlays : `bool` or `int` or array-like [`int` or `str`], default False
          Whether to return overlays of the value by the groupby column.
  
          If False, no overlays are shown.
  
          If True and ``label_col`` is defined, calls `pandas.DataFrame.pivot_table` with
          ``index=groupby_col``, ``columns=label_col``, ``values=value_col``.
          ``label_col`` is defined by one of ``overlay_label_time_feature``,
          ``overlay_label_sliding_window_size``, or ``overlay_label_custom_column``.
          Returns one column for each value of the ``label_col``.
  
          If True and the ``label_col`` is not defined, returns the raw values within
          each group. Values across groups are put into columns by their position in
          the group (1st element in group, 2nd, 3rd, etc.). Positional order in a group
          is not guaranteed to correspond to anything meaningful, so the items within a
          column may not have anything in common. It is better to specify one of ``overlay_*``
          to explicitly define the overlay labels.
  
          If an integer, the number of overlays to randomly sample. The same as True,
          then randomly samples up to `int` columns. This is useful if there are too many values.
  
          If a list [int], a list of column indices (int type). The same as True,
          then selects the specified columns by index.
  
          If a list [str], a list of column names. Column names are matched by their
          string representation to the names in this list. The same as True,
          then selects the specified columns by name.
  
      overlay_label_time_feature : `str` or None, default None
          If ``show_overlays`` is True, can be used to define ``label_col``,
          i.e. which dimension to show separately as overlays.
  
          If provided, uses a column generated by
          `~greykite.common.features.timeseries_features.build_time_features_df`.
          See that function for valid values.
      overlay_label_sliding_window_size : `int` or None, default None
          If ``show_overlays`` is True, can be used to define ``label_col``,
          i.e. which dimension to show separately as overlays.
  
          If provided, uses a column that sequentially partitions data into groups
          of size ``groupby_sliding_window_size``.
      overlay_label_custom_column : `pandas.Series` or None, default None
          If ``show_overlays`` is True, can be used to define ``label_col``,
          i.e. which dimension to show separately as overlays.
  
          If provided, uses this column value. Should be same length as the DataFrame.
  
      value_col : `str`, default VALUE_COL
          The column name for the value column. By default,
          shows the univariate time series value, but it can be any
          other column in ``self.df``.
  
      mean_col_name : `str`, default "mean"
          The name to use for the mean column in the output.
          Applies if ``show_mean=True``.
  
      quantile_col_prefix : `str`, default "Q"
          The prefix to use for quantile column names in the output.
          Columns are named with this prefix followed by the quantile,
          rounded to 2 decimal places.
  
      center_values : `bool`, default False
          Whether to center the return values.
          If True, shifts each overlay so its average value is centered at 0.
          Shifts mean and quantiles by a constant to center the mean at 0, while
          preserving their relative values.
  
          If False, values are not centered.
  
      mean_style: `dict` or None, default None
          How to style the mean line, passed as keyword arguments to
          `plotly.graph_objects.Scatter`. If None, the default is::
  
              mean_style = {
                  "line": dict(
                      width=2,
                      color="#595959"),  # gray
                  "legendgroup": MEAN_COL_GROUP}
  
      quantile_style: `dict` or None, default None
          How to style the quantile lines, passed as keyword arguments to
          `plotly.graph_objects.Scatter`. If None, the default is::
  
              quantile_style = {
                  "line": dict(
                      width=2,
                      color="#1F9AFF",  # blue
                      dash="solid"),
                  "legendgroup": QUANTILE_COL_GROUP,  # show/hide them together
                  "fill": "tonexty"}
  
          Note that fill style is removed from to the first quantile line, to
          fill only between items in the same category.
  
      overlay_style: `dict` or None, default None
          How to style the overlay lines, passed as keyword arguments to
          `plotly.graph_objects.Scatter`. If None, the default is::
  
              overlay_style = {
                  "opacity": 0.5,  # makes it easier to see density
                  "line": dict(
                      width=1,
                      color="#B3B3B3",  # light gray
                      dash="solid"),
                  "legendgroup": OVERLAY_COL_GROUP}
  
      xlabel : `str`, optional, default None
          X-axis label of the plot.
      ylabel : `str`, optional, default None
          Y-axis label of the plot. If None, uses ``value_col``.
      title : `str` or None, default None
          Plot title. If None, default is based on axis labels.
      showlegend : `bool`, default True
          Whether to show the legend.
      overlay_pivot_table_kwargs : additional parameters
          Additional keyword parameters to pass to `pandas.DataFrame.pivot_table`,
          used in generating the overlays.
          See `~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays`
          description for details.
  
      Returns
      -------
      fig : `plotly.graph_objects.Figure`
          plotly graph object showing the mean, quantiles, and overlays.
  
      See Also
      --------
      `~greykite.framework.input.univariate_time_series.UnivariateTimeSeries.get_quantiles_and_overlays`
          To get the mean, quantiles, and overlays as a `pandas.DataFrame` without plotting.
      """
  
      if ylabel is None:
          ylabel = value_col
  
      grouped_df = self.get_quantiles_and_overlays(
          groupby_time_feature=groupby_time_feature,
          groupby_sliding_window_size=groupby_sliding_window_size,
          groupby_custom_column=groupby_custom_column,
          show_mean=show_mean,
          show_quantiles=show_quantiles,
          show_overlays=show_overlays,
          overlay_label_time_feature=overlay_label_time_feature,
          overlay_label_sliding_window_size=overlay_label_sliding_window_size,
          overlay_label_custom_column=overlay_label_custom_column,
          center_values=center_values,
          value_col=value_col,
          mean_col_name=mean_col_name,
          quantile_col_prefix=quantile_col_prefix,
          **overlay_pivot_table_kwargs,
      )
  
      if mean_style is None:
          mean_style = {
              "line": dict(width=2, color="#595959"),  # gray
              "legendgroup": MEAN_COL_GROUP,
          }
      if quantile_style is None:
          quantile_style = {
              "line": dict(
                  width=2, color="#1F9AFF", dash="solid"  # blue
              ),
              "legendgroup": QUANTILE_COL_GROUP,  # show/hide them together
              "fill": "tonexty",
          }
      if overlay_style is None:
          overlay_style = {
              "opacity": 0.5,  # makes it easier to see density
              "line": dict(
                  width=1, color="#B3B3B3", dash="solid"  # light gray
              ),
              "legendgroup": OVERLAY_COL_GROUP,
          }
      style_dict = {
          MEAN_COL_GROUP: mean_style,
          QUANTILE_COL_GROUP: quantile_style,
          OVERLAY_COL_GROUP: overlay_style,
      }
  
      y_col_style_dict = {}
      # All categories in grouped_df. Reverses the order so the first category is plotted last (on top).
      categories = grouped_df.columns.get_level_values(0).unique()[::-1]
      for category in categories:
          style = style_dict.get(category, {})
          if "fill" in style:
              # If fill is part of the style, plotly fills the area between this line and
              # the previous line added to the plot.
              # Since we only want to fill between lines in the same category (e.g. between quantiles),
              # we remove the "fill" from the first line within each category. Otherwise the first
              # line in this category would fill to the last line in the previous category.
              category_style_dict = {
                  grouped_df[category].columns[0]: {
                      k: v for k, v in style.items() if k != "fill"
                  }
              }
              category_style_dict.update(
                  {
                      col: style
                      for col in grouped_df[category].columns[1:]
                  }
              )
          else:
              category_style_dict = {
                  col: style for col in grouped_df[category].columns
              }
          y_col_style_dict.update(category_style_dict)
  
      grouped_df.columns = list(
          grouped_df.columns.get_level_values(1)
      )  # MultiIndex is not needed for plotting
      x_col = grouped_df.index.name
      grouped_df.reset_index(inplace=True)
      fig = plot_multivariate(
          grouped_df,
          x_col=x_col,
          y_col_style_dict=y_col_style_dict,
          xlabel=xlabel,
          ylabel=ylabel,
          title=title,
          showlegend=showlegend,
      )
      return fig
  
imports: import warnings
  from datetime import datetime
  from functools import partial
  from typing import Dict
  from typing import List
  from typing import Optional
  from typing import Union
  import numpy
  import pandas
  from greykite.common.constants import TIME_COL
  from greykite.common.constants import VALUE_COL
  from greykite.common.logging import LoggingLevelEnum
  from greykite.common.logging import log_message
  from greykite.common.time_properties import describe_timeseries
  from greykite.common.time_properties import get_canonical_data
  from greykite.common.viz.timeseries_plotting import add_groupby_column
  from greykite.common.viz.timeseries_plotting import flexible_grouping_evaluation
  from greykite.common.viz.timeseries_plotting import grouping_evaluation
  from greykite.common.viz.timeseries_plotting import plot_multivariate
  from greykite.common.viz.timeseries_plotting import plot_univariate
  from greykite.framework.constants import MEAN_COL_GROUP
  from greykite.framework.constants import OVERLAY_COL_GROUP
  from greykite.framework.constants import QUANTILE_COL_GROUP
label_desc: Use image node_id 10 for calling the UnivariateTimeSeries obj's underlying member method code with example usage: obj.plot_quantiles_and_overlays(groupby_time_feature, groupby_sliding_window_size, groupby_custom_column, show_mean, show_quantiles, show_overlays, overlay_label_time_feature, overlay_label_sliding_window_size, overlay_label_custom_column, center_values, value_col, mean_col_name, quantile_col_prefix, mean_style, quantile_style, overlay_style, xlabel, ylabel, title, showlegend) and returns: fig