The Join command takes multiple TimeSeries data structures and stores them in a single, new, TimeSeries data structure.

The Join command can also be invoked in a few other ways:

These alternative calling sequences provide no new functionality, just notational convenience.

All calling sequences described above accept any number of time series to be joined together. The command first determines what the data sets in the new time series object are going to be (see the discussion of the mergedatasets option, below). It then determines what times will be present in the new time series (see the discussion of the regulardates option, below). Finally, a Matrix encompassing all data is constructed, which is turned into a TimeSeries data structure.

mergedatasets = false, true, or force

This option determines how Join decides how the data sets will occur in the new time series object. If mergedatasets = false is passed, then every data set in the input time series will be a separate data set in the resulting time series. If mergedatasets = true (the default) then all data sets that have equal names (given by the headers option; see GetHeaders) will be merged. This is the default. If mergedatasets = force is given, then all first data sets in every time series will be merged together; all second data sets (if present) will be merged, and so on.

If some data sets are merged, then the resulting data set gets the name of the data set occurring first in the calling sequence. If there are multiple values for one time stamp for the same data set, then the valuetolerance option determines what happens.

valuetolerance = nonnegative real number or infinity

Whenever data sets are merged, there can be a range of dates where more than one data set has a value. If this is the case and the values differ by more than the value of the valuetolerance parameter (in absolute sense), then an error is issued. Otherwise, values from data sets in earlier arguments (further to the left in the calling sequence) will be overwritten by values from data sets in later arguments (further to the right in the calling sequence). The default value is 0, meaning that values differing in any way yield an error. If specifying infinity as the value for this option, values will always be overwritten without raising an error.

When one of the sets has missing data for a given date, it is not considered for this process.

regulardates = true or false

If the dates of two time series do not match up exactly, then Maple needs to make a choice: either include multiple slightly different dates, or move values from one or more time series to a slightly different date. If regulardates = true (the default), then Maple tries to determine a set of time stamps that are mostly regular - i.e., they have intervals of similar length between them. In particular, it finds the time series with the shortest intervals on average and tries to make all time series line up around multiples of that interval. This means, for example, that if monthly data is joined to quarterly data, that monthly data points will always be inserted in between the quarterly data, even if the monthly data has a more limited range. If the time stamps do not exactly line up, the datetolerance option, explained below, determines what difference between them is accepted.

If regulardates = false, then Maple simply tries to find relatively few time stamps that occur near the time stamps in the given time series. (How near is determined by the datetolerance option below.) This can be appropriate if you need to join weekly and monthly data, for example. Note, however, that most commands in the TimeSeriesAnalysis package assume that dates are regular.

datetolerance = nonnegative real number

This option, together with the regulardates option, determines what are the time stamps of the time series to be constructed. In particular, if one time series has time stamps on the last day of every month, and another has time stamps on the 28th of every month, one could include both dates and either insert alternating missing values in between, or interpolate - but it seems more likely that, say, January 28th and January 31st can be considered the same time point. The datetolerance option determines when dates are merged. The way it works is as follows: given a sequence $t_i$ of dates, Maple determines a time interval $t_i-\mathrm{\delta }..t_i+\mathrm{\delta }$ for every date $t_i$, where $\mathrm{\delta }$ is typically equal to $\frac{\left(t_{i+1}-t_{i-1}\right)\mathrm{datetolerance}}{2}$. It then ensures that for every $t_i$, there is a corresponding time stamp $T_k$ in the new time series such that $T_k$ is in the range $t_i-\mathrm{\delta }..t_i+\mathrm{\delta }$. If regulardates is true, then an error is raised if this is not possible within the constraints given. If regulardates is false, then extra time stamps are simply inserted.

Setting datetolerance=0 means different time stamps are never merged. If regulardates is false, then setting datetolerance equal to 1 or higher means that multiple dates from the same time series will have overlapping dates and is not recommended. (With time intervals that are not equally long, such as months, this is even possible for values of datetolerance that are a little less than 1.) If regulardates is true, this cannot happen. The default value is $0.05$.

interpolate = none, nearest, or linear

If dates are inserted in between values for a time series, then by default the result will not have values coming from that time series. This option offers the opportunity to insert values obtained by interpolation.

More precisely, suppose a data set has values $x_k$ and $x_{k+1}$ for dates $t_k$ and $t_{k+1}$. These are mapped to times $T_m$ and $T_{m+n}$, with $1<n$. For times $T_{m+i}$ with $0<i$ and $i<n$, the default option, interpolate = none, will not supply any values for the resulting data set. If the option interpolate = nearest is supplied, then the resulting data set's value for $T_{m+i}$ will get the value for $t_k$ if $i<\frac{n}{2}$ and the value for $t_{k+1}$ otherwise. If the option interpolate = linear is supplied, then the value will be determined by linear interpolation: the value for time $T_{m+i}$ is $x_k+\frac{i\left(x_{k+1}-x_k\right)}{n}$.

$\mathrm{with}\left(\mathrm{TimeSeriesAnalysis}\right)\&colon;$

$\mathrm{ts1}≔\mathrm{TimeSeries}\left(\left[\left[5.2\&comma;4.8\&comma;2.9\&comma;3.9\&comma;4.3\&comma;4.3\&comma;3.1\right]\&comma;\left[16.3\&comma;19.1\&comma;15.6\&comma;18.2\&comma;\mathrm{undefined}\&comma;17.7\&comma;19.6\right]\right]\&comma;\mathrm{headers}=\left[''A''\&comma;''B''\right]\&comma;\mathrm{frequency}=''monthly''\&comma;\mathrm{enddate}=''2011-10-30''\right)$

$\mathrm{ts1}≔\left[?\right]$

$\mathrm{ts2}≔\mathrm{TimeSeries}\left(\left[17.8\&comma;19.9\&comma;21.2\&comma;22.5\&comma;23.9\right]\&comma;\mathrm{header}=''B''\&comma;\mathrm{enddate}=''2012-01-31''\&comma;\mathrm{frequency}=''monthly''\right)$

$\mathrm{ts2}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts1}\&comma;\mathrm{ts2}\right)$

$\mathrm{ts3}≔\mathrm{Join}\left(\mathrm{ts1}\&comma;\mathrm{ts2}\right)$

Error, (in TimeSeries:-Join) for time 2011-09-30, new data set B has two candidate values, 17.7 and 17.8, which differ by more than valuetolerance (0)

$\mathrm{ts3}≔\mathrm{Join}\left(\mathrm{ts1}\&comma;\mathrm{ts2}\&comma;\mathrm{valuetolerance}=0.5\right)$

$\mathrm{ts3}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts3}\right)$

$\mathrm{ts4}≔\mathrm{Join}\left(\mathrm{ts1}\&comma;\mathrm{ts2}\&comma;\mathrm{datetolerance}=0\&comma;\mathrm{valuetolerance}=0.5\right)$

Error, (in TimeSeries:-interval_adjustment_helper) incompatible dates around 2011-10-31 00:00:00; consider increasing datetolerance

$\mathrm{ts4}≔\mathrm{Join}\left(\mathrm{ts2}\&comma;\mathrm{ts1}\&comma;\mathrm{valuetolerance}=0.5\&comma;\mathrm{datetolerance}=0\&comma;\mathrm{regulardates}=\mathrm{false}\right)$

$\mathrm{ts4}≔\left[?\right]$

$\mathrm{GetDates}\left(\mathrm{ts4}\right)$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts4}\right)$

$\mathrm{ts5}≔\mathrm{Join}\left(\mathrm{ts1}\&comma;\mathrm{ts2}\&comma;\mathrm{mergedatasets}=\mathrm{force}\&comma;\mathrm{valuetolerance}=\mathrm{\infty }\right)$

$\mathrm{ts5}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts5}\right)$

$\mathrm{ts6}≔⟨\mathrm{ts1}|\mathrm{ts2}⟩$

$\mathrm{ts6}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts6}\right)$

$\mathrm{ts7}≔\mathrm{ts2}\left[3..\right]$

$\mathrm{ts7}≔\left[?\right]$

$\mathrm{ts8}≔\mathrm{TimeSeries}\left(\left[4.9\&comma;4.8\&comma;2.4\&comma;4.0\&comma;\mathrm{undefined}\&comma;3.1\&comma;4.0\right]\&comma;\mathrm{frequency}=''monthly''\&comma;\mathrm{startdate}=''2011-11-30''\&comma;\mathrm{header}=''A''\right)$

$\mathrm{ts8}≔\left[?\right]$

$\mathrm{ts9}≔⟨\mathrm{ts1}\&comma;\mathrm{ts7}\&comma;\mathrm{ts8}⟩$

$\mathrm{ts9}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts9}\right)$

$\mathrm{ts10}≔\mathrm{ts1}\mathbf{union}\mathrm{ts7}\mathbf{union}\mathrm{ts8}$

$\mathrm{ts10}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts10}\right)$

$\mathrm{ts11}≔\mathrm{TimeSeries}\left(\left[8.7\&comma;10.1\&comma;10.9\&comma;9.4\&comma;10.7\&comma;9.5\&comma;9.6\&comma;12.2\&comma;9.1\&comma;9.8\&comma;11.7\&comma;11.7\&comma;10.9\&comma;10.6\&comma;10.8\&comma;11.2\&comma;\mathrm{undefined}\&comma;10.2\&comma;10.6\&comma;\mathrm{undefined}\&comma;9.8\&comma;10.8\&comma;10.5\&comma;10.1\&comma;9.5\&comma;9.4\&comma;10.4\&comma;11.5\&comma;9.4\&comma;12.1\right]\&comma;\mathrm{startdate}=''2011-11-01''\&comma;\mathrm{frequency}=''weekly''\&comma;\mathrm{header}=''C''\right)$

$\mathrm{ts11}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts11}\right)$

$\mathrm{ts12}≔\mathrm{Join}\left(\mathrm{ts8}\&comma;\mathrm{ts11}\&comma;\mathrm{regulardates}=\mathrm{false}\right)$

$\mathrm{ts12}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts12}\right)$

$\mathrm{ts13}≔\mathrm{Join}\left(\mathrm{ts8}\&comma;\mathrm{ts11}\&comma;\mathrm{interpolate}=\mathrm{nearest}\&comma;\mathrm{regulardates}=\mathrm{false}\right)$

$\mathrm{ts13}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts13}\right)$

$\mathrm{ts14}≔\mathrm{Join}\left(\mathrm{ts8}\&comma;\mathrm{ts11}\&comma;\mathrm{interpolate}=\mathrm{linear}\&comma;\mathrm{regulardates}=\mathrm{false}\right)$

$\mathrm{ts14}≔\left[?\right]$

$\mathrm{TimeSeriesPlot}\left(\mathrm{ts14}\right)$

The TimeSeriesAnalysis[Join] command was introduced in Maple 18.

For more information on Maple 18 changes, see Updates in Maple 18.