A series is a one-dimensional vector of numbers whose elements are initialized in groups or intervals.
series Sales = from 2010 : 0, from 2011 : 100000, from 2013 to 2016 : 150000;
In this example, the series is called Sales. Sales contains three intervals: one that has one element (corresponding to the year 2010), one that has two elements (corresponding to years 2011 and 2012), and one that has four elements (corresponding to years 2013, 2014, 2015, 2016).
A series has at least one interval definition that contains an expression that gives the number represented by the series in that interval. The interval definitions also contain the interval boundaries -- in this case 2010, 2011, 2013, and 2016. The lower bound of the first interval and the upper bound of the last interval define the lower and upper bounds of the series, and they must be constant expressions. The other interval boundaries are called intermediate interval boundaries, and they may be variable expressions. Only the upper bound for the last interval must be explicitly defined; the upper bounds for the other intervals are calculated by subtracting one from the lower bound of the next interval.
The interval bounds and subscripts must be integers, and they can cover any range that you designate, including negative numbers. Each interval boundary must exceed the previous one. All interval ranges must lie between -32768 and +32767. If necessary, DPL will truncate subscripts and interval bounds to integers.
A series also has a subscript (a way to reference particular elements of the series) which can range between the lower and upper boundaries of the series. In this example, the subscript may range from 2010 to 2016. A basic subscript refers directly to a particular element in the series. For example, the following refers to the value for Sales in 2013:
Sales[2013]
A relative subscript, contains a special identifier ($) that represents the current subscript of the series being initialized.
series Sales = from 2010 : 0, from 2011 to 2000 : Sales[$ - 1] + 10000;
In this case, when DPL evaluates the value of Sales for 2011, the $ sign stands for 2011, so DPL looks up the value of Sales for 2010 (that is, 2011 - 1) and adds 10,000.
You must initialize each element of a series, which means that each interval must be assigned an expression. The expression can include the names of variables previously defined in the model and any function supported by DPL. Unlike those of an array, DPL does not allow the elements of a series to be uninitialized.
In addition to using the $ sign in the name of a series element, you can use the $ sign to represent the number of the current index in an expression.
series Years = from 2010 to 2010: [$];
Most definitions in DPL can only reference objects defined earlier in a program. However DPL allows you to reference a series before defining it. That makes it possible to define several series recursively. In the following example, the definition of Series1 references Series2 before Series2 is defined.
series Series2; series Series1 = from 1: 1, from 2 to 10: Series2[$ - 1] + 1; series Series2 = from 1 to 10: Series1[$] * 2;
With these definitions, Series1[2] equals 3, Series2[2] equals 6, Series1[10] equals 1023, and Series2[10] equals 2046. The first definition in the example indicates that the variable Series2 is a series rather than an array. Because DPL assumes that forward referenced variables are series, this line is optional.
DPL allows you to define a value that depends on the current subscript of a series. Because the current subscript is known during the definition of a series, you can use a value defined this way as part of the definition of another series. For example, the following statements define one series in terms of the two above.
value X = Series1[$] * Series2[$]; series Series3 = from 1 to 10: X;
There are three ways to use a series in DPL:
- With a subscript that specifies one element of the series
- Without a subscript, as the argument of a function that converts the series into a single number
- With a specified subrange, as the argument of a function that converts the subrange into a single number
If a series has a subscript, the series can appear in an expression anywhere a value is permitted, and the subscript must be enclosed in brackets immediately following the series name. Series with relative subscripts can only appear in expressions that initialize other series or define values that will be used to initialize other series.
If a series does not have a subscript, the series must appear by itself (not as part of an expression) or with a subrange specification as the argument of a function. The name of a series without subscripts can appear as the argument of certain spreadsheet functions. These functions convert a series into a single number. When used as an argument in these functions, the series name is used by itself, without subscripts, or with a subrange specification and without any other operators or operands. This is the only way you can use a series in a DPL expression without subscripts. For example, the following expression uses a function that takes a series name as its argument.
@sum(Cash_Flow) / 2 - 100
The expression includes the spreadsheet function @sum (), which computes the total of the series' elements.
When a function argument is a series name without subscripts or with a subrange specification, it cannot be part of an expression. For example, the argument of the function @sum() in the following expression contains a series name with no subscript. It will cause DPL to generate an error message.
@sum(Cash_Flow/2) - 100 //Not a valid expression
Some spreadsheet functions have more than one argument. Some of these arguments must be a series name (by itself), and others can be expressions (possibly including a series with a subscript). No single argument, however, will contain a series name without a subscript within an expression. The following expression includes a spreadsheet function that computes the internal rate of return for a set of payments. The function's first argument is an expression that yields an initial guess for the internal rate of return. If the expression contains a series name, it must have a subscript. The second argument is the name of a series containing the payments. This argument cannot have a subscript.
1000 * @irr(1 / Cash_Flow[2000], Cash_Flow)
For example, you can refer to the this series in three ways:
series Cash_Flows= from 2010: 10000, from 2011 to 2019: Cash_Flow [$-1] *1.1;
- With a subscript, referring to a single element (CF2010 is 10000)
value CF2010 = Cash_Flow [2010];
- Without a subscript, referring to the entire series (CFTotal is 139703)
value CFTotal = @sum(Cash_Flow);
- With a subrange specification, referring to a selected subset of the elements in the series (CFSubtotal is 61873)
value CFSubTotal = @sum(Cash_Flow{2013..2016});
A series subrange is an array created from a portion of a series. A subrange specification looks similar to a reference to a single series element, except that curly braces { } are used instead of square brackets [ ] and the parameter is a pair of values or expressions separated by two periods (..) rather than a single number or expression.
The boundaries on the subrange may be variable expressions. This feature adds flexibility to the range of values that will be addressed during a model run, as the starting and ending position can vary dynamically depending on the states of events:
value StartPosition = 2013;
chance EndPosition.{2} = {.5}
= 2016, 2018;
value CFSum = @sum(Cash_Flow{StartPosition..EndPosition});
A series subrange consisting of a single element is not equivalent to a subscript reference to that element:
Cash_Flow{2011..2011} does not equal Cash_Flow[2011]
The two expressions refer to the same value. However, the first results in an array with one element, whereas the second results in a single value. The expression Cash_Flow{2011..2011} can be used where an array is expected (@npv (Cash_Flow{2011..2011}). The expression Cash_Flow [2011] can be used anywhere a single value is expected (Cash_Flow [2011] - 200).
When referring to a single element in a subrange, treat the subrange as a separate array. The expression
@index(Cash_Flow{2013..2016}, 2, 0)
and
Cash_Flow[2015]
refer to the same element.
Notice that, although the element is the sixth element in the series, it is the third element in the subrange array. (The @index function takes the series, column, and row as arguments, respectively.)
Versions: DPL Professional, DPL Enterprise, DPL Portfolio
See Also