class_docstr: Please read the `tutorial <tutorials/TimeSeries>` before reading this API doc.
  This class represents a general multivariate time series as a wrapper around
  a number of (optionally named) `UnivariateTimeSeries`. A `TimeSeries` object
  is initialized as ``time_series = TimeSeries(univariates)``, where
  ``univariates`` is either a list of `UnivariateTimeSeries`, or a dictionary
  mapping string names to their corresponding `UnivariateTimeSeries` objects.
  
  Because the individual ``univariates`` need not be sampled at the same times, an
  important concept for `TimeSeries` is *alignment*. We say that a `TimeSeries`
  is *aligned* if all of its univariates have observations sampled at the exact
  set set of times.
  
  One may access the `UnivariateTimeSeries` comprising this `TimeSeries` in four ways:
  
  1.  Iterate over the individual univariates using
  
      .. code-block:: python
  
          for var in time_series.univariates:
              # do stuff with each UnivariateTimeSeries var
  
  2.  Access an individual `UnivariateTimeSeries` by name as
      ``time_series.univariates[name]``. If you supplied unnamed univariates to
      the constructor (i.e. using a list), the name of a univariate will just
      be its index in that list.
  3.  Get the list of each univariate's name with ``time_series.names``.
  4.  Iterate over named univariates as
  
      .. code-block:: python
  
          for name, var in time_series.items():
              # do stuff
  
      Note that this is equivalent to iterating over
      ``zip(time_series.names, time_series.univariates)``.
  
  This class supports the following additional features as well:
  
  1.  Interoperability with ``pandas``
  
      -   ``df = time_series.to_pd()`` yields a time-indexed ``pd.DataFrame``,
          where each column (with the appropriate name) corresponds to a
          variable. Missing values are ``NaN``.
      -   ``time_series = TimeSeries.from_pd(df)`` takes a time-indexed
          ``pd.DataFrame`` and returns a corresponding `TimeSeries` object
          (missing values are handled appropriately). The order of
          ``time_series.univariates`` is the order of ``df.keys()``.
  
  2.  Automated alignment: ``aligned = time_series.align()`` resamples each of
      ``time_series.univariates`` so that they all have the same timestamps.
      By default, this is done by taking the union of all timestamps present
      in any individual univariate time series, and imputing missing values
      via interpolation. See the method documentation for details on how you
      may configure the alignment policy.
  3.  Transparent indexing and iteration for `TimeSeries` which have all
      univariates aligned (i.e. they all have the same timestamps)
  
      -   Get the length and shape of the time series (equal to the number of
          observations in each individual univariate). Note that if the time
          series is not aligned, we will return the length/shape of an equivalent
          ``pandas`` dataframe and emit a warning.
      -   Index ``time_series[i] = (times[i], (x1[i], ..., xn[i]))``
          (assuming ``time_series`` has ``n`` aligned univariates with timestamps
          ``times``, and ``xk = time_series.univariates[k-1].values``). Slice
          returns a `TimeSeries` object and works as one would expect.
      -   Assuming ``time_series`` has ``n`` variables, you may iterate with
  
          .. code-block:: python
  
              for t_i, (x1_i, ..., xn_i) in time_series:
                  # do stuff
  
          Notably, this lets you call ``times, val_vectors = zip(*time_series)``
  
  4.  Time-based queries for any time series
  
      -   Get the two sub `TimeSeries` before and after a timestamp ``t`` via
          ``left, right = time_series.bisect(t)``
      -   Get the sub `TimeSeries` between timestamps ``t0`` (inclusive) and
          ``tf`` (non-inclusive) via ``window = time_series.window(t0, tf)``
  
  5.  Concatenation: two `TimeSeries` may be concatenated (in time) as
      ``time_series = time_series_1 + time_series_2``.
  
  .. document special functions
  .. automethod:: __getitem__
  .. automethod:: __iter__
class_docstr_tok: ["Please","read","the","`","tutorial","<","tutorials\/TimeSeries",">","`","before","reading","this","API","doc",".","This","class","represents","a","general","multivariate","time","series","as","a","wrapper","around","a","number","of","(","optionally","named",")","`","UnivariateTimeSeries","`",".","A","`","TimeSeries","`","object","is","initialized","as","``","time_series","=","TimeSeries","(","univariates",")","``",",","where","``","univariates","``","is","either","a","list","of","`","UnivariateTimeSeries","`",",","or","a","dictionary","mapping","string","names","to","their","corresponding","`","UnivariateTimeSeries","`","objects",".","Because","the","individual","``","univariates","``","need","not","be","sampled","at","the","same","times",",","an","important","concept","for","`","TimeSeries","`","is","*","alignment","*",".","We","say","that","a","`","TimeSeries","`","is","*","aligned","*","if","all","of","its","univariates","have","observations","sampled","at","the","exact","set","set","of","times",".","One","may","access","the","`","UnivariateTimeSeries","`","comprising","this","`","TimeSeries","`","in","four","ways",":","1",".","Iterate","over","the","individual","univariates","using","..","code-block",":",":","python","for","var","in","time_series.univariates",":","#","do","stuff","with","each","UnivariateTimeSeries","var","2",".","Access","an","individual","`","UnivariateTimeSeries","`","by","name","as","``","time_series.univariates","[","name","]","``",".","If","you","supplied","unnamed","univariates","to","the","constructor","(","i.e",".","using","a","list",")",",","the","name","of","a","univariate","will","just","be","its","index","in","that","list",".","3",".","Get","the","list","of","each","univariate","'s","name","with","``","time_series.names","``",".","4",".","Iterate","over","named","univariates","as","..","code-block",":",":","python","for","name",",","var","in","time_series.items","(",")",":","#","do","stuff","Note","that","this","is","equivalent","to","iterating","over","``","zip","(","time_series.names",",","time_series.univariates",")","``",".","This","class","supports","the","following","additional","features","as","well",":","1",".","Interoperability","with","``","pandas","``","-","``","df","=","time_series.to_pd","(",")","``","yields","a","time-indexed","``","pd.DataFrame","``",",","where","each","column","(","with","the","appropriate","name",")","corresponds","to","a","variable",".","Missing","values","are","``","NaN","``",".","-","``","time_series","=","TimeSeries.from_pd","(","df",")","``","takes","a","time-indexed","``","pd.DataFrame","``","and","returns","a","corresponding","`","TimeSeries","`","object","(","missing","values","are","handled","appropriately",")",".","The","order","of","``","time_series.univariates","``","is","the","order","of","``","df.keys","(",")","``",".","2",".","Automated","alignment",":","``","aligned","=","time_series.align","(",")","``","resamples","each","of","``","time_series.univariates","``","so","that","they","all","have","the","same","timestamps",".","By","default",",","this","is","done","by","taking","the","union","of","all","timestamps","present","in","any","individual","univariate","time","series",",","and","imputing","missing","values","via","interpolation",".","See","the","method","documentation","for","details","on","how","you","may","configure","the","alignment","policy",".","3",".","Transparent","indexing","and","iteration","for","`","TimeSeries","`","which","have","all","univariates","aligned","(","i.e",".","they","all","have","the","same","timestamps",")","-","Get","the","length","and","shape","of","the","time","series","(","equal","to","the","number","of","observations","in","each","individual","univariate",")",".","Note","that","if","the","time","series","is","not","aligned",",","we","will","return","the","length\/shape","of","an","equivalent","``","pandas","``","dataframe","and","emit","a","warning",".","-","Index","``","time_series","[","i","]","=","(","times","[","i","]",",","(","x1","[","i","]",",","...",",","xn","[","i","]",")",")","``","(","assuming","``","time_series","``","has","``","n","``","aligned","univariates","with","timestamps","``","times","``",",","and","``","xk","=","time_series.univariates","[","k-1","]",".values","``",")",".","Slice","returns","a","`","TimeSeries","`","object","and","works","as","one","would","expect",".","-","Assuming","``","time_series","``","has","``","n","``","variables",",","you","may","iterate","with","..","code-block",":",":","python","for","t_i",",","(","x1_i",",","...",",","xn_i",")","in","time_series",":","#","do","stuff","Notably",",","this","lets","you","call","``","times",",","val_vectors","=","zip","(","*","time_series",")","``","4",".","Time-based","queries","for","any","time","series","-","Get","the","two","sub","`","TimeSeries","`","before","and","after","a","timestamp","``","t","``","via","``","left",",","right","=","time_series.bisect","(","t",")","``","-","Get","the","sub","`","TimeSeries","`","between","timestamps","``","t0","``","(","inclusive",")","and","``","tf","``","(","non-inclusive",")","via","``","window","=","time_series.window","(","t0",",","tf",")","``","5",".","Concatenation",":","two","`","TimeSeries","`","may","be","concatenated","(","in","time",")","as","``","time_series","=","time_series_1","+","time_series_2","``",".","..","document","special","functions","..","automethod",":",":","__getitem__","..","automethod",":",":","__iter__"]
docstr: Helper function that converts [(t_1[i], x_1[i]), ..., (t_k[i], x_k[i])],
  i.e. [var[i] for var in self.univariates], into the desired output form
  (t_1[i], (x_1[i], ..., x_k[i])).
code: def _txs_to_vec(txs):
      """
      Helper function that converts [(t_1[i], x_1[i]), ..., (t_k[i], x_k[i])],
      i.e. [var[i] for var in self.univariates], into the desired output form
      (t_1[i], (x_1[i], ..., x_k[i])).
      """
      return txs[0][0], tuple(tx[1] for tx in txs)
  
imports: from bisect import bisect_left, bisect_right
  import itertools
  import logging
  from typing import Any, Callable, Dict, Iterable, Mapping, Sequence, Tuple, Union
  import warnings
  import numpy
  import pandas
  from merlion.utils.misc import ValIterOrderedDict
  from merlion.utils.resample import AggregationPolicy, AlignPolicy, MissingValuePolicy, get_date_offset, infer_granularity, reindex_df, to_pd_datetime, to_timestamp, to_offset
label_desc: Use image node_id 12 for calling the TimeSeries obj's underlying member method code with example usage: obj._txs_to_vec(txs) and returns: txs,  tuple