class_docstr: Abstract interface for data aggregation functionality for plotly figures.
class_docstr_tok: ["Abstract","interface","for","data","aggregation","functionality","for","plotly","figures","."]
docstr: Add traces to the figure.
  
  !!! note
  
      Make sure to look at the [`add_trace`][figure_resampler.figure_resampler_interface.AbstractFigureAggregator.add_trace] function for more info about
      **speed optimization**, and dealing with not ``high-frequency`` data, but
      still want to resample / limit the data to the front-end view.
  
  Parameters
  ----------
  data : List[BaseTraceType  |  dict]
      A list of trace specifications to be added.
      Trace specifications may be either:
  
        - Instances of trace classes from the plotly.graph_objs
          package (e.g plotly.graph_objs.Scatter, plotly.graph_objs.Bar).
        - Dicts where:
  
            - The 'type' property specifies the trace type (e.g.
              'scatter', 'bar', 'area', etc.). If the dict has no 'type'
              property then 'scatter' is assumed.
            - All remaining properties are passed to the constructor
              of the specified trace type.
  max_n_samples : None | List[int] | int, optional
        The maximum number of samples that will be shown for each trace.
        If a single integer is passed, all traces will use this number. If this
        variable is not set; ``_global_n_shown_samples`` will be used.
  downsamplers : None | List[AbstractAggregator] | AbstractAggregator, optional
      The downsampler that will be used to aggregate the traces. If a single
      aggregator is passed, all traces will use this aggregator.
      If this variable is not set, ``_global_downsampler`` will be used.
  gap_handlers : None | List[AbstractGapHandler] | AbstractGapHandler, optional
      The gap handler that will be used to aggregate the traces. If a single
      gap handler is passed, all traces will use this gap handler.
      If this variable is not set, ``_global_gap_handler`` will be used.
  limit_to_views : None | List[bool] | bool, optional
      List of limit_to_view booleans for the added traces. If set to True the
      trace's datapoints will be cut to the corresponding front-end view, even if
      the total number of samples is lower than ``max_n_samples``.
      If a single boolean is passed, all to be added traces will use this value,
      by default False.
  
      Remark that setting this parameter to True ensures that low frequency traces
      are added to the ``hf_data`` property.
  check_nans : None | List[bool] | bool, optional
      List of check_nans booleans for the added traces. If set to True, the
      trace's datapoints will be checked for NaNs. If a single boolean is passed,
      all to be added traces will use this value, by default True.
  
      As this is a costly operation, it is recommended to set this parameter to
      False if the data is known to contain no NaNs (or when the downsampler can
      handle NaNs, e.g., EveryNthPoint). This will considerably speed up the graph
      construction time.
  **traces_kwargs: dict
      Additional trace related keyword arguments.
      e.g.: rows=.., cols=..., secondary_ys=...
  
      !!! info "See Also"
  
          [`Figure.add_traces`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure.add_traces>) docs.
  
  Returns
  -------
  BaseFigure
      The Figure on which ``add_traces`` was called on; i.e. self.
docstr_tok: ["Add","traces","to","the","figure",".","!","!","!","note","Make","sure","to","look","at","the","[","`","add_trace","`","]","[","figure_resampler.figure_resampler_interface.AbstractFigureAggregator.add_trace","]","function","for","more","info","about","*","*","speed","optimization","*","*",",","and","dealing","with","not","``","high-frequency","``","data",",","but","still","want","to","resample","\/","limit","the","data","to","the","front-end","view",".","Parameters","--","--","--","--","--","data",":","List","[","BaseTraceType","|","dict","]","A","list","of","trace","specifications","to","be","added",".","Trace","specifications","may","be","either",":","-","Instances","of","trace","classes","from","the","plotly.graph_objs","package","(","e.g","plotly.graph_objs.Scatter",",","plotly.graph_objs.Bar",")",".","-","Dicts","where",":","-","The","'type","'","property","specifies","the","trace","type","(","e.g",".","'scatter","'",",","'bar","'",",","'area","'",",","etc.",")",".","If","the","dict","has","no","'type'","property","then","'scatter","'","is","assumed",".","-","All","remaining","properties","are","passed","to","the","constructor","of","the","specified","trace","type",".","max_n_samples",":","None","|","List","[","int","]","|","int",",","optional","The","maximum","number","of","samples","that","will","be","shown","for","each","trace",".","If","a","single","integer","is","passed",",","all","traces","will","use","this","number",".","If","this","variable","is","not","set",";","``","_global_n_shown_samples","``","will","be","used",".","downsamplers",":","None","|","List","[","AbstractAggregator","]","|","AbstractAggregator",",","optional","The","downsampler","that","will","be","used","to","aggregate","the","traces",".","If","a","single","aggregator","is","passed",",","all","traces","will","use","this","aggregator",".","If","this","variable","is","not","set",",","``","_global_downsampler","``","will","be","used",".","gap_handlers",":","None","|","List","[","AbstractGapHandler","]","|","AbstractGapHandler",",","optional","The","gap","handler","that","will","be","used","to","aggregate","the","traces",".","If","a","single","gap","handler","is","passed",",","all","traces","will","use","this","gap","handler",".","If","this","variable","is","not","set",",","``","_global_gap_handler","``","will","be","used",".","limit_to_views",":","None","|","List","[","bool","]","|","bool",",","optional","List","of","limit_to_view","booleans","for","the","added","traces",".","If","set","to","True","the","trace","'s","datapoints","will","be","cut","to","the","corresponding","front-end","view",",","even","if","the","total","number","of","samples","is","lower","than","``","max_n_samples","``",".","If","a","single","boolean","is","passed",",","all","to","be","added","traces","will","use","this","value",",","by","default","False",".","Remark","that","setting","this","parameter","to","True","ensures","that","low","frequency","traces","are","added","to","the","``","hf_data","``","property",".","check_nans",":","None","|","List","[","bool","]","|","bool",",","optional","List","of","check_nans","booleans","for","the","added","traces",".","If","set","to","True",",","the","trace","'s","datapoints","will","be","checked","for","NaNs",".","If","a","single","boolean","is","passed",",","all","to","be","added","traces","will","use","this","value",",","by","default","True",".","As","this","is","a","costly","operation",",","it","is","recommended","to","set","this","parameter","to","False","if","the","data","is","known","to","contain","no","NaNs","(","or","when","the","downsampler","can","handle","NaNs",",","e.g.",",","EveryNthPoint",")",".","This","will","considerably","speed","up","the","graph","construction","time",".","*","*","traces_kwargs",":","dict","Additional","trace","related","keyword","arguments",".","e.g",".",":","rows=","..",",","cols=","...",",","secondary_ys=","...","!","!","!","info","``","See","Also","''","[","`","Figure.add_traces","`","]","(","https",":","\/\/plotly.com\/python-api-reference\/generated\/plotly.graph_objects.Figure.html","#","plotly.graph_objects.Figure.add_traces",">",")","docs",".","Returns","--","--","--","-","BaseFigure","The","Figure","on","which","``","add_traces","``","was","called","on",";","i.e",".","self","."]
code: def add_traces(
      self,
      data: List[BaseTraceType | dict] | BaseTraceType | Dict,
      max_n_samples: None | List[int] | int = None,
      downsamplers: None
      | List[AbstractAggregator]
      | AbstractAggregator = None,
      gap_handlers: None
      | List[AbstractGapHandler]
      | AbstractGapHandler = None,
      limit_to_views: List[bool] | bool = False,
      check_nans: List[bool] | bool = True,
      **traces_kwargs,
  ):
      """Add traces to the figure.
  
      !!! note
  
          Make sure to look at the [`add_trace`][figure_resampler.figure_resampler_interface.AbstractFigureAggregator.add_trace] function for more info about
          **speed optimization**, and dealing with not ``high-frequency`` data, but
          still want to resample / limit the data to the front-end view.
  
      Parameters
      ----------
      data : List[BaseTraceType  |  dict]
          A list of trace specifications to be added.
          Trace specifications may be either:
  
            - Instances of trace classes from the plotly.graph_objs
              package (e.g plotly.graph_objs.Scatter, plotly.graph_objs.Bar).
            - Dicts where:
  
                - The 'type' property specifies the trace type (e.g.
                  'scatter', 'bar', 'area', etc.). If the dict has no 'type'
                  property then 'scatter' is assumed.
                - All remaining properties are passed to the constructor
                  of the specified trace type.
      max_n_samples : None | List[int] | int, optional
            The maximum number of samples that will be shown for each trace.
            If a single integer is passed, all traces will use this number. If this
            variable is not set; ``_global_n_shown_samples`` will be used.
      downsamplers : None | List[AbstractAggregator] | AbstractAggregator, optional
          The downsampler that will be used to aggregate the traces. If a single
          aggregator is passed, all traces will use this aggregator.
          If this variable is not set, ``_global_downsampler`` will be used.
      gap_handlers : None | List[AbstractGapHandler] | AbstractGapHandler, optional
          The gap handler that will be used to aggregate the traces. If a single
          gap handler is passed, all traces will use this gap handler.
          If this variable is not set, ``_global_gap_handler`` will be used.
      limit_to_views : None | List[bool] | bool, optional
          List of limit_to_view booleans for the added traces. If set to True the
          trace's datapoints will be cut to the corresponding front-end view, even if
          the total number of samples is lower than ``max_n_samples``.
          If a single boolean is passed, all to be added traces will use this value,
          by default False.\n
          Remark that setting this parameter to True ensures that low frequency traces
          are added to the ``hf_data`` property.
      check_nans : None | List[bool] | bool, optional
          List of check_nans booleans for the added traces. If set to True, the
          trace's datapoints will be checked for NaNs. If a single boolean is passed,
          all to be added traces will use this value, by default True.\n
          As this is a costly operation, it is recommended to set this parameter to
          False if the data is known to contain no NaNs (or when the downsampler can
          handle NaNs, e.g., EveryNthPoint). This will considerably speed up the graph
          construction time.
      **traces_kwargs: dict
          Additional trace related keyword arguments.
          e.g.: rows=.., cols=..., secondary_ys=...
  
          !!! info "See Also"
  
              [`Figure.add_traces`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure.add_traces>) docs.
  
      Returns
      -------
      BaseFigure
          The Figure on which ``add_traces`` was called on; i.e. self.
  
      """
      # note: Plotly its add_traces also a allows non list-like input e.g. a scatter
      # object; the code below is an exact copy of their internally applied parsing
      if not isinstance(data, (list, tuple)):
          data = [data]
  
      # Convert each trace into a BaseTraceType object
      data = [
          self._data_validator.validate_coerce(trace)[0]
          if not isinstance(trace, BaseTraceType)
          else trace
          for trace in data
      ]
  
      # First add a UUID, as each (even the non-hf_data traces), must contain this
      # key for comparison. If the trace already has a UUID, we will keep it.
      for trace in data:
          uuid_str = str(uuid4()) if trace.uid is None else trace.uid
          trace.uid = uuid_str
  
      # Convert the data properties
      if (
          isinstance(max_n_samples, (int, np.integer))
          or max_n_samples is None
      ):
          max_n_samples = [max_n_samples] * len(data)
      if (
          isinstance(downsamplers, AbstractAggregator)
          or downsamplers is None
      ):
          downsamplers = [downsamplers] * len(data)
      if (
          isinstance(gap_handlers, AbstractGapHandler)
          or gap_handlers is None
      ):
          gap_handlers = [gap_handlers] * len(data)
      if isinstance(limit_to_views, bool):
          limit_to_views = [limit_to_views] * len(data)
      if isinstance(check_nans, bool):
          check_nans = [check_nans] * len(data)
  
      zipped = zip(
          data,
          max_n_samples,
          downsamplers,
          gap_handlers,
          limit_to_views,
          check_nans,
      )
      for (
          i,
          (
              trace,
              max_out,
              downsampler,
              gap_handler,
              limit_to_view,
              check_nan,
          ),
      ) in enumerate(zipped):
          if (
              trace.type.lower() not in self._high_frequency_traces
              or self._hf_data.get(trace.uid) is not None
          ):
              continue
  
          max_out_s = (
              self._global_n_shown_samples
              if max_out is None
              else max_out
          )
          if not limit_to_view and (
              trace.y is None or len(trace.y) <= max_out_s
          ):
              continue
  
          dc = self._parse_get_trace_props(trace, check_nans=check_nan)
          self._hf_data[trace.uid] = self._construct_hf_data_dict(
              dc,
              trace=trace,
              downsampler=downsampler,
              gap_handler=gap_handler,
              max_n_samples=max_out,
              offset=i,
          )
  
          # convert the trace into a dict, and only withholds the non-hf props
          trace = trace._props
          trace = {
              k: trace[k]
              for k in set(trace.keys()).difference(set(dc._fields))
          }
  
          # update the trace data with the HF props
          trace = self._check_update_trace_data(trace)
          assert trace is not None
          data[i] = trace
  
      return super(self._figure_class, self).add_traces(
          data, **traces_kwargs
      )
  
imports: from __future__ import annotations
  import itertools
  import re
  from abc import ABC
  from collections import namedtuple
  from copy import copy
  from typing import Dict, Iterable, List, Optional, Tuple, Union
  from uuid import uuid4
  import dash
  import numpy
  import pandas
  import plotly.graph_objects
  from pandas.io.json._normalize import nested_to_record
  from plotly.basedatatypes import BaseFigure, BaseTraceType
  from ..aggregation import AbstractAggregator, MedDiffGapHandler, MinMaxLTTB
  from ..aggregation.aggregation_interface import DataPointSelector
  from ..aggregation.gap_handler_interface import AbstractGapHandler
  from ..aggregation.plotly_aggregator_parser import PlotlyAggregatorParser
  from .utils import round_number_str, round_td_str
label_desc: Use image node_id 15 for calling the AbstractFigureAggregator obj's underlying member method code with example usage: obj.add_traces(data, max_n_samples, downsamplers, gap_handlers, limit_to_views, check_nans) and returns: super