SPLICE is used to combine two or more timeseries into one. You may choose which one of these timeseries is "primary" (keeps its values): default is the last timeseries stated. The SPLICE statement splices all available observations, and hence is not called with a time period. If you need to truncate the period of the resulting timeseries, use a subsequent TRUNCATE, or alternatively use the in-built function splice().

You may splice on a single period or a time interval. If no time period(s) is provided, all overlapping observations are used for splicing.

Syntax

splice <FIRST N=... TYPE=...> ... ;

splice y = x1 x2 x3 ... ;
splice y = x1 t1 x2 t2 x3 ... ;

splice y = x1 t1 t2 x2 t3 t4 x3 ... ;

y	The new timeseries made from the variables on the right-hand side of =.
x1, x2, ...	The timeseries that are to be spliced into the left-hand side timeseries.
t1, t2, ...	(Optional). Time periods. If on the right-hand side two timeseries are separated by one date, this date is used as the splicing date. If there are two dates, the indicated time interval is used for splicing. A statement like splice y = x1 2010q2 x2; is essentially short-hand for splice y = x1 2010q2 2010q2 x2;. If no time period is stated between two of the right-hand side series, Gekko tries to splice using as many common observations as possible.
FIRST	(Optional). Uses the first timeseries as "primary" (keeps its values). Using <first> is equivalent to <n=1>. Using the last timeseries is default.
LAST	(Optional). Since <last> is already default, this option only has cosmetic use.
N=	(Optional). Sets the timeseries number (1, 2, ... , n) to use as "primary" (keeps its values). Using <n=1> is equivalent to using <first>. Using the last timeseries is default.
TYPE=	(Optional). Choose type of smoothing: rel1, rel2, rel2 or abs. Below the types are described (example with three overlapping observations): •rel1: (Default). Ratio of averages used for a relative adjustment. The formula used for the relative correction factor R = ((y1 + y2 + y3)/3) / ((x1 + x2 + x3)/3). •rel2: Average ratio used for a relative adjustment. The formula used for the relative correction factor is R = (y1/x1 + y2/x2 + y3/x3)/3. •rel3: All values are first transformed with log(), then a SPLICE with <type=abs> is computed, and finally all values are transformed back with exp(). Because of the log(), negative values will not work. The type is quite similar to rel2, except in essence using geometric rather than arithmetic averages. •abs: Average difference is used for an absolute adjustment. This is advised for timeseries that can be 0 or negative, and where the levels of the timeseries are comparable. The formula used for the absolute correction factor is D = (y1 + y2 + y3)/3 - (x1 + x2 + x3)/3. Note: if you are using just one overlapping period, rel1, rel2 and rel3 are equivalent.

•If a variable on the right-hand side of = is stated without databank, Gekko may look for it in the list of open databanks (if databank search is active, cf. MODE).

•Looping: with a list like for instance #m = a, b;, you may use for string %i = #m; splice y{%i} = x1{%i} x2{%i}; end; to splice x1a and x2a into ya, and x1b and x2b into yb.

Methodology

Consider five overlapping timeseries x1-x5, as shown below. If you use splice y = x1 x2 x3 x4 x5;, Gekko will per default first use the levels of x5 (the last series) as "primary" y values. It will then move to the left to x4 and "glue" these values on y (using the overlapping observations to adjust). This is repeated left-wise for x3, x2, and finally x1. The resulting y series is shown, too (note how the internal period delimiters in y reflect start periods of x2-x5).

clip0142

If, instead, splice <n=3> y = x1 x2 x3 x4 x5; is used, x3 is used as "primary" y values. Then left-wise from x3, first x2 and then x1 are glued on. Finally, right-wise from x3, first x4 and then x5 are glued on.

clip0143

Note that the internal period delimiters in y are now different (and the levels will usually be so, too). The delimiters now reflect x2 and x3 start periods on the left, and x3 and x4 end periods on the right.

Example

Consider these three overlapping timeseries x1, x2 and x3.

clip0147

These series are very dissimilar and not exactly obvious candidates for splicing, but we will use them for illustrative purposes, cf. the following example:

reset;
time 2002 2012;
x1 <2002 2006> = 21, 22, 23, 24, 25;
x2 <2004 2010> = 41, 42, 43, 44, 45, 46, 47;
x3 <2008 2012> = 61, 62, 63, 64, 65;
splice y1 = x1 2006 x2;
splice y2 = x1 2005 2006 x2;
splice y3 = x1 x2; //all common observations
splice y4 = x1 x2 x3; //multi-splice
splice <n=2> y5 = x1 x2 x3; //second series is "primary"
splice <first> y6 = x1 x2 x3; //first series is "primary"
prt <n> y1, y2, y3, x1, x2;
prt <n> y4, y5, y6, x1, x2, x3;

For y1, the year 2006 is used as splice year, whereas for y2, the period 2005-2006 is used. For y3, all common observations are used (2004-2006). Default is that the levels of the last series are kept.

Levels:

y1 y2 y3 x1 x2

2002 36.1200 36.4286 36.7500 21.0000 M

2003 37.8400 38.1633 38.5000 22.0000 M

2004 39.5600 39.8980 41.0000 23.0000 41.0000

2005 41.2800 42.0000 42.0000 24.0000 42.0000

2006 43.0000 43.0000 43.0000 25.0000 43.0000

2007 44.0000 44.0000 44.0000 M 44.0000

2008 45.0000 45.0000 45.0000 M 45.0000

2009 46.0000 46.0000 46.0000 M 46.0000

2010 47.0000 47.0000 47.0000 M 47.0000

clip0146

The above figure illustrates how the attachment is done (remember that y1 splices on 2006, y2 splices on 2005-2006, and y3 splices on 2004-2006). For y1, x1 attaches cleanly to x2 in 2006. For y2 and y3, the attachement is done over a period range (2005-2006 and 2004-2006, respectively). For instance, in 2002 and 2003, the blue y3 series is lower than it would be if y3 was attached on the year 2004 only (and this is because x1 is growing and x2 is decreasing).

The multi-spliced series y4, y5 and y6 look like this:

clip0148

Again, there are some "funny" movements right before/after the attachment years, which has to do with overlapping observations being used and the fact the the x1-x3 series are so dissimilar. Also note that relative splicing is used here, not absolute.

Note

You may alternatively use the splice() function, for instance y1 = splice(x1, 2006, x2); But beware that this function respects the local/global time period when putting values into y1, so the splice() values will not be put into y1 outside of the local/global time period. But apart from this truncating of the function output values, the function works just like SPLICE.

Related statements

SMOOTH