B Appendix – Rules Function Reference Guide
This appendix provides references for rule functions, including:
Syntax and Design
This section provides the syntax and design of functions, procedures, modifiers, and keywords that are used in expressions in the RPASCE calculation engine. There are important distinctions between each of these definitions.
Functions
Functions are separated into two types: single result functions and multiple result functions.
Single Result Functions
Mechanisms for performing operations within an expression that are controlled and executed by the calculation engine.
-
Functions are most commonly used in RPASCE.
-
Most functions in base RPASCE return only a single measure.
-
Calculation engine controls and runs the evaluation of a function.
-
Functions may be used in expressions with other functions and keywords.
Multiple Result Functions
Similar to the features and behavior of single result functions, but with semantic and syntactic differences.
-
There can be more than one left-hand side (result) measure that can be specified implicitly by position in the expression or explicitly by label.
-
Left-hand side measures must be at same intersection; however, the calendar hierarchy can be dropped or added.
-
The results from a multiple result function cannot be used as arguments to another function, nor can the results be chained with other operations to form long expression.
-
Expressions can be used as arguments to multiple result functions.
-
Multiple result functions cannot be part of a cycle group.
Procedures
Procedures are mechanisms for performing operations in an expression where the calculation engine controls the execution, which is performed by the procedure itself.
-
Procedures can only use measures or scalars
-
Procedure runs the evaluation (instead of RPASCE/calculation engine), but the calculation engine still controls protection processing, sequence of calculation, when the procedure is called, and so on.
-
Procedures can have multiple arguments on the left-hand and right-hand sides.
-
Procedures cannot be used with functions, other procedures, keywords, and certain modifiers.
-
Because of their flexibility and the control available to the developer, procedures can be used for a wide variety of special calculations and activities.
-
Procedures require a different syntax. The syntax uses “<-“ instead of “=" in the expression.
Modifiers
Modifiers directly modify the source or destination of measures, to override the level, aggregation type, position, and so on.
Modifier Syntax
<measure>.<modifier>
Keywords
Keywords appear in expressions or as arguments inside functions to return specific data values.
Syntax Conventions
The syntax is as quick and straightforward to implement as possible. Function names, keywords, and so on are currently in lowercase.
Keywords are allowed, but they are kept to a minimum. Function parameters are comma separated and may be optional; however, they are positional, so that the absence of a parameter needs to be specified by commas if a subsequent parameter is supplied.
Table B-1 displays the syntax conventions used in this procedure.
Table B-1 Syntax Conventions
Indicator | Definition |
---|---|
[…] |
All options listed in brackets are optional. |
{…|…} |
Options listed in “{}" with “|" separators are mutually exclusive (either/or). |
{…,…} |
Options listed in “{}" with “," separators way are a complete set. |
Bold |
Bold indicate labels. |
Italics |
Italics indicate a temporary placeholder for a constant or a measure. |
Italics/meas |
This indicates that the placeholder can be either a constant or a measure. |
Bold Italics |
This indicates a numeric placeholder for the dynamic portion of a label. Usually a number from 1 to N. |
Normal |
Normal text signifies required information. |
Underlined |
This convention is used to identify the function or procedure name. |
The following is the functional syntax used in this guide:
-
Large square brackets [ ] are used to indicate an optional parameter.
-
Small square brackets [ ] are part of the expression syntax and are used to specify a hierarchy, dimension, and/or position.
-
Large braces { } indicate a choice where one of the items (which will be separated by a pipe sign "|") must be selected.
-
Small braces {} are part of the expression syntax, and are used to specify a measure set for functions that accept a variable number of arguments (that is, {<measureset>}).
-
Parameters of a specific type (such as expressions or dimension names) are shown in angle brackets <>.
-
A plus “+" sign is used to specify an intersection, which is done by connecting two or more dimension specifications.
-
Keywords, modifiers, function names, and procedure names are shown in bold.
Specification of Hierarchy, Dimension, or Position
Many functions in RPASCE require the specification of a hierarchy, dimension, or a combination thereof, to define the level at which an expression is evaluated. When defining the hierarchy and dimension names in expressions square brackets [ ] must be used.
In the document, the following syntax is used to designate a hierarchy and dimension:
Hierarchy, Dimension, and Position Syntax
[<hierarchy>].[<dimension>].[[<position>]]
Note:
Position is noted as optional because it can only be specified in a limited number of functions.
For simplicity of parsing and clarity of rule writing, the <hierarchy>
must be supplied in all cases, even when, as in calendar index functions, it might be implied from the context. Functions that require a hierarchy and dimension specification have standard validation rules whereby [<hierarchy>]
must be a valid hierarchy name, [<dimension>]
must be a valid dimension in [<hierarchy>]
, and [<position>]
must be a valid position name in [<dimension>]
. If the position name starts with a number, the position name must be nested in a pair of double quotes. In some functions or procedures, one of the hierarchical keywords top, bottom, or current (used conditionally based on context) can be used to specify the dimension. Should this validation fail, an error is generated.
Function Inverses
Some functions (such as cover) have what are referred to as "inverse" functions. This is required, as all expressions in a rule group must be algorithmic inverses of each other. Each function states whether it has an inverse, and, if so, what the syntax of the inverse is.
An inverse function is only relevant when the function encompasses the whole of the expression. Functions embedded in longer expressions do not have inverses, though the expression itself may have an inverse if the measure being "solved" for is not an input into the function. Functions that have inverses usually have enough scope in their syntax to cover the eventualities that would typically cause them to be embedded in longer expressions (such as code to prevent an error result).
Functions with Multiple Results
The following special syntax should be used for functions with multiple results.
The left-hand side measures in a multiple result expression are comma-separated and can be identified by a labeling mechanism.
Label Syntax
<measure>:<label>
Valid label names are specified by the multiple result function syntax. If a multiple result function specifies valid labels, the function can be used in an expression without specifying all possible results. The multiple result function itself is aware of which results are being stored and may be able to run faster by skipping the computation of unneeded results.
Special Handling for Functions
There are several keywords and functions that have special control flow over the evaluation of the expression.
Error Handling
RPASCE has no facility for holding an error value for a cell. Should the evaluation of any expression, or clause in an expression, result in an error, the value for the cell or clause will be the naval.
Note:
It is good programming practice to check for any clauses that may return an error, and the prefer function provides a way to specify the behavior under these circumstances. Some functions have their own implicit error handling.
Keyword: if
Used for handling conditional logic and masking updates within expressions.
Syntax
if(<condition>, <use-expression>, <else-expression>)
where <condition>
is any valid Boolean expression. <use-expression>
and <else-expression>
are any valid expressions that are evaluated based on the result of <condition>
; one (and only one) of these expressions can contain the keyword ignore. <use-expression>
is evaluated when the result of <condition>
is true; <else-expression>
is evaluated when the result of <condition>
is not true.
<expression>
is any valid expression. ignore is a keyword that is used to indicate that the entire expression is not to be evaluated (that is, masking the update to the entire expression).
Note:
The use of ignore can only be used in either the <use-expression>
or <else-expression>
, but not both.
The use of ignore can only be used in either the <use-expression>
or <else-expression>
, but not both.
The use of ignore always flags the expression as a masked update – this will always prevent the expression from being evaluated or involved with aggregations when the condition is not met. To reiterate, note that the entire expression is not evaluated, not just the sub-expression that uses the if clause. When ignore is used in expression where the LHS measure is modified with the master keyword (typically in a commit rule group), then the <condition>
must be a Boolean measure (in other words, not an expression). This syntactical restriction is validated when the expression is parsed.
if clauses can be nested without restrictions but must be enclosed with parentheses when used more than once within an expression.
Examples:
Conditional logic:
-
BOP =
if(current == first, SeasOP, lag(EOP))
-
OTB =
if(ProjEOP > PlanEOP, 0, PlanRecpt – OnOrder)
Masked update with a single expression:
-
SalesOP = if(Approved, SalesWP, ignore)
Updates Sales for the Original Plan version to the value in the Working Plan version when the Boolean measure Approved is set to true. ignore designates that no update is made to
SalesOP
if the Approved measure is false. This is functionally equivalent to the next example. -
SalesOP = if(NotApproved, ignore, SalesWP)
Does not update the measure
SalesOP
with the values from the measureSalesWP
when the Boolean measureNotApproved
is true. -
Note the distinctly different behavior between the following similar expressions:
-
a = b + (if(<condition>, c, ignore))
This is an example of a masked update where no update is made to measure a if the condition is not met (that is, the entire expression is not evaluated).
-
a = b + (if(<condition>,c, 0))
This is an example of conditional logic where an else clause is provided and the expression is always evaluated, thus
a
is always updated to eitherb
orb+c
.
-
Keyword: prefer
Returns the first non-error value from a series of expressions.
The primary use is to enable the capture and appropriate calculation of error conditions.
Syntax
prefer(<expression1>, <expression2> [, <expression3> … <expressionn>])
Where < expression1-n>
are expressions which return values of the appropriate data type. The function returns the value of the first of the expressions that does not generate an error when it is evaluated. It is good coding practice to use a prefer function around any clause of an expression, which could potentially generate an error.
Inverse
The prefer function does not have an inverse.
Examples:
-
prefer(A/B, 100)
This example returns the value of A divided by B, unless that generates an error (as it would if B is zero), when it returns 100.
-
prefer(lag(A), B)
This example returns the value the lag of A, unless that generates an error (as it would when evaluating the first period of the plan horizon), when it returns the value of B. The
prefer
function in this example is thus the functional equivalent of the expression:if(current == first, B, lag(A))
Non-Conforming Measures
One of the strengths of the RPASCE engine is that a workbook may contain measures with different scopes: the size and shape of the multidimensional cube of data may vary by measure. Any two given measures in a workbook may have scopes that align exactly (for instance, both measures have a base intersection of SKU/Store/Week), or where one is a subset of the other (for instance, one has a base intersection of SKU/Store/Week, and the other is at Class/Week). There can also be circumstances where each measure includes a hierarchy in its base intersection that the other dimension does not use (for instance, one has a base intersection of Class/Week and the other is Store/Week). In extreme circumstances, the scopes of two measures may have no point of overlap at all (for instance, one has a base intersection of Class and the other Store).
It is the scope of the measure on the left-hand side of an expression (referred to as the LHS measure) that determines the cells that must be calculated by the expression, though that scope may be modified using a modifier such as level. Where one or more measures on the right-hand side (RHS) of an expression have a scope that is different (in any way) to the left-hand side (LHS) measure, the expression is deemed to be non-conforming. There is special logic to handle the calculation of non-conforming expressions, which depends on the type of nonconformity.
Although not explicitly declared, there is a single logical All position at the top of every hierarchy. When considering non-conformity, any measure that is not dimensioned on a hierarchy, is implicitly assumed to be dimensioned on the All level of that hierarchy, and thus all data values are assumed to be for the All position. This concept is the key to understanding the handling of non-conforming expressions.
When the concept of the All position is understood, all expressions can be considered to contain measures that use the same hierarchies. The only potential differences between them are the bottom levels (dimensions in the base intersection). Thus, for handling non-conformity, only three cases need to be considered, for each hierarchy:
-
RHS same
In this case, the RHS measure has the same bottom level as the LHS measure. The RHS measure is conforming for that hierarchy, and values for the RHS measure are taken from the same position as the position being calculated for the LHS measure.
-
RHS higher
In this case, the RHS measure has a higher bottom level than the LHS measure. The RHS measure is non-conforming for that hierarchy. The values for the RHS measure for the position being calculated are assumed to be the same as the value of the RHS measure for the position in its bottom dimension that is the parent (ancestor) of the position being calculated. Effectively, it can be considered that the value of the measure has been replicated down the hierarchy to the required level.
-
RHS lower
In this case, the RHS measure has a lower bottom level than the LHS measure. The RHS measure is non-conforming for that hierarchy, but because the scope of the RHS measure includes the bottom level for the LHS measure, values for the RHS measure are taken from the same position as the position being calculated for the LHS measure. RHS measure is aggregated using the default aggregation method.
The conceptual case where the measures have scopes that do not overlap, because they have base intersections in a hierarchy that are for dimensions that are up different branches of the hierarchy, fails rule validation.
Non-Conforming Measure Examples
The following examples all use the simple expression a = b + c
.
Example 1
Consider the following scenario:
-
a has a base intersection of SKU/Store/Week
-
b has a base intersection of SKU/Week
-
c has a base intersection of SKU/Region/Week
For each SKU/Store/Week, a is calculated from the value of b at SKU/Week (it is assumed that the value of b is the same for all positions in the location hierarchy) and the value of c at SKU/Region/Week, for the Region the Store belongs in. If replication from the Region level is not appropriate, the rule writer can simulate other spreading techniques using functions and modifiers such as count and level.
For example, the count function may be used to determine the number of Stores in the Region, and so dividing the measure c by that count will simulate even spreading. Additionally level could be used to force the calculation of a at Region instead of as base intersection, Store (a.level([loc].[reg])=b+c). In this scenario edits to b or c would calculate a at Region and would then spread those values down to Store for measure a using the default spread method.
Example 2
Consider the following scenario:
-
a has a base intersection of SKU/Store/Week
-
b has a base intersection of SKU/Week
-
c has a base intersection of SKU
For each SKU/Store/Week, a is calculated from the value of b at SKU/Week (it is assumed that the value of b is the same for all positions in the location hierarchy) and the value of c at SKU (it is assumed that the value of b is the same for all positions in the location hierarchy and time hierarchy).
Note:
An alternative approach, if required, would be to use a level modifier on the measure a, so that it is calculated at SKU/Week, and then spread down to SKU/Store/Week, using the existing store participations to the measure a.
Example 3
Consider the following scenario:
-
a has a base intersection of SKU/Week
-
b has a base intersection of SKU/Store/Week
-
c has a base intersection of SKU/Region/Week
For each SKU/Week combination, a is calculated from the value of b and c at SKU/All/Week. Otherwise stated b and c are aggregated up the location hierarchy, and then added to a for each position in SKU/Week.
Functional Keywords
Functional keywords are keywords that may be used in expressions that return specific data values. There are a group of keywords that provide information (in the form of index numbers) about the calendar hierarchy, and a further group of keywords that provide information of the current session.
Calendar Index Functional Keywords
Certain calendar index functional keywords are supported in the syntax, as described in this section. In this context, a calendar index number is an ordinal position counter of the position in a dimension within the scope of the calendar horizon, where the dimension is as for the cell being evaluated. For example, in a plan whose scope is a year, the first week will have an index of 0, week 26 will have an index of 25, and week 52 will have an index of 51. Similarly, if an expression is being evaluated at the quarter level, the first quarter will have an index of 0, and the last one an index of 3. Calendar index functional keywords may be included in any numeric expression.
first
This returns the index number of the first calendar position.
This keyword is provided for completeness and clarity of rule function writing, since the value will always be zero.
last
This returns the index number of the last calendar position.
last + 1 will therefore always be the number of positions in the calendar horizon in the current dimension.
current
This returns the index number of the period being evaluated.
current can be used as a standalone keyword only under the context of time.
Note:
It can also be used in the syntax of a function as a hierarchical keyword (for specifying the current level in a hierarchy) and is allowed for any hierarchy (but must follow the syntax <hierarchy>.current
).
today
This returns the index number of the period that contains the current time as given by the system clock.
The index number that today returns is determined by the base intersection of the measure that is being evaluated (on the left-hand side of the expression). For example, if the base intersection of the measure being evaluated is week, today will return the index number of the current week.
Note:
The effect of this keyword may be overridden by providing the environment variable RPAS_TODAY. If this is present, the time in the RPAS_TODAY environment variable is used instead of the system clock time.
Note:
The difference between the keywords today and now is that today returns an index number; now returns the value of the current date and time. An error is generated when the current period is not included in the workbook.
elapsed
This returns the index number of the period that is the last elapsed period.
elapsed is interpreted as the last period for which actuals have been posted. When used on the RHS of an expression, it returns the index number of the period that is the last elapsed period for the level of calendar hierarchy at which the calculation takes place. When used on the LHS, this sets the last elapsed period along the base dimension of the Calendar hierarchy to the given index number, that is, it is assumed that the index number used to set elapsed is along the base dimension of the hierarchy. If there is no elapsed period, this keyword returns –1. Furthermore, when used on the RHS of an expression whose LHS does not have the Calendar hierarchy, this keyword returns -1.
elapsed must be assigned a value corresponding to the index of the last elapsed period before it can be used in calculations (on the right-hand side of other rule groups). This assignment can happen in load, refresh, or calc rule-groups but not in commit rule groups. Use the following syntax for assigning the index number in the base calendar dimension as the elapsed value.
Syntax
elapsed = <expression>
Where <expression>
is any valid expression that returns a numeric value, of which only the integer portion is used.
Example
For example, to update elapsed to always correspond to today:
-
Add a new single dimensional measure with base intersection at day.
Call this measure
pDay
. -
In the Calc rule group or in the Load and Refresh rule group.
-
Add rules that initialize the new measure with the calendar index of today, as shown in this example:
pDay=prefer(today-1,if(now>end,last,-1))
-
Add a new rule that sets the elapsed measure:
elapsed=pDay.pst
Note:
In the previous example, the intersection of
pDay
must match the lowest dimension in the workbook. If the lowest calendar dim of the workbook is at the day level, then the elapsed index calculated must correspond to the number of days elapsed. If the lowest calendar dim of the workbook is at the week level, then the elapsed index calculated must correspond to the number of weeks elapsed. -
The following examples illustrate the behavior of the keyword. For these examples, assume that RPASCE, using the previous mechanism, has calculated that the index for the last period along the base dimension (Day) to be 30 and that in the Calendar hierarchy, this day rolls up to week with index 4 and month with index 2. In this scenario, the following would occur:
-
LHS_week = elapsed
puts a value of 4 in the LHS_week measure which is along the Week dimension. -
LHS_day = elapsed
puts a value of 30 in the LHS_day measure which is along the day dimension. -
LHS_sku_str_day = elapsed
puts a value of 30 in the LHS_sku_str_day measure whose calendar hierarchy is along the Day dimension. -
LHS = elapsed
changes the navalue of LHS to -1, where the LHS measure is a scalar. Since the measure does not have a Calendar hierarchy, elapsed cannot determine the period index that this measure needs. In order to get a scalar populated, declare a measure along the level at which the elapsed index is required, assign it the elapsed keyword, and then assign this measure to the scalar with an aggregate of PST, PET, or AMBIG.
Session Keywords
This section describes session keywords.
now
This returns the current date and time from the system clock.
now
is stored with date and time information.
Note:
The difference between the keywords today
and now
is that today
returns an index number; now
returns the value of the current date and time.
The displayed format of now
is based on the measure type.
This keyword can be used to hold information about when data was changed (for instance, the beginning date and time of a batch run). The value returned by now
can be overridden by RPAS_TODAY environment variable.
userID
This returns a string that contains the id of the current user.
This keyword can be used to hold information about the user who made a specific change.
username
This returns a string that contains the account name of the current user.
This keyword can be used to hold information about the user who made a specific change.
Beginning with 19.x, the userid is ID (unique id) and Username is the username set by the customer while retrieving it from the session keywords. This means that, from now on, the customer must use the username as the session key word in all their rules. Currently, if the customer uses userid as the session keyword in the workbook template, the customer will see a unique ID uid000xx instead of the name. RPASCE applies strict rules when handling the personally identifiable information of a customer. In the past, customer have used the user email ID as the username, which cannot be logged into the log files.Anything displayed in the browser, such as OAT wizards/User Admin Wizards all show the username except for the log files, which are logged into the OAT tasks. Now and in the future, they cannot contain any personally identifiable information. These log files are shared within Oracle for analysis and it is regulated that all customer personally identifiable information must be removed. Only the userid is logged in the log files. In this way, a clear demarcation has been created between userid and username.
Calendar Hierarchical Date Keywords
This section describes calendar hierarchical date keywords.
begin
This returns a date type value for the first index in the MeasureStore calendar dimension.
Because it returns a date type value, this keyword is not context sensitive (meaning it does not depend on where it is being used) and can be compared with the now keyword.
Note:
The root calendar dimension is defined as the unique dimension that is at the root of the calendar hierarchy.
end
This returns a date type value for the last index in the MeasureStore calendar dimension.
Because it returns a date type value, this keyword is not context sensitive (meaning it does not depend on where it is being used) and can be compared with the now
keyword.
Modifiers
Modifiers are used to directly modify the source or destination of measures. Modifiers must be used in conjunction with a measure in the manner displayed under Syntax:
Syntax
<measure>[.<modifier>[.<modifier>]…
]
The following modifiers can be used with measures in a variety of ways. Note the acceptable uses for each modifier as there are restrictions regarding use on the left-hand side and if they can be used in conjunction with other modifiers.
master
This references the PDS version of a measure.
master is used as a modifier to a measure to reference the version of the measure that resides in the PDS. It can only be used in load and commit rule groups. It cannot be used in calculation rule groups.
Syntax
<measure>.master
Where <measure>
is any valid measure. master
can be used on both the left-hand side and right hand side of expressions
and can be used with functions. When used with other modifiers, master
must be the first modifier.
On the right-hand side of an expression, master can be used with both level and aggtype. On the left-hand side, master must be used by itself.
Examples
-
Sales=Sales.master
Used in load rule group to retrieve Sales from the PDS into a workbook.
-
Sales.master=Sales
Used in commit rule group to commit the updated Sales measure to the PDS from the version in the workbook.
aggtype
This references to alternative aggregation types.
When a measure is referenced just by name in an expression, or as a parameter in a rule function, the value used is for the default aggregation type for the measure. Values from alternative aggregation types are also available by using the syntax:
Syntax
<measure>.<aggtype>
Where aggtype
is a supported aggregation type
as listed in an appendix of this guide. Every function parameter that
requires a measure will also accept this extended form.
Note:
If alternate aggregation types are required for a measure in rules, this approach is more efficient that defining another measure with the alternate aggregation type, as data values at the base intersection are not duplicated.
The aggtype
modifier can only be used on the right-hand
side of an expression, but it can be used with functions and other
modifiers. When used with level and/or master modifiers, aggtype
must be the specified last.
level
This returns the value of an expression for a specific intersection of parent positions or forces the calculation at a specific intersection.
The parents specified may be in one or more hierarchies.
Syntax
<measure>.level(<dimspec1>[+<dimspec2>… +<dimspecn>])
Where <dimspec1-n>
is [<hierarchy>].{[<dimension>]
| top | current}
and each dimension specification is separated
by a plus sign.
<measure>
is the measure to be specified. <hierarchy>
is the name of a valid hierarchy. top and
current are keywords referring to the highest, and current (that is,
being evaluated if on the RHS, or base intersection in the hierarchy
if on the LHS) dimensions in the hierarchy. If a hierarchy is not
specified, the <dimension> for that hierarchy is assumed to be
current. If the <dimension>
for a hierarchy is
lower than the base intersection for the measure (when used on the
LHS), or the <dimension>
is not a valid dimension
in the specified hierarchy, an error is generated.
This modifier can be used on both the LHS and RHS of a rule expression. It can only be used by itself on the LHS, but it can be combined with other functions and modifiers on the RHS.
When this modifier is on the LHS of a rule expression, the rule is evaluated at the specified intersection. The newly calculated value at an aggregated intersection is then spread down the hierarchies to the base intersection for the measure, using the default spread-type for the measure. A typical usage of this modifier on the LHS of a rule expression is to calculate a non-conforming measure where the scope of the measure includes hierarchies not present in the measures on the RHS of the expression. The calculation would usually be at the base intersection of the common hierarchies, but at the top of the additional hierarchies and spread to their base intersections.
When this modifier is on the RHS of a rule expression, the measure being modified is evaluated at the specified intersection.
Note:
Just the measure, not the rule, is evaluated at the designated level.
Examples
-
sales.level([loc].top)
This returns the value for the measure sales for the position at the top of the location hierarchy and for the current position in all other hierarchies.
-
sales.level([loc].[area])
This returns the value for the measure sales for the position in the area dimension that is the parent of the position being evaluated and the current position in all other hierarchies (that is, the total sales in my area).
-
sales.level([loc].[area]+[prod].[div])
This returns the value for the measure sales for the position in the area and division dimensions that is the parent of the position being evaluated and current position in all other hierarchies (that is, the total sales in my area for my division).
-
recpts.level([rec].top) = <expression>
The measure recpts is calculated at the base intersection of all hierarchies except the rec hierarchy, where it is calculated at the top. This value is spread down to the base intersection for the measure.
old
This references the value of a measure as of the previous calculate.
Syntax
<measure>.old
Any measure modified with old will use the value that was available at the start of the calculation process, which means that these modified measures can be ignored for such things as protection processing. Most importantly, this means that a measure can effectively be calculated from itself, as the .old modifier breaks the cycle.
Assumptions/Restrictions
The following assumptions/restrictions apply to old
:
-
Can only be used in a rule group of type calculation.
-
Can only be used on the right-hand side of an expression.
-
Cannot be used in combination with
.master
,.level,
or.aggtype
modifiers. -
Cannot be used with (cannot modify) non-materialized measures.
Use of the old modifier has no effect on calculation sequence or protection processing, as the values of measures modified with old are known before the calculation starts.
Note:
The old modifier is not designed to operate with measures whose aggregation type is recalc. In particular, expressions that attempt to use the old modifier on a measure with an aggregation type of recalc, such as
a=b + c.old
where c is a measure with an aggregation type of recalc, are not allowed. Similarly, expressions that attempt to calculate a measure with an aggregation type of recalc, but which use the old modifier, such as
c=a + b.old
where c
is a measure with an aggregation type
of recalc, are also not allowed.
Example
The old modifier can be used in conjunction with the propspread
function to implement a hierarchical relationship among measures.
In the following example, Total sales (TotalSls) is the parent measure
and regular sales (RegSls), promotional sales (PromSls), and markdown
sales (MkdSales) are the child measures. Using old
and propspread
to configure this relationship allows
the manipulation of any combination of these measures before calculating,
except for all of them.
In the following example and in other such hierarchical measure relationships, the order of the expressions within a rule is critical for the measures to be correctly calculated.
-
TotalSls = RegSls + PromoSls + MkdSls
-
RegSls, PromoSls, MkdSls = propspread(TotalSls, RegSls.old, PromoSls.old, MkdSls.old)
-
PromoSls, MkdSls = propspread(TotalSls - RegSls, PromoSls.old, MkdSls.old)
-
RegSls, MkdSls = propspread(TotalSls - PromoSls, RegSls.old, MkdSls.old)
-
RegSls, PromoSls = propspread(TotalSls - MkdSls, RegSls.old, PromoSls.old)
-
RegSls = TotalSls - PromoSls - MkdSls
-
PromoSls = TotalSls - RegSls - MkdSls
-
MkdSls = TotalSls - RegSls - PromoSls
Description of Functions
This section describes:
Calendar Index Functions
These are functions that return the calendar index numbers of positions that are specified relative to the current position through hierarchical relationships, or by date. Support is in place for functions to find the first and last children of a parent at a given dimension (for instance, the first week of the current quarter, the last week of the current month). These are to support relative time series functions, such as month to date totals. These may be constrained by setting a condition under which the expression is evaluated.
indexfirst
This returns the calendar index number of the first position in the current dimension that is descended from the parent of the current position at the specified dimension.
See the tssum function for an example of typical usage. The function may be constrained by setting a condition for the evaluation.
Syntax
indexfirst([<clndhierarchy>].{[<dimension>] | top}[, <boolexpr>])
Where <clndhierarchy>
is the name of the calendar (time) hierarchy, and <dimension> is the name of a dimension in the calendar hierarchy. top is a keyword that implies the top dimension in the calendar hierarchy. If <dimension>
is not a valid dimension in the calendar hierarchy or it is not a dimension that is equal to or higher than the current (being evaluated) dimension in any alternate hierarchy, an error is generated.
<boolexpr>
is optional and is any valid Boolean expression used to set a condition for the evaluation of the function. If <boolexpr>
is not specified, the function returns the index number of the first position of the dimension descended from the parent of the current position of the specified dimension. When <boolexpr>
is specified, the function returns the index number of the first position of the dimension descended from the parent of the current position at the specified dimension where the <boolexpr> evaluates to true.
Inverse
The indexfirst
function does not have an inverse.
Examples
-
indexfirst([clnd].[qtr])
-
If the cell being evaluated is a week, this returns the calendar index number of the first week in the quarter that the week of the cell being evaluated belongs to (that is, the first week in the current quarter).
-
indexfirst([clnd].[week], Receipts != 0)
-
If the cell being evaluated is a day, this returns the calendar index number of the first day of the current week when that has a value for Receipts that is not equal zero (that is, the first day in the current week with recorded Receipts).
-
indexfirst([clnd].top)
-
If the cell being evaluated is a week, this returns the calendar index number of the first week in the calendar horizon. This keyword is included for consistency with other functions, as it will always return the value first (that is, zero).
indexlast
This returns the calendar index number of the last position in the current dimension that is descended from the parent of the current position at the specified dimension.
The function may be constrained by setting a condition for the evaluation.
Syntax
indexlast([<clndhierarchy>].{[<dimension>] | top}[, <boolexpr>])
Where <clndhierarchy>
is the name of the calendar (time) hierarchy. <dimension> is the name of a dimension in the calendar hierarchy. top is a keyword that implies the top dimension in the calendar hierarchy. If <dimension> is not a valid dimension in the calendar hierarchy or is not a dimension that is equal to or higher than the current (being evaluated) dimension (in any alternate hierarchy), an error is generated.
<boolexpr>
is optional and is any valid Boolean expression used to set a condition for the evaluation of the function. If <boolexpr>
is not specified, the function returns the index number of the last position of the dimension descended from the parent of the current position at the specified dimension. When<boolexpr>
is specified, the function returns the index number of the last position of the dimension descended from the parent of the current position at the specified dimension where the <boolexpr>
evaluates to true.
Inverse
The indexlast function does not have an inverse.
Examples
-
indexlast([clnd].[qtr])
-
If the cell being evaluated is a week, this returns the calendar index number of the last week in the quarter that the week for the cell being evaluated belongs to (that is, the last week in the current quarter).
-
indexlast([clnd].[week], Receipts != 0)
-
If the cell being evaluated is a day, this returns the calendar index number of the last day of the current week that has a value for Receipts that is not equal to zero (that is, the last day of the current week with recorded Receipts).
-
indexlast([clnd].top)
-
If the cell being evaluated is a week, this returns the calendar index number of the last week in the calendar horizon. This keyword is included for consistency with other functions, as it will always return the value last.
indextostartdate
This returns the start date of the period whose index number is supplied.
Syntax
indextostartdate(<index>[ ,[<clndhierarchy>].{[<dimension>] | current}])
Where <clndhierarchy>
is the name of the calendar (time) hierarchy, and <dimension> is the name of a dimension in the calendar hierarchy. current is a keyword that implies the current dimension in the calendar hierarchy. If <dimension>
is not a valid dimension in the calendar hierarchy, an error is generated. If the calendar hierarchy and dimension are not supplied, the default is the current calendar dimension.
Note:
This function requires that the day dimension of the calendar hierarchy be included in the workbook. If the lowest dimension of the calendar hierarchy is higher than the day dimension, the function will not be able to return a valid date.
<index>
is an expression that returns an index number in the indicated calendar dimension. If <index>
is non-integer, only the integer portion is used. If <index>
is not a valid index number for the specified dimension, an error is generated. If the measure being evaluated does not have a base intersection in the calendar hierarchy, and the current option is used, an error is generated.
The function returns a date that is the start date of the period indicated by the dimension and index number. If the period being evaluated is at or lower than the day level, the start date is the date of the whole of the period. If the period being evaluated is higher than the day level, the start date is the date of the first child position at the day level of the period being evaluated.
Inverse
The indextostartdate
function does not have an inverse.
Examples
-
indextostartdate(current)
-
Returns the start date of the current time period.
-
indextostartdate (indexfirst([clnd].[qtr]))
-
Returns the start date of the first period in the current time dimension in the current quarter.
-
indextostartdate (index([clnd].[week], openweek), [clnd].[week])
-
Returns the start date of the period at the week level whose name is held in the openweek measure.
indextoenddate
indextoenddate
This returns the end date of the period whose index number is supplied.
Syntax
indextoenddate(<index>[ ,[<clndhierarchy>].{[<dimension>] | current}])
Where <clndhierarchy>
is the name of the calendar (time) hierarchy, and <dimension> is the name of a dimension in the calendar hierarchy. current is a keyword that implies the current dimension in the calendar hierarchy. If <dimension>
is not a valid dimension in the calendar hierarchy, an error is generated. If the calendar hierarchy and dimension are not supplied, the default is the current calendar dimension.
Note:
This function requires that the day dimension of the calendar hierarchy be included in the workbook. If the lowest dimension of the calendar hierarchy is higher than the day dimension, the function will not be able to return a valid date.
<index>
is an expression that returns an index number in the indicated calendar dimension. If <index>
is non-integer, only the integer portion is used. If <index>
is not a valid index number for the specified dimension, an error is generated. If the measure being evaluated does not have a base intersection in the calendar hierarchy, and the current option is used, an error is generated.
The function returns a date that is the end date of the period indicated by the dimension and index number. If the period being evaluated is at or lower than the day level, the end date is the date of the whole of the period. If the period being evaluated is higher than the day level, the end date is the date of the last child position at the day level of the period being evaluated.
Inverse
The indextoenddate function does not have an inverse.
Examples
-
indextoenddate(current)
-
Returns the end date of the current time period.
-
indextoenddate (indexfirst([clnd].[qtr]))
-
Returns the end date of the last period in the current time dimension in the current quarter.
-
indextoenddate (index([clnd].[week], openweek), [clnd].[week])
-
Returns the end date of the period at the week level whose name is held in the openweek measure.
Calendar Calculation Functions
These are functions that return calendar calculations.
addPeriods
This function requires three inputs and generates one output. It produces a Date value output by adding some periods specified by a dimension name to an input Date value.
Input
-
Date: Input Date value.
-
Integer: Number of periods to be added to the input Date specified by 1.
-
String: The Dimension Name of the period, such as DAY, MNTH, and so on.
Output
Date: The input Date plus number of periods.
Example
targetDate = addPeriods(srcDate, 1, "DAY")
Note:
If srcDate evaluates to Jan/01/2012, targetDate should be Jan/02/2012.
calendarStart
This function has no input and produces one output. The output is a Date type value specifying the starting date of the current application’s calendar hierarchy. If called in a workbook, it still returns the starting date of the application’s calendar hierarchy, not the first date included in the workbook.
Output
Date: First date in the current application’s calendar hierarchy.
Example
targetDate = calendarStart()
dateDiff
This function requires three inputs and generates one output. It calculates the difference of two date values. It returns the difference as an integer value as number of days, months, and so on, depending on a third string type input that specifies the scale of the output as a dimension name.
The dateDiff() function has a restriction that it can only calculate using dates loaded in the CLND hierarchy. If either the start or the end date is outside of CLND range, the function returns 0 (the same as if the start date = the end date).
Input
-
Date: First date.
-
Date: Second date.
-
String: Dimension name for the scale of the diff to be calculated, such as DAY, MNTH, and so on.
Output
Integer: Number of periods calculated by firstDate - secondDate, in the scale of the dimension name provided.
Example
targetDate = dateDiff(date1, date2, "MNTH")
Note:
If date1 is Jan/01/2012, and date2 is Jan/01/2011, the resulting targetDate is 12, since the two dates are 12 months apart.
Date
This function requires two inputs and produces one output. It produces a date value based on an input date as a string, and a formatting string.
Input
-
String: Input date string
-
String: Date formatting string
The date formatting string follows the format of %[variable]%{variable]%[variable]. The specific options are as follows:
-
B: month, full name
-
h: month, 3-character abbreviation, such as JAN, FEB, MAR
-
Y: 4-digit year
-
y: 2-digit year
-
m: 2-digit month
-
d: 2-digit day
-
H: 2-digit hour
-
M: 2-digit minute
-
S: 2-digit second
-
s: 3-digit millisecond
For instance, if the format string evaluates to %Y%m%d and the date string is 20120102, the date is January 02, 2012. If the format string is %Y%h%d%H%M%S and the date string is 2012JAN02073030, the time and date is 7:30:30am on January 02, 2012.
Output
Date: Date value by parsing the input date string using the input date format.
Example
targetDate = date(dateStr, formatStr)
Index and Position Functions
This is a class of general functions that may be used for any hierarchy that enables reference to positions in a generic manner. In most cases, the functions do not generate results that are useful in themselves, but they are typically used as parameters that are passed into other functions.
An index is an internal reference to a position in a dimension. For dimensions in the calendar hierarchy, the index reflects an ordering of positions because there is a well-defined sequence (oldest to newest, based on the start and end dates) of periods. There are special calendar index functions that exploit this property. For other dimensions, there is no such ordering, and the index number can be considered random.
Note:
Index numbers (including calendar index numbers) should not be saved and reused between planning sessions, as there is no guarantee that the same index numbers will apply in subsequent sessions since the positions or relationships in a hierarchy may change.
These general index functions may be used for any hierarchy, including the calendar hierarchy.
index
This returns the index number of the specified position in the specified dimension of the specified hierarchy.
Syntax
index([<hierarchy>].{[<dimension>] | current}[,{ <stringexpr> | <dateexpr>}])
Where <hierarchy>
is the name of a valid hierarchy, and <dimension> is the name of a valid dimension in that hierarchy. current is a keyword that returns the current dimension in <hierarchy>
. If <hierarchy>
is not a valid hierarchy or <dimension>
is not a valid dimension in that hierarchy, an error is generated.
<stringexpr>
and <dateexpr>
are optional expressions that can be used to specify a position. If neither <stringexpr>
nor <dateexpr>
are specified, the function returns the index number of the current position of the dimension being evaluated. <stringexpr>
is a string expression that results in a position name. If the result of <stringexpr>
is not a valid position name in the dimension being evaluated, an error is generated. <dateexpr>
is a numeric expression that results in a date type value and can only be used if <hierarchy>
is the calendar hierarchy. If the result of <dateexpr>
is not a date type value, or the result is returned when evaluating a dimension that is not in the calendar hierarchy, an error is generated.
The function returns the index number of the indicated position in the specified dimension of the specified hierarchy. When used with dates, the indicated position is the position that contains the date specified.
Inverse
The index
function does not have an inverse.
Examples
-
index([prod].[item], likeitem)
-
This returns the index number of the string position in the item dimension referenced in the likeitem measure.
-
index([prod].[cls], cls123)
-
This returns the index number of the class cls123.
-
index([clnd].[mnth], opendate)
-
This returns the index number of the month that contains the date that results from the opendate measure.
position
This returns the position name of the position in the specified dimension of the specified hierarchy with the supplied index number. The returned string is in upper case.
Syntax
position([<hierarchy>].{[<dimension>] | current}[, <indexexpression>])
<hierarchy>
must be the name of a valid hierarchy. If specified, <dimension> must be the name of a valid dimension in that hierarchy. current is a keyword that returns the current dimension in <hierarchy>
. If <hierarchy>
is not a valid hierarchy or <dimension> is not a valid dimension in that hierarchy, an error is generated.
<indexexpression>
is an optional parameter to specify the index of the position to be evaluated. If <indexexpression>
is not specified, the current position is assumed. The expression must be a valid expression that results in a numeric measure. The integers of the resulting values of the expression are used as the index numbers to determine the position to be evaluated. If <indexexpression>
does not return a valid index number for the specified dimension an error is generated.
The function returns an uppercase string that is the position name of the position with the specified index number for the specified dimension of the specified hierarchy.
Inverse
The position function does not have an inverse.
Examples
-
position([prod].[item], 3)
-
This returns the position name of the item with index number =3.
-
position([prod].[item], likeindex)
-
This returns the position name of the item with the index number in the measure likeindex.
-
position([prod].current)
-
This returns the position name of the current position of the current dimension in the product hierarchy.
attribute
This returns the value of the specified attribute for the current position, or the position with the supplied index number.
Syntax
attribute(<attribute>, [<hierarchy>].{[<dimension>] | current}[, <indexexpression>])
Where <attribute>
is a valid attribute for the dimension to be used, otherwise an error is generated. <hierarchy>
must be the name of a valid hierarchy. If specified, <dimension> must be the name of a valid dimension in that hierarchy. current is a keyword that returns the current dimension in <hierarchy>
. If <hierarchy>
is not a valid hierarchy or <dimension>
is not a valid dimension in that hierarchy, an error is generated.
<indexexpression>
is an optional parameter to specify the index of the position to be evaluated. If <indexexpression>
is not specified, the current position is assumed. The expression must be a valid expression that results in a numeric measure. The integers of the resulting values of the expression are used as the index numbers to determine the position to be evaluated. If <expression>
does not return a valid index number for the specified dimension an error is generated.
Valid values for <attribute>
for all non-measure dimensions include the following, which must be specified using quotes:
-
"label" – The label (description) for the position. This value must be specified using quotes. The attribute function requires left-hand side measure to be a string measure. All keywords which need to be passed to a function must be wrapped in double quotes. Any other syntax will throw an error.
-
"dpmstatus" – The DPM status of the position. This attribute function required left-hand side measure to be a Boolean measure. True value corresponds to an informal status. A False value corresponds to a formal status.
The function returns the value of the specified attribute for the specified position.
Inverse
The attribute
function does not have an inverse.
Examples
-
attribute("label", [prod].current)
-
This returns the value of the label attribute for the current position of the current dimension in the product hierarchy.
-
attribute("dpmstatus", [prod].[item], likeindex)
-
This returns the value of the dpmstatus attribute for the item with the index number in the measure likeindex (that is, the label for my like item).
Forecast Procedure
Using the RPASCE Configuration Tools, a time-series demand forecast may be configured as part of a planning workflow or business process. The Forecast procedure provides only a small subset of the functionality that is available through IPOCS-Demand Forecasting. The differences between these solution extensions are as follows:
-
The forecast produced by the Forecast procedure is a single-level forecast.
-
IPOCS-Demand Forecasting allows for forecasts to be generated at aggregate levels in the data (to remove sparsity), and then this forecast is spread down to the execution level by using a profile.
-
The Forecast procedure allows for a single forecasting method to be specified in the calculation of the forecast.
-
IPOCS-Demand Forecasting allows for forecasting methods and forecasting parameters to be modified as needed at all levels in your data.
-
No standard approval process of the resulting forecasts is included as part of the Forecast procedure.
-
IPOCS-Demand Forecasting allows for forecast adjustments and approvals to be made at the lowest level necessary in your data.
The Forecast Procedure Syntax section contains the specifications and syntax for configuring the Forecast procedure.
Forecast Requirements
The following libraries must be registered in any PDS that will use the Forecast solution extension:
-
AppFunctions
-
RdfFunctions
Using the Forecast Procedure
The following notes are intended to serve as a guide for configuring the Forecast procedure within the RPASCE Configuration Tools.
-
Refer to the appropriate input parameters and output measures when using the Forecast procedure.
-
The resultant measure (that is, the forecast output) should be at the same intersection as your history measure (that is, pos). This will be the base intersection of the final level.
-
The Forecast procedure is a multiple result procedure, meaning that it can return multiple results with one procedure call within a rule. In order to get multiple results, the resultant measures must be configured in the Measure Tool and the specific measure label must be used on the left-hand side (LHS) of the procedure call. The resultant measure parameters must be comma-separated in the procedural call.
Syntax Conventions
Table B-2 displays the syntax conventions used in this procedure.
Table B-2 Syntax Conventions
Indicator | Definition |
---|---|
[…] |
All options listed in brackets are optional. |
{…|…} |
Options listed in “{}" with “|" separators are mutually exclusive (either/or). |
{…,…} |
Options listed in “{}" with “," separators way are a complete set. |
Bold |
Bold indicates Labels. |
Italics |
Italics indicate a temporary placeholder for a constant or a measure. |
Italics/meas |
This indicates that the placeholder can be either a constant or a measure. |
BoldItailics |
This indicates a numeric placeholder for the dynamic portion of a label. Usually a number from 1 to N. |
Normal |
Normal text signifies required information. |
Underlined |
This convention is used to identify the function or procedure name. |
Forecast Procedure Syntax
This shows the syntax for using the Forecast procedure with a simplified syntax version of the Forecast procedure. For the complete syntax version, refer to the Oracle Retail Inventory Planning Optimization Cloud Service Demand Forecasting Administration Guide. The input and output parameter tables explain the specific usage of the parameter's names use in the procedure.
Simplified Syntax Version of the Forecast Procedure
Generic Example:
FORECAST: FORMEAS , CHMETHOD:METHMEAS<-BaselineForecast(MASK:MEASKMEAS, {STARTDATE:STARTDATE | STARTDATEMEAS:STARTDATEMEAS}, HISTORY: HISTORYMEAS, FORECASTLENGTH:FORECASTLENGTH, PERIOD:PERIOD ,{FRCSTSTARTMEAS:FRCSTSTARTMEAS | FRCSTSTART:FRCSTSTART}, PLAN:PLAN, PROFILE:PROFILE, BAYESIAN_HORIZ:BAYESIAN_HORIZ, {VALID_DD:VALID_DD, DDPROFILE:DDPROFILE })
Sample:
forecast:frcstout,cumint:cumintout,int:intout<-BaselineForecast(forecastlength :12,history:pos,mask:frcstmask,period:26,startdatemeas:todaymeas)
Configuration Parameters and Rules
Table B-3 provides the input parameters for the Forecast procedure.
Table B-3 Forecast Procedure Input Parameters
Parameter Name | Description |
---|---|
FORECASTLENGTH |
The length of the forecast. Data Type: Integer Multiple Allowed: No Required: Yes |
HISTORY |
The input measure the forecast is based on. Data Type: Real Multiple Allowed: No Required: Yes |
MASK |
Array that identifies what forecast method is used for each time series. Refer to Forecast Model/Model List table. Data Type: Boolean Multiple Allowed: No Required: Yes |
MAXALPHA |
The maximum alpha value. Data Type: Real Multiple Allowed: No Required: No |
PERIOD |
The forecasting period for calculating seasonal coefficients. Data Type: Integer Multiple Allowed: No Required: Yes |
PLAN |
The Plan measure. Data Type: Real Multiple Allowed: No Required: No |
PROFILE |
The Seasonal Profile measure. Data Type: Real Multiple Allowed: No Required: No |
STARTDATE/ STARTDATEMEAS |
The forecast start date. Either STARTDATE or STARTDATEMEAS is required. STARTDATEMEAS, if used, must be a scalar for AutoES method. Data Type: STARTDATE - Date as a string. Data Type: STARTDATEMEAS – Date as measure. Multiple Allowed: No Required: Yes |
VALID_DD |
The maximum non-zero history to use de-seasonalized demand value for seasonal profile-based forecasting. Data Type: Integer Multiple Allowed: No Required: No |
DDPROFILE |
De-seasonalized demand measure. Used only for profile-based forecasting. Data Type: Double Multiple Allowed: No Required: No |
Table B-4 provides the output parameters for the Forecast procedure.
Table B-4 Forecast Procedure Output Parameters
Parameter Name | Description |
---|---|
CHMETHOD |
Selected method. Refer to Forecast Model/Model List table. Data Type: Integer Multiple Allowed: No Required: No |
FORECAST |
Forecast output. Data Type: Real Multiple Allowed: No Required: Yes |
PEAKS |
Peaks, which are used for calculating baseline of the forecast. Data Type: Real Multiple Allowed: No Required: No |
Forecast Method/Model List
Table B-5 provides the numeric value assigned to the forecast model/model list.
Table B-5 Forecast Procedure Output Parameters
Model | Numeric Value |
---|---|
AUTO ES |
1 |
SIMPLE |
2 |
HOLT |
3 |
WINTERS |
4 |
CASUAL |
5 |
AVERAGE |
6 |
NO FORECAST |
7 |
COPY |
8 |
CROSTON |
9 |
M. WINTERS |
10 |
A. WINTERS |
11 |
SIMPLE CROSTON |
12 |
BAYESIAN |
13 |
LOADPLAN |
14 |
PROFILE |
15 |
Tensorflow Procedure
This section details the AppTensorflowExpr (Tensorflow procedure for generating results by loading and calling trained Tensorflow model with input features measure).
Tensorflow Parameter/Model Dependencies
The models should be trained at right version of Tensorflow version and should be already uploaded to the PDS.
Using the Tensorflow Procedure
The following bulleted items are intended to serve as a guide for configuring the Tensorflow procedure within the RPASCE Configuration Tools:
-
Refer to the appropriate input parameters and output measures when using the Tensorflow procedure.
-
The resultant measure (ML_OUTPUT) should be at the same intersection as RUN_MASK measure or with extra calendar dimension.
-
If the output is a time series, then the ML_PREDICT_BEGIN and ML_PREDICT_END measures which specify the start date index and end date index, should be periodically updated (every week or so) by configuring rules. Otherwise, these two measures are not needed.
-
The indicator to run the algorithm or not is specified using the RUN_MASK measure. This is a boolean measure and on its intersection, the Tensorflow models related information will be retrieved.
Forecast Procedure Syntax
The syntax for using the Tensorflow procedure is as follows:
ML_OUTPUT: FORMEAS {,ML_OUTPUT_MSG:RTNMSG} <-AppTensorflowExpr(RUN_MASK:MEASKMEAS ML_OPERATOR:OPERATORMEAS, ML_INPUT_PLACEHOLDER:INPUTMEAS,ML_CHKPT_PATH: PATHMEAS, {, ML_PREDICT_BEGIN:STARTINDEX, ML_PREDICT_END:ENDINDEX,DATA_HIER:"HIERNAME"}, ML_FEATURE1:FEATURE1MEAS,{ ML_FEATUREN:FEATURENMEAS })
Configuration Parameters and Rules
Table B-6 and Table B-7 explain the specific usage of the parameters names used in the procedure.
Table B-6 Input Parameters for the Tensorflow Procedure
Parameter Name | Description |
---|---|
RUN_MASK |
The run mask Data Type: Boolean Multiple Allowed: No Required: Yes |
ML_OPERATOR |
The model output tensor name Data Type: String Multiple Allowed: No Required: Yes |
ML_INPUT_PLACEHOLDER |
The model input tensor name. Data Type: String Multiple Allowed: No Required: Yes |
ML_CHKPT_PATH |
The Tensorflow model path Data Type: String Multiple Allowed: No Required: Yes |
DATA_HIER |
The hierarchy name along which the output will be. Usually it is CLND for the time series. Data Type: String Multiple Allowed: No Required: No |
ML_PREDICT_BEGIN |
The start date index. Only needed if the output is an array. Data Type: Integer Multiple Allowed: No Required: no |
ML_PREDICT_END |
The start date index. Only needed if the output is an array. Data Type: Integer Multiple Allowed: No Required: No |
ML_FEATURE |
The data feature input Data Type: Real Multiple Allowed: Yes Required: Yes |
Table B-7 Output Parameters for the Tensorflow Procedure
Parameter Name | Description |
---|---|
ML_OUTPUT |
Tensorflow procedure output. Data Type: Real Multiple Allowed: No Required: Yes |
ML_OUTPUT_MSG |
Tensorflow procedure return message. Data Type: String Multiple Allowed: No Required: no |
Tensorflow Models Upload
Retailers should train their models with their own data and algorithm on the corresponding Tensorflow version that RPASCE supports. Once the models are trained and saved into binary files. Retailer should upload their models using the Manage Tensorflow OAT task or during the PDS build or patch.
Tensorflow Tensor Name
After training the models and saving the model into the Tensorflow binary files, retailer could run the utility saved_model_cli
to find out the input and output name of the tensor node in the saved models. For the details on this command, refer to this website: https://www.tensorflow.org/guide/saved_model
.
Tensorflow Feature Data
Most machine learning algorithms are expecting the feature data are within same range in order to product robust results. There are different methods to normalize the features data to some specific range. No matter which method retailer choose, retailer should make sure the same normalization methods should apply to feature data in both training and forecasting. In other words, the ML_FEATURE measures should be normalized with same method as the feature data which is used to train the uploaded models. Also, the order of the feature in this special expression should be the same during the training phase. Example, if price is the second feature in training phase, the price will be the second feature (ML_FEATURE2) in this special expression.
Time Series Functions
This is a collection of very similar functions to perform typical calculation tasks over a range of cells in one or more time series. The <start>
and <end>
positions, defined using calendar index numbers, specifies the range of cells to be used. Typically, there may be some arithmetic performed to calculate the start and/or end positions.
Note:
By using the indexdate
or index
functions to provide calendar index numbers, the <start>
and <end>
positions to be used in the time series can effectively be specified by position name or by date.
Note:
If the level modifier is used, the current keyword only has a value when the level used is higher than the level being evaluated (since, for example, the concept of the current week is ambiguous when evaluating a month, so an error is generated).
Single Time Series Functions
The following sections detail the Single Time Series functions.
tssum
Produces a sum of the cells in the time series for the measure defined by the start and end positions.
tssum
is used for the following types of calculations:
-
Season to date
-
Balance to achieve
-
4 week moving sum
The function produces a sum of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tssum(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory, the other parameters are optional. If <start>
is not specified, the default value is first (that is, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tssum function does not have an inverse.
Examples
-
tssum(PlanSales)
-
This is a plan-to-date or running total value for sales.
-
tssum(PlanSales, current, last)
-
This provides a balance to achieve (that is, a sum from the current period to the end of the horizon).
-
tssum(PlanSales.level([clnd].[week]), current – 3, current)
-
This provides a 4-week moving total for sales.
-
tssum(PlanSales, indexfirst([clnd].[qtr]))
-
This provides a quarter to date running total (see the indexfirst function).
tsavg
The average (mean) value of the cells in the range.
The function produces an average of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsavg(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsavg
function does not have an inverse.
tsmax
The maximum value of any cell in the range.
The function returns the maximum value of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsmax(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsmax function does not have an inverse.
tsmin
The minimum value of any cell in the range.
The function returns the minimum value of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsmin(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsmin
function does not have an inverse.
tsmode
The modal value of the cells in the range.
The function returns the modal value of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsmode(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
If there is more than one value for the mode, then the function returns the first value that is calculated.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsmode
function does not have an inverse.
tsmedian
The median value of the cells in the range.
The function returns the median value of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsmedian(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
If there is no middle number, the function returns the average of the middle two numbers.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsmedian
function does not have an inverse.
tsstd
The standard deviation of the cells in the range.
The function returns the standard deviation of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsstd(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsstd
function does not have an inverse.
tsvar
The variance of the cells in the range.
The function returns the variance of the cells in the time series for the positions implied by the <start>
and <end>
for the specified dimension.
Syntax
tsvar(<expression>[, <start>[, <end>]])
Where <expression>
is an expression or measure whose time series is to be used, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>
, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<expression>
is mandatory; the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current.
Use the level modifier to specify a dimension in the calendar hierarchy when calculating higher or lower than the current calendar dimension.
Inverse
The tsvar
function does not have an inverse.
Double Time Series (Statistical Error) Functions
The following sections detail the Double Time Series (Statistical Error) functions.
tsme
Produces the Mean Error of an estimate time series compared to an actuals time series.
Syntax
tsme(<x>, <y>[, <start>[, <end>]])
Where <x>
is an expression or measure that represents the estimate and <y>
is an expression or measure that represents the actuals, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated
<x>
and <y>
are mandatory, and the other parameters are optional. If <start>
is not specified, the default value is first (that is, 0). If <end>
is not specified, the default value is current. The Mean error is calculated using the following formula.
Inverse
The tsme function does not have an inverse.
Examples
-
tsme(FcstSales, ActSales)
-
This calculates the Mean Error of the FcstSales measure from the start of the calendar horizon until the current time period.
-
tsme(FcstSales, ActSales, first, elapsed)
-
This calculates the Mean Error of the FcstSales measure from the start of the calendar horizon until the last time period with actuals loaded.
-
tsme(FcstSales, ActSales, first, min(elapsed, current))
-
This calculates the Mean Error of the FcstSales measure from the start of the calendar horizon until the first of the period being evaluated or the last time period with actuals loaded.
tsmae
Mean Absolute Error.
Syntax
tsmae(<x>, <y>[, <start>[, <end>]])
Where <x>
is an expression or measure that represents the estimate and <y>
is an expression or measure that represents the actuals, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<x>
and <y>
are mandatory, the other parameters are optional. If <start>
is not specified, the default value is first (that is, 0). If <end>
is not specified, the default value is current.
The Mean Absolute error is calculated using the following formula.
Inverse
The tsmae function does not have an inverse.
tsmape
Mean Absolute Percentage Error.
Syntax
tsmape(<x>, <y>[, <start>[, <end>]])
Where <x>
is an expression or measure that represents the estimate and <y>
is an expression or measure that represents the actuals, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<x>
and <y>
are mandatory, and the other parameters are optional. If <start>
is not specified, the default value is first (for instance, 0). If <end>
is not specified, the default value is current. The Mean Absolute Percentage error is calculated using the following formula.
Figure B-3 Mean Absolute Percentage Error Formula
![Description of Figure B-3 follows Description of Figure B-3 follows](img/f348_inverse_tsmape.jpg)
Description of "Figure B-3 Mean Absolute Percentage Error Formula"
Inverse
The tsmape
function does not have an inverse.
tsrmse
Root Mean Square Error.
Syntax
tsrmse(<x>, <y>[, <start>[, <end>]])
Where <x> is an expression or measure that represents the estimate and <y> is an expression or measure that represents the actuals, and <start> and <end> are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start> or <end> are numeric, but non-integer, only the integer portion will be used. If <end> is less than <start>, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<x> and <y> are mandatory, and the other parameters are optional. If <start> is not specified, the default value is first (that is, 0). If <end> is not specified, the default value is current. The Root Mean Square error is calculated using the following formula.
Inverse
The tsrmse function does not have an inverse.
tspae
Percentage Absolute Error.
Syntax
tspae(<x>, <y>[, <start>[, <end>]])
Where <x>
is an expression or measure that represents the estimate and <y>
is an expression or measure that represents the actuals, and <start>
and <end>
are expressions that calculate numbers. The current calendar dimension is assumed, and if the cell being evaluated does not have a calendar dimension, the bottom calendar dimension is assumed. If the values of <start>
or <end>
are numeric, but non-integer, only the integer portion will be used. If <end>
is less than <start>, or either parameter is non-numeric or outside the scope of the calendar index numbers for the specified dimension, an error is generated.
<x>
and <y>
are mandatory, and the other parameters are optional. If <start>
is not specified, the default value is first (that is, 0). If <end>
is not specified, the default value is current. The Percentage Absolute error is calculated using the following formula.
Figure B-5 Percentage Absolute Error Formula
![Description of Figure B-5 follows Description of Figure B-5 follows](img/f350_inverse_tspae.jpg)
Description of "Figure B-5 Percentage Absolute Error Formula"
Inverse
The tspae
function does not have an inverse.
Hierarchical Functions and Procedures
This is a collection of functions and procedures that provide some knowledge of hierarchical structures, and the how the current position fits in, or uses knowledge of hierarchical structures.
count
This returns the count of children at a specified level that belong to a parent at a higher level.
Syntax
count([<hierarchy>][.<childdimspec>[,<parentdimspec>]])
Where <childdimspec> is {[<childdimension>] | bottom | current}
and <parentdimspec> is [<hierarchy>].{[<parentdimension>] | top | current}
<hierarchy> is the name of a valid hierarchy (same hierarchy must be referenced throughout the function). <childdimension> and <parentdimension> must be valid dimensions in the specified hierarchy. If both are specified, then <childdimension> must be lower than <parentdimension> in a roll-up, or an error is generated. bottom, top, and current are keywords referring to the lowest, highest, and current (being evaluated) dimensions in the hierarchy. If <childdimspec> is not specified, the default is bottom. If <parentdimension> is not specified, the default is current.
The function returns the number of children in the dimension <childdimension> that are descended from the implied position (the current position or the ancestor of the current position at the specified level) in the dimension <parentdimension>. If the <childdimension> and the <parentdimension> are the same, the function returns the value of 1.
Inverse
The count function does not have an inverse.
Examples
-
count([loc].bottom)
-
Returns the number of children in the bottom dimension in the location hierarchy for the current position in the location hierarchy
-
count([loc].[str])
-
Returns the number of children in the store dimension (str) in the location hierarchy for the current position in the location hierarchy (that is, how many stores do I own)
-
count([loc].[str], [loc].[area])
-
Returns the number of children in the store dimension in the location hierarchy for the position in the dimension area that is the ancestor of the current position in the location hierarchy (that is, how many stores in my area).
lookup
This procedure returns the value of an expression for a specific intersection.
The positions to be looked up may be in one or more hierarchies. This procedure has the following special uses and restrictions:
lookup is a procedure and thus cannot be combined with functions and other procedures in any manner.
Used for history mapping and like SKU/sister store functionality.
The base intersection of the output measure must be the same as the input measure and/or one or more of the mapping measures.
Syntax
<output> <- lookup(<input>, <dimspec1> [, <dimspec2> ... , <dimspecn>])
Where <dimspec1-n> is [<hierarchy>].{[<dimension>] | bottom | current | top}, <map>
<output> is the measure being updated. <input> is the measure to be evaluated. Each <dimspec> is used to specify the hierarchy and dimension to be used in the mapping process and the measure that contains the mapping values.
For each <dimspec> that is specified, the <hierarchy> must be the name of a valid hierarchy and the <dimension> must be the name of a valid dimension in that hierarchy. top is a keyword that refers to the highest dimension in the hierarchy, bottom is a keyword that refers to the lowest dimension in the hierarchy, and current is a keyword that refers to the current dimension (that is, the dimension of the cell being evaluated).
<map> is either a measure or an explicitly stated position used to designate how positions in <input> are mapped to determine the resulting values in <output>. The output, input, and mapping measures used in the lookup procedure must conform in a certain manner. Specifically, the resulting measure <output> must have the same base intersection as <input>, <map>, or both measures so that all conform.
When <map> is a measure, it must result in either index numbers or position names, either of which must be valid index numbers or position names from the related dimension specification. When <map> contains index numbers that do not map to valid positions, an error is generated and the na value for <output> is returned. There is no special cycle breaking logic for the lookup procedure. This means that a measure may never be calculated from the lookup of the same measure.
Note:
lookup
is a procedure so it cannot be combined with functions, modifiers, or other procedures in any manner. As a procedure, it requires a different syntax: “<-“ instead of “= when being assigned.
Inverse
The lookup procedure does not have an inverse.
Examples
-
output <- lookup(input, [presentationstyle].[ presentationstyle], map)
-
Where output is at sku-week, input is at sku-presentationstyle, and map is at sku-week with position names or index numbers from the presentation style dimension. The output and mapping measures have the same base intersection. This expression calculates the output measure from the mapping of presentation styles that vary for each sku-week combination.
-
output <- lookup(input, [prod].[sku], map)
-
Where output and input are at sku-week and map is at sku with position names or index numbers from the sku dimension. This expression calculates the output measure from the like sku of the input measure.
Tablelookup
This procedure returns the value (interpolated if necessary) from the entry in a table of information held in measures that matches with supplied keys.
Syntax
tablelookup(<expression>, <matching technique>, <keymeasure> [,<resultmeasure>])
Where <matching technique> is {exactmatch, <nomatchvalue> | average | nearest | high | low | interpolate}
The tablelookup procedure requires that a table be available that may be the target of the lookup. This table will be formed from normal measures with a base intersection of normal dimensions. Nevertheless, the most usual usage will be where the table measures are dimensioned on a dimension built for the purpose, plus other dimensions as required.
Note:
The usage of the tablelookup special expression requires the arguments to be conformed in certain way. For example, in the tablelookup expression (valueMeasure, nearest, keyMeasure), it is required to address the following:
-
The keyMeasures baseint must have a table entry dimension, and this table entry dimension must be the innermost. Let's assume the keyMeasure is at clss/rgn/te level where dimension te is the table entry dimension, and it is the innermost. The subspace of the key entry is defined as the baseint of the key measure minus the table entry dimension; in this case, the subspace will be clss/rgn.
-
The valueMeasures baseint must be able to map to the subspace (clss/rgn) with a many to one mapping, that is, the baseint of the valueMeasure must be shows the clss/rgn. So it is a valid expression if the valueMeasures baseint is sku/str, clss/str, sku/rgn. If the valueMeasures baseint is the same or higher than clss/rgn, or cannot create a valid map to clss/rgn, the previous error message is triggered. For example, lower than baseint for valueMeasure triggers the error: clss/rgn, dept/rgn, clss/chn, dept/chn, dept/str, sku/chn.
It is suggested to examine the baseint of the input measure with the previous criteria in mind.
Example
Imagine a requirement to look up valid price points that may be applied as prices for an item. The collection of valid price points will be different for each class. To satisfy this requirement, a table is built. A ‘table' hierarchy is defined with a tableentry dimension with a number of positions, which are named e01, e02, e03, … e99 to allow for 99 entries in the table, with the order of the positions being the same as their natural sort sequence, and the order of the hierarchy being the highest (innermost) non-time hierarchy. A measure named pp is defined with a base intersection of tableentry/class. The pp measure is populated with valid price points for each class, with the lowest valid price point in position e01, the next lowest in e02, and so on. This table can now be used to look up valid price points. The procedure call (indirectly) provides a class and (directly) provides a target price as arguments, and a valid price point is returned based on the selected matching technique. See the following examples for an example that uses this table.
<expression> is any valid expression that results in a value of the same data type as the <keymeasure>. In the description that follows, this value is referred to as the key value. <keymeasure> is the name of the measure to be used as a key when matching the key value against the table. <resultmeasure> is an optional measure that holds the return value. If <resultmeasure> is not specified, <keymeasure> is used for the values of the result as in the price point example.
The procedure attempts to match the key value against an entry in the table. The innermost non-time dimension in the base intersection of the <keymeasure> is assumed to be the dimension along which entries in the table are indexed. For all other dimensions in the base intersection of the <keymeasure>, the procedure will match against the parent at that dimension of the cell being evaluated.
Note:
The values in <keymeasure> must be in ascending order and must not contain any repeated values. A value that is either out of sequence or repeated designates that the previous value is the last entry in the table. In other words, only the sorted elements in the key measure will be considered in the lookup process.
The <matching technique> specifies the matching technique to be used when an exact match of the <keymeasure> against the key value is not found. If the matching technique is exactmatch, <nomatchvalue> is a numeric value that must be specified to indicate the value to use in cells when there is no exact match. Otherwise, if the key value is higher than the highest value in the “table," or lower than the lowest value in the table, it is assumed to match against the highest or lowest value accordingly. If the matching technique is high and no match against the key value is found, the procedure returns the value of the <resultmeasure> for the entry immediately higher than the key value. If the matching technique is low and no match against the key value is found, the procedure returns the value of the <resultmeasure> for the entry immediately lower than the key value. If the matching technique is nearest and no match against the key value is found, the procedure returns the value of the <resultmeasure> for the entry immediately lower than the key value or immediately higher than the key value, depending upon which entry is nearest (this is like rounding to the nearest value). If the matching technique is average and no match against the key value is found, the procedure returns the numeric average of the value of the <resultmeasure> for the entry immediately lower and immediately higher than the key value, or it generates an error if the <resultmeasure> is not of numeric data type.
If the matching technique is interpolate and no match against the key value is found, the procedure returns an interpolated value between the value of the <resultmeasure> for the entry immediately lower and immediately higher than the key value, or it generates an error if the <resultmeasure> is not of numeric data type. The interpolation is calculated as shown in Figure B-6.
Inverse
The tablelookup procedure does not have an inverse.
Examples
-
tablelookup(tgtpr, nearest, pp)
-
Returns the nearest valid value of the pp measure to the supplied target price (tgtpr).
-
tablelookup(perc, interpolate, epct, elast)
-
Looks up the percentage markdown (perc) of the current position against a percentage change elasticity table (epct). Returns the matching elasticity value (elast). If the percentage markdown is not found in the table, the procedure will interpolate the elasticity value from the nearest values higher or lower than the percentage markdown.
flookup
The fixed look up function returns the value of a measure for an explicitly named fixed intersection.
Syntax
flookup(<measure>, <posspec1> [, <posspec2> … , <posspecn>])
Where <posspec1-n> is: [<hierarchy>].[<dimension>].[<positionname>]
<measure> is the measure to be looked up. This <measure> must conform to the measure being calculated as follows. Some hierarchies may be present in the base intersection of both measures, and these are handled by normal non-conforming logic. For any hierarchies that are only in the base intersection of the measure being calculated (the output measure), all the positions will look up the same value. For any hierarchies that are only in the base intersection of the <measure> (input measure), the position to be used must be explicitly named through a position specification (<posspec>).
Note:
If the position to be used can only be specified indirectly (for example, if it is held in a measure), the flookup function cannot be used, and the more powerful lookup procedure should be used instead.
flookup can be used to return a constant or a slice. In case of a constant, the NA value of the flookup function will be the value of the constant. In case of a slice, the NA value of the flookup function will be the NA value of <measure>.
For each <posspec> that is specified, the <hierarchy> must be the name of a valid hierarchy, the <dimension> must be the name of a valid dimension in that hierarchy, and the <positionname> must be the name of a valid position in that dimension, If the position name includes special characters, it can be enclosed in quotes ( " " ) in addition to the standard requirement for square brackets ( [ ] ). If <hierarchy> is not a valid hierarchy or <dimension> is not a valid dimension in that hierarchy, or <positionname> is not a valid position in that dimension, an error is generated.
Additionally, <dimension> must be a dimension in the base intersection of <measure>. To use dimensions not in the base intersection, the <measure> must have a level modifier to explicitly raise it to the desired dimension.
There is no special cycle breaking logic for the flookup function. This means that a measure may never be calculated from the flookup of the same measure. The flookup function returns the value of the expression from the specified fixed intersection.
Inverse
The flookup function does not have an inverse.
Examples
-
flookup(perc, [flvl].[flvl].[flvla])
-
Returns the value for the measure perc for the position flvla in the flvl dimension of the flvl hierarchy.
-
flookup(leadtime, [prod].[cls].[class1], [loc].[whse].[whseA])
-
Returns the value for the measure leadtime for the class class1 for the warehouse whseA.
aggregate
The aggregate procedure provides similar functionality to the hybrid aggregation type. Measures that use the hybrid aggregation type cannot be manipulated higher than their base intersection (as there is no mechanism to spread changes), but since the aggregate procedure is used on recalc measures, they can be changed with the change being applied through normal mapping rules. In addition, the aggregate procedure has a recalc aggregation type that is not available in the hybrid aggregation method.
This procedure returns the value of a measure aggregated from the base intersection to the current level using the supplied aggregation type.
Syntax
aggregate (<cachemeasure>, <hierspec1> [, <hierspec2> … , <hierspecn>])
where <hierspec1-n> is [<hierarchy>].<aggtype>
The rule writer specifies a <cachemeasure> that holds the base intersection values to be aggregated, and it is also the source of values for recalc aggregation.
The rule writer also specifies the aggregation type for each hierarchy and the priority sequence to be used. The priority sequence is required because at levels that are aggregated in more than one hierarchy (for instance, Department/Region/Month for a measure with a base intersection of Class/Store/Week), different results would usually be obtained by aggregating up each of the hierarchies. For example, if the requirement is to aggregate up the product hierarchy by using the total aggregation type, up the location hierarchy by using the average aggregation type, and up the calendar hierarchy by using the first aggregation type. There are three potential ways to calculate a value at Department/Region/Month. We could total from Class/Region/Month, average from Department/Store/Month, or first from Department/Region/Week. These would almost certainly generate three completely different values. By providing a priority sequence, the rule writer explicitly determines which of these values are required. See the worked example.
Note:
The effect of a series of aggregations of the same type up a single hierarchy may return different results from those of a measure with the same aggregation type. ‘Normal' aggregation for a measure driven by its aggregation type is performed from all base intersection cells descended from the cell being evaluated. For example, for a measure with a base intersection of Class/Week and an ‘average' aggregation type, the value calculated for a cell at Department/Month is the average of all values for all Class/Week cells for the Department/Month. If the measure is a recalc measure, calculated at aggregated levels from a rule with an aggregate function, such as aggregate(x, [prod].average, [clnd].average), the value for the Department/Month will be the average of all the Class/Months (not Class/Weeks) that belong to the Department/Month. Other than coincidentally, this would generate a different value.
<cachemeasure> is the measure to be aggregated, and the value of <cachemeasure> is also the value used for cells that are at the base intersection (bottom levels), and at aggregated levels when the required aggregation type is recalc. <hierarchy> is the name of a valid hierarchy. Each hierarchy may only be specified once in the procedure, but hierarchies may appear in any order. The sequence that the hierarchies are specified in is used to determine which hierarchy to aggregate up if the cell being evaluated is at an aggregated level in more than one hierarchy. In this circumstance, aggregation is performed up the first specified hierarchy that the cell is at an aggregated level in, and the other hierarchies are ignored. <aggtype> specifies the aggregation type to be used. The <aggtype> must be one of the standard aggregation types. If any hierarchy that is in the scope of the measure being calculated is not explicitly specified, the aggregation type of that hierarchy is assumed to be total. Such hierarchies are assumed to be sequenced after all hierarchies that are explicitly referenced, and they are ordered from innermost to outermost.
Note:
The value of the <cachemeasure> is used at the base intersection of the measure being calculated. If, for a given cell, the aggregation type to be used is recalc, the value is also obtained directly from the <cachemeasure> at that level, which will normally have an aggregation type of recalc.
Note:
aggregate is a procedure so it cannot be combined with functions, modifiers, or other procedures in any manner. As a procedure it requires a different syntax: “<-“ instead of “=" when being assigned.
Inverse
The aggregate procedure does not have an inverse.
Examples
-
result <- aggregate(x, [clnd].recalc)
-
For cells at the base intersection, the value is calculated from the measure x. For cells at an aggregated level in the calendar hierarchy, the value is also obtained from the measure x, which we can assume has an aggregation type of recalc, and thus the result of the procedure is as if the aggregation type were recalc, using the usual expression to calculate measure x. If the cell is not at an aggregated level in the time hierarchy, and assuming in this example that the other hierarchies are product and location; in that priority, the value for a cell at an aggregated product level is calculated as the total of all cells for products descended from that product for the same location and time. Otherwise, the value for the cell is calculated as the total of all cells for locations descended from the cell's location for the same product and time.
-
result <- aggregate(x, [loc].average)
-
In a similar manner to the previous example, cells at aggregated levels in the location hierarchy will be calculated by averaging the values of cells for all descendent locations. Otherwise, the value will be totaled up the product or time hierarchy as appropriate.
-
result <- aggregate(x, [clnd].average)
-
Totals up all hierarchies except time, which uses an average aggregation type.
-
result <- aggregate(x, [prod].average, [clnd].first)
-
Averages up the product hierarchy if possible. Otherwise, takes the first child value up the calendar hierarchy. Otherwise, totals up the other hierarchies.
-
result <- aggregate(x, [prod].average, [clnd].last)
-
Averages up the product hierarchy if possible. Otherwise, takes the last child value up the calendar hierarchy. Otherwise, totals up the other hierarchies.
Multi-Level Calculation Example for Aggregate Procedure
Consider a measure calculated from the expression aggregate(x, [prod].total, [loc].avg, [clnd].first). The measure is assumed to have a base intersection of Class/Store/Week.
Examples
Examples of the calculations that would be applied at various levels are as follows:
-
Class/Store/Month: first from Class/Store/Week
-
Class/Region/Month: avg from Class/Store/Month
-
Department/Region/Month: total from Class/Region/Month
Transform Procedures
RPASCE offers the following transformation procedures.
Transform Procedure Requirements
The following libraries must be registered in any PDS that will use the transform procedures:
-
Transform
Example
regfunction -d <pathToDomain> -l Transform
–add
Note:
For all transformation procedures, use of the LABEL parameter in place of the POSNAME parameter when dealing with dimensions with large numbers of positions can adversely affect the performance and memory usage of the procedure. Therefore, use of POSNAME is preferable to use of LABEL when the business case could support either option.
transformSum
transformSum converts data across hierarchies using sum aggregation. The procedure converts data between measures of different dimensionality using a set of map measures to convert positions from the source measure to positions in the target measure. Source measures are aggregated into the target using the sum aggregation method.
Syntax
<target> <- transformSum(<source>,
<transformspec1> [, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-8 provides the input parameters for the transformSum procedure.
Table B-8 Input Parameters for transformSum
Parameter Name | Description |
---|---|
source |
Measure that is being aggregated into <target> measure using the aggregation type of sum. |
transformspec1-n |
This parameters is [<source hierarchy>].[<source dimension>], [<target hierarchy>].[<target dimension>] , [LABEL|POSNAME], <map> The <transformspec> defines which dimension in the source is mapped to which dimension in the target and how the positions are mapped between the dimensions. The <map> measure may either be text or Boolean. If it is text, then the value of the cell contains the position id or label name of a position in the target dimension. The compulsory [LABEL|POSNAME] parameter specifies which method is used. If the <map> measure is Boolean, then its base intersection must include the <source dimension>; any true cells in the map measure will define the positions that are transformed to the target. If a label is not unique within a dimension and the LABEL option is used, then only the first position in the dimension that includes the label will be part of the transformation. |
Table B-9 provides the output parameter for the transformSum procedure.
Table B-9 Output Parameters for transformSum
Parameter Name | Description |
---|---|
target |
Measure into which the <source> measure is aggregated into using the aggregation type of sum. |
Notes
If a hierarchy is in both the source and target measures, then the dimension for that hierarchy in the source and target must be the same, unless the transformation is defined through a mapping transformspec, meaning the source measure cannot have a base intersection of item if the target measure has a base intersection of class and there is no explicit transformation specified from item to class in transformspec.
If a dimension in the target is not in the source and is also not defined by a mapping, then transformation is applied to every position in that dimension.
transformSum only works for numeric measures. Text or Boolean measures will not get transformed.
If a cell in the source cannot be mapped to a position in the target, then it is ignored. The Transform procedure always writes a status message to rpas.log indicating how many cells were successfully transformed, how many cells failed and how many seconds the transformation took to execute.
The source measure and any map measure may be non-conforming. For instance, the source may be defined at month and the map defined at season.
Example
WpVRSlsR <-transformSum(WpSlsR, [LOC].[STR], [DVR].[VR],
LABEL, WpRankTx)
Takes WpSlsR (store/class/month) and transforms it to WpVRSlsR (volume rank/class/month) using label mappings defined in WpRankTx (store/class/season).
transformMax
The transformMax procedure converts data across hierarchies using max aggregation. The procedure operates in the same way as transformSum, except that the aggregation method used is max.
Syntax
<target> <- transformMax(<source>, <transformspec1>
[, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-10 provides the input parameters for the transformMax procedure.
Table B-10 Input Parameters for transformMax
Parameter Name | Description |
---|---|
source |
Measure that is being aggregated into <target> measure using the aggregation type of max. |
transformspec1-n |
This parameter is [<hierarchy>].[<dimension>], [<hierarchy>].[<dimension>] , [LABEL|POSNAME], <map> |
Table B-11 provides the output parameter for the transformMax procedure.
Table B-11 Output Parameters for transformMax
Parameter Name | Description |
---|---|
target |
Measure into which the <source> measure is aggregated into using the aggregation type of max. |
Example
r_ut_out<-transformMax(r_ut_in, [prod].[sku], [clnd].[week],
0, r_ut_map)
Takes r_ut_in (sku/str/day) and transforms it to r_ut_out (sku/str/week) using label mappings defined in r_ut_map (sku/str). Here the maximum across all the days of a week is taken from r_ut_in and stored in the r_ut_out measure using label mappings defined in r_ut_map (sku/str).
transformOr
The transformOr procedure converts data across hierarchies using or aggregation. The procedure operates in the same way as transformSum, except that the aggregation method used is or. Both source and target measures must be Boolean measure types.
Syntax
<target> <- transformOr(<source>, <transformspec1>
[, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-12 provides the input parameters for the transformOr procedure.
Table B-12 Input Parameters for transformOr
Parameter Name | Description |
---|---|
Acsource |
Measure that is being aggregated into <target> measure using the aggregation type of or. Must be a Boolean measure type. |
transformspec1-n |
This parameter is [<hierarchy>].[<dimension>], [<hierarchy>].[<dimension>] , [LABEL|POSNAME], <map> |
Table B-13 provides the output parameter for the transformOr procedure.
Table B-13 Output Parameters for transformOr
Parameter Name | Description |
---|---|
Target |
Measure into which the <source> measure is aggregated into using the aggregation type of or. Must be a Boolean measure type. |
Example
r_ut_out<-transformOr(r_ut_in, [prod].[sku], [clnd].[week],
0, r_ut_map)
Takes r_ut_in (sku/str/day) and transforms it to r_ut_out (sku/str/week) using label mappings defined in r_ut_map (sku/str). Here the Boolean OR across all the days of a week is taken from r_ut_in and stored in the r_ut_out measure using label mappings defined in r_ut_map (sku/str).
transformProp
The transformProp procedure converts data across hierarchies using Proportional spreading. The procedure converts data between measures of different dimensionality using a set of map measures to convert positions from the source measure to positions in the target measure. While the transformSum procedure (and related aggregation procedures) assumes a many->one relationship as it performs the transformation (aggregation), the transformProp assumes a one-to-many relationship between the source and target cells (spreading).
Each source value is spread to a set of target values, leaving the ratio between the target values intact.
If the sum of all target cells is zero, then the source is spread evenly to the targets.
Syntax
<target> <- transformProp(<source>, <transformspec1>
[, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-14 provides the input parameters for the transformProp procedure.
Table B-14 Input Parameters for transformProp
Parameter Name | Description |
---|---|
source |
Measure that is being spread into <target> measure. |
transformspec1-n |
This parameter is [<hierarchy>].[<dimension>], [<hierarchy>].[<dimension>] , [LABEL|POSNAME], <map> |
Table B-15 provides the output parameter for the transformProp procedure.
Table B-15 Output Parameters for transformProp
Parameter Name | Description |
---|---|
target |
Measure into which the <source> measure is spread. |
Note
If the <source> measure has a calendar dimension, then the r_elapsed measure has to have a value. (This is true for all TransformSpread flavors: transformProp, transformRepl, transformEven)
Example
mace -d . -run -expression "r_ut_out <- transformProp(r_ut_in,
[clnd].[day], [loc] .[str], 0, r_ut_map)
transformEven
The transformEven procedure converts data across hierarchies using Even spreading.
Syntax
<target> <- transformEven(<source>, <transformspec1>
[, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-16 provides the input parameters for the transformEven procedure.
Table B-16 Input Parameters for transformEven
Parameter Name | Description |
---|---|
source |
Measure that is being spread into <target> measure. |
transformspec1-n |
This parameter is [<hierarchy>].[<dimension>], [<hierarchy>].[<dimension>] , [LABEL|POSNAME], <map> |
Table B-17 provides the output parameter for the transformEven procedure.
Table B-17 Output Parameters for transformEven
Parameter Name | Description |
---|---|
target |
Measure into which the <source> measure is spread. |
Note
If the <source> measure has a calendar dimension, then the r_elapsed measure has to have a value. (This is true for all TransformSpread flavors: transformProp, transformRepl, transformEven)
Example
mace -d . -run -expression "r_ut_out <- transformEven(r_ut_in, [clnd].[day], [loc] .[str], 0, r_ut_map)"
transformRepl
The transformRepl procedure converts data across hierarchies using Replicate spreading.
Syntax
<target> <- transformRepl(<source>, <transformspec1>
[, <transformspec2> … , <transformspecn>])
Input Parameters
Table B-18 provides the input parameters for the transformRepl procedure.
Table B-18 Input Parameters for transformRepl
Parameter Name | Description |
---|---|
source |
Measure that is being spread into <target> measure |
transformspec1-n |
This parameter is [<hierarchy>].[<dimension>], [<hierarchy>].[<dimension>] , [LABEL|POSNAME], <map> |
Table B-19 provides the output parameter for the transformRepl procedure.
Table B-19 Output Parameters for transformRepl
Parameter Name | Description |
---|---|
target |
Measure into which the <source> measure is spread. |
Note
If the <source> measure has a calendar dimension, then the r_elapsed measure must have a value. (This is true for all TransformSpread flavors: transformProp, transformRepl, transformEven)
Example
mace -d . -run -expression "r_ut_out <- transformRepl(r_ut_in,
[clnd].[day], [loc] .[str], 0, r_ut_map)"
Normalization and Resizing Functions
This section provides details on the normalization and resizing functions.
resize
This uses the shape of a time series to produce another time series of a different length, but with the same shape.
Syntax
resize(<expression>, <start>, <fromlength>, <tolength>, <dst_start>)
Where <expression> is a measure or expression whose time series is to be used, and <start>, <fromlength> and <tolength> are expressions that calculate numbers. <start> is assumed to be a calendar index number; if its value is numeric but non-integer, only the integer portion will be used. If its value is a date type, the date value is converted to a calendar index internally. If <fromlength> or <tolength> are less than 0, or either parameter is non-numeric or when added to <start>-1 is outside the scope of the calendar index numbers for the dimension being calculated, an error is generated. If <fromlength> or <tolength> are non-integer, only the integer portion will be used. <dst_start> is an optional input. It can be a date type measure. If so, the date value is converted to a calendar index internally. It can also be a numeric value. If it's a numeric value, it represents the first calendar index that the output time series is written to. If omitted, it is always 0.
The function returns a time series that is resized such that the overall shape of the values is retained, but the number of time periods is stretched or shrunk from <fromlength> or <tolength>. For time periods outside the horizon covered by <start> and <start> -1 + <tolength> (if there are any), the function will return zero – if values other than this are required, or if no update to those periods is required, the function should be wrapped in an if function that can set the appropriate value or use the ignore clause, as appropriate.
The function stretches or shrinks the section of the time series by interpolation or decimation. The algorithm uses upsampling, convolution, and then downsizing. The filter used in convolution is a finite impulse response (FIR) lowpass filter, using a hamming window with cut-off frequency and length determined from greatest common denominator of the source and destination time series lengths.
The values generated for individual cells through this process are not normalized (for a similar function that normalizes the result, see the resizenorm function), and will be of similar magnitude to the cell values for the source cells.
Inverse
The resize function does not have an inverse.
Examples
-
resize(profile, first, 10, 17)
-
The first 17 periods of the result time series will have values with a shape the same as the first 10 periods of the measure profile. All other periods will be zero.
-
resize(lag(profile,startweek), startweek, profilelength, numweeks)
-
This example should be compared with the similar example of the normalize function. It uses a profile to generate a sales plan for an item for a specified length of time from a specified period of time. The profile is not necessarily the same length as the period for which sales are to be generated. The measure profile is assumed to have a profile (shape) for the sales of an item, starting in the first period with values for a number of periods given by the measure profilelength. startweek is an index number of the period from which sales should be generated for the item. numweeks has the length of the sales profile to be generated. Periods before the startweek or after the startweek-1+numweeks will have a result of zero. The periods from startweek to startweek-1+numweeks will have the result of the first profilelength weeks of the profile measure, stretched or shrunk to fit the appropriate number of periods.
resizenorm
This uses the shape of a time series to produce another time series of a different length, but with the same shape, normalized to a specific total.
Syntax
resizenorm(<expression>, <start>, <fromlength>, <tolength>[, <total>], <dst_start>)
<total> is an expression that returns a numeric value. If <total> is not specified, it is assumed to be the sum of the cells of <expression> from startweek to startweek-1+fromlength. See the resize function for an explanation of the other parameters.
This function is identical to the resize function, except that the calculation engine automatically normalizes the resized values to the specified <total>.
Inverse
The resizenorm function does not have an inverse.
Examples
-
resizenorm(profile, first, 10, 17)
-
The first 17 periods of the result time series will have values with a shape the same as the first 10 periods of the measure profile. All other periods will be zero. The values of the cells will be such that sum of the 17 generated periods of the result time series will be the same as the first 10 periods of the measure profile.
-
resizenorm(lag(profile,startweek), startweek, profilelength, numweeks, targetsales)
-
This example should be compared with the similar example of the resize function. The generated sales will be normalized so that their sum is the value of the targetsales measure.
-
resizeprofile
The resizeprofile function is a rewrite of the resizenorm function. The resizeprofile function is intended as a functional replacement for the resize and resizenorm functions.
Note:
Users are encouraged to replace the expressions containing resize and resizenorm functions with resizeprofile. The resize and resizenorm functions are still maintained for backward compatibility.
Syntax
-
resizeprofile(expression, start, fromlength, tolength, dststart: <dststart>, total: <total>)
-
Where <expression> is a measure or expression whose time series is to be used, and <start>, <fromlength> and <tolength> are expressions that calculate numbers. <start> is assumed to be a calendar index number; if its value is numeric but non-integer, only the integer portion will be used. If its value is a date type, the date value is converted to a calendar index internally. If <fromlength> or <tolength> are less than 0, or either parameter is non-numeric or when added to <start>-1 is outside the scope of the calendar index numbers for the dimension being calculated, an error is generated. If <fromlength> or <tolength> are non-integer, only the integer portion will be used. <dststart> is an optional input. It can be a date type measure. If so, the date value is converted to a calendar index internally. It can also be a numeric value. If it is a numeric value, it represents the first calendar index that the output time series is written to. If omitted, it is always 0.
-
The function returns a time series that is resized such that the overall shape of the values is retained, but the number of time periods is stretched or shrunk from <fromlength> or <tolength>. For time periods outside the horizon covered by <start> and <start> -1 + <tolength> (if there are any), the function will return zero. If values other than this are required, or if no update to those periods is required, the function should be wrapped in an if function that can set the appropriate value or use the ignore clause, as appropriate.
-
The function stretches or shrinks the section of the time series by interpolation or decimation. The algorithm uses upsampling, convolution, and then downsizing. The calculation engine automatically normalizes the resized values to the specified <total>.
Usage
The usage text of this function is as follows:
-
resizeprofile(expression, start, fromlength, tolength, dst_start: <dst_start>, total: <total>) where:
-
expression: is a measure or expression, whose time series is to be used in the calculations. This is a required input.
-
start: denotes the index number of the calendar dimension of expression. The algorithm processes data points from this index number going forward. This is a required input.
-
fromlength: together with start, this input establishes which portion of the curve should be processed. fromlength determines the length of the original curve. This is a required input.
-
tolength: determines the length of the output curve. This is a required input.
-
dst_start: this is a named value pair denoting an optional input, which determines the index of the starting point of the output curve. If not specified, it defaults to zero.
-
total: this is a named value pair denoting an optional input whose numeric value is used to normalize the resized curve. If total is not specified, skip the Normalize step.
-
Examples
-
"MeasureB=resizeProfile(MeasureA, 0, 10, 30, dststart:1)"
-
resizeprofile will take the curve represented by the 10 positions starting at index 0 in MeasureA and resize that curve to fit the 30 positions starting at index 1 in MeasureB.
-
"MeasureD=resizeProfile(MeasureA, 0, 10, 25, dststart:1, total:200)"
-
resizeprofile will take the curve represented by the 10 positions starting at index 0 in MeasureA and resize that curve to fit the 25 positions starting at index 1 in MeasureD. While performing the resize operation, resizeProfile will normalize the curve to a total of 200 across all destination positions.
-
"MeasureD=resizeProfile(MeasureC + MeasureA, 0, 15, 30, dststart:2, total:100)"
-
resizeprofile will take the curve represented by the 15 positions starting at index 0 in the expression “MeasureC + MeasureA" and resize that curve to fit the 30 positions starting at index 2 in MeasureD. While performing the resize operation, resizeProfile will normalize the curve to a total of 100 across all destination positions.
String Functions
This section provides details on the string functions.
uppercase
Converts a string to upper case.
Syntax
uppercase(<expression>)
Where the value of <expression> is returned as a string with upper case characters. This is useful in making string comparisons.
lowercase
Converts a string to lower case.
Syntax
lowercase(<expression>)
Where the value of <expression> is returned as a string with lower case characters. This is useful in making string comparisons.
textCompare
Performs a case-sensitive comparison of two strings.
Syntax
textCompare(<expression1>, <exprssion2>)
Where the two input arguments <expression1> and <expression2> must have a type of string. The result type is Boolean. The result value is a Boolean value of the case-sensitive comparison of the two RHS (right hand side) expressions.
The number of input arguments is 2. The number of output arguments is 1.
textConcat
Concatenates string arguments.
Syntax
textConcat(<expression1> ,<expression2>[,… ,<expressionN>])
Where the value of all expressions is either a string type measure or a string literal. Concatenates two or more values into a single string.
substr
This returns a portion of the input String measure's value.
Syntax
substr(<inputMeasure>[,<startIndex>,<length>])
Where <inputMeasure> must be a string type measure and the optional <startIndex> and <length> arguments are either integer measures or literal integer values. The substr function will take the portion of the input string beginning at <startIndex> (which defaults to 0 if not specified) and spanning the amount of characters specified by the <length> argument (which defaults to the length of the input string if not specified). If the end index of the copy (calculated as <startIndex> + <length>) is greater than the length of the input string, substr will pad the input string with spaces to make it long enough to be copied.
ConvertToString
The ConvertToString function will return the string representation of any non-string measure. The number and type of input arguments will change, depending on the type of first argument to the function, but it will always return string values.
The first argument is the input measure which contains the non-string values which needs to be converted to string. This is a mandatory input for ConvertToString.
Syntax - ConvertToString when input measure type is real
strMeas = ConvertToString(realMeas,precision: <precision>,separator:<separator>,decimalmark:<decimalmark>)
If we pass in a real measure as first input argument to the ConvertToString function, then the output measure will contain the input measure's real numbers converted to string.
When the input measure is of type real the function will accept an additional optional argument of type integer which is the precision to be used on the input real values before they are converted to string. Precision is an optional integer constant or scalar integer measure. If precision is not specified a default precision value of 14 will be used. This is because, as a rule, the default value is set to be as precise as possible. This is consistent with current default used by RPAS CE, 14 is the internal default precision used by the RPASCE when converting a double to string by utilities like printArray.
Another optional argument is the decimal mark which is also of type string. Decimal mark can be a string constant or a scalar string measure. If the decimal mark string is not provided ‘.' will be used as the default decimal mark.
Syntax - ConvertToString when input measure type is integer
strMeas = ConvertToString(intMeas,separator:<separator>)
If we pass in an integer measure as first input argument to ConvertToString function, then the output measure will contain the input measure's integer numbers converted to string.
Syntax - ConvertToString when input measure type is date
strMeas = ConvertToString(dateMeas,dateFormat:<dateFormat>)
If a date measure is passed as first input argument to the ConvertToString function, then the output measure will contain the input measure's numeric date values converted to string. In addition, if the first input argument is a date type measure, the ConvertToString function will accept a second optional argument of type string that is the date format string. The second argument must be prefixed with the label dateformat followed by a colon, in the same way as the other labels used in RPASCE functions. For example, dateformat:%d%h%Y. The internal numeric dates in the input measure will be converted to string according to the format specified in the format string and stored in the output string measure. If second argument is not specified, the result string will be in the format "%d %h %Y.
The date format string is expected in the form %[variable]. Variable can be any of the following.
-
B: month, full name
-
h: month, 3-character abbreviation, such as JAN, FEB, MAR
-
Y: 4-digit year
-
y: 2-digit year
-
m: 2-digit month
-
d: 2-digit day
-
H: 2-digit hour
-
M: 2-digit minute
-
S: 2-digit second
-
s: 3-digit millisecond
Syntax - ConvertToString when input measure type is Boolean
strMeas = ConvertToString(boolMeas, trueString:<trueString>,
falseString:<falseString>)
If we pass in a Boolean measure as first input argument to the ConvertToString function, then the output string measure will contain the input measure's Boolean values converted to string. This function takes three additional string arguments. We will refer to the first two as trueString and falseString. These two strings are expected to be used in place of Boolean values true and false in the result. Each true cell value in the input measure will be stored as the trueString in the output string measure and each false cell value in the input measure will be stored as falseString in the output string measure. If the second and third arguments are not specified, then by default English strings true and false will be used.
Math Functions
This section provides details on the math functions.
pow
This returns the value of a number raised to the power of another number (x to the power of y).
Syntax
pow(<x>, <y>)
<x> and <y> are expressions that return real numbers. <y> designates the exponent to which <x> is raised.
exp
This returns the value of the transcendental number e raised to the power of a number (e to the power of x).
e is the base of natural logarithms.
Syntax
exp(<x>)
<x> is an expression that returns a real number to which the number e (value 2.71828183) is raised.
sqrt
This returns the square root of a number.
Syntax
sqrt(<x>)
<x> is an expression that returns a real number. This function returns the equivalent of pow(x, 0.5).
log
This returns the logarithm of a number.
This function returns the exponent that indicates the power to which a number is raised to produce a given number.
Syntax
log(<x>, [<base>])
Where <x> and <base> are expressions that return real numbers. If <base> is not specified, the default value is 10.
Examples
-
log(100)
-
The logarithm of 100 to the base 10 is 2.
-
log(125, 5)
-
The logarithm of 125 to the base 5 is 3.
ln
This returns the natural logarithm of a number.
This function returns the logarithm of <x> to base e (2.71828183).
Syntax
ln(<x>)
<x> is an expression that returns a real number.
mod
This returns the remainder as the result of the division of 2 numbers.
The result of this function is the remainder of <x> divided by <y>.
Syntax
mod(<x>, <y>)
<x> and <y> are expressions that return real numbers.
Example
-
mod(5, 2)
-
The remainder of 5 divided by 2 is 1.
abs
This returns the absolute value of a number.
Syntax
abs(<x>)
<x> is an expression that returns a real number.
rand
This is used to generate random values of type integer, real, and date. The return type of rand and the number and type of input arguments will depend on the type of the LHS measure.
In all cases of the rand function described in the following sections, low and high must be the first two parameters. They do not need to be in a fixed order; the function will select the upper value for high and the lower value for low. Low and high can be constants, scalar measures, or regular measures with a base intersection.
-
Base intersection of the low and high measures can be at or higher than the base intersection of the LHS measure. If they are at a higher intersection the values will be spread down using the repl method before being used.
-
When the upper limit is lower than the lower limit rand function will internally compare the limit values and generate a random value that falls between the two limit values. Also, low and high are included in the range of possible random values generated by rand. Therefore rand(1, 10) can generate 1 or 10 or anything in between, same as rand(10, 1). If low and high are measures, then rand generates values that fall between the two measures.
-
Seed is an optional input into the random generation algorithm. Seed can be either an integer or a real number. The same seed will produce the same set of random values. Note that this is the behavior of random number generator algorithms in general and not specific to RPASCE. The seed argument may be more applicable in the testing/verification process where the same test random data can be generated multiple times using the same seed. When using the seed argument, the value needs to be preceded by the “seed:" label. The use cases have an example of proper usage.
Syntax - For real and integer type
resultMeas = rand(lowerLimit,upperLimit[,seed:<seed>])
When the LHS measure is an int or real type measure, the rand procedure generates random numbers that falls between the lower limit number (lowerLimit) and the upper limit number (upperLimit). For int or real type LHS measures lowerLimit and upperLimit are mandatory inputs.
If you pass in real numbers as lowerLimit or upperLimit and the LHS measure is an int type measure, then the real limit values will be rounded to the nearest integer before being used.
Syntax - For date type
dateMeas = rand(startDate,endDate[,dateformat:<datefomrat>][,
seed:<seed>])
When the LHS measure is a date type measure, the rand procedure generates random dates that fall between startDate and endDate. startDate is the lower limit date for the range of dates within which random dates need to be generated and endDate is the upper limit of that range. When LHS measure is date type startDate and endDate are mandatory inputs. startDate and endDate can be constants, scalar measures or regular measures with a base intersection.
String type is allowed for startDate and endDate when they are constants or scalar measures. In that case date format string will be used to convert startDate and endDate to internal numeric date values.
If startDate and endDate are measures with base intersection, then they need to be of type date and cannot be of string type. In this case date format argument if supplied will be ignored.
dateformat is an optional input string that specifies the format of the startDate and endDate if they are strings. If dateformat string is not provided the default position format value in the PDS will be used. Internally this format can be found in be found in the diminfo array of the meta.db. Position format is usually specified only for the inner most dimension in the calendar hierarchy (usually day dimension). This argument must be preceded by the label dateformat.
The date format string is expected in the form %[variable]. Variable can be any of the following:
-
B: month, full name
-
h: month, 3-character abbreviation, such as JAN, FEB, MAR
-
Y: 4-digit year
-
y: 2-digit year
-
m: 2-digit month
-
d: 2-digit day
-
H: 2-digit hour
-
M: 2-digit minute
-
S: 2-digit second
-
s: 3-digit millisecond
If date format is being used Year, month and day are required. Time (hour, minute, second and millisecond) is optional. If time is not specified all 0's will be used for time which will be 00:00:00:000 using format H:M:S:s.
Other Functions and Procedures
This section provides details on other functions and procedures.
multisource
The multisource procedure calculates a workbook-only recalc measure, based upon the intersection that the measure is currently displayed at. The multisource procedure takes as arguments a list of measures at different base intersections. When evaluating the output measure, the intersection of the current worksheet is used to determine which of the right-hand side (RHS) measure's values must be assigned to the LHS measure.
Syntax
multisource(<inputMeas1>,<inputMeas2>…<inputMeasN>[,<performAggregation>])
Where <inputMeas1> through <inputMeasN> are measures at differing base intersections. When the multisource expression is evaluated, the input measure with the appropriate base intersection is used.
The <performAggregation> flag is a Boolean value (true or false). When this flag is set to True and there is no input measure at the evaluated intersection, then the closest measure will have its values aggregated based on that measure's aggregation method, and those values are used.
Multisource is useful when you need to load and display non-aggregated data at different intersections within a single measure. To achieve this without multisource measures, you must have multiple measures at each of the required intersections. This decreases usability since the user sees many different measures and many invalid cells. The following example shows the number of measures that would be needed to support just the different levels of the product hierarchy. This would be exploded out for each combination of intersections along the different hierarchies.
However, with the use of multisource measures, the same requirements met by the previous example are achieved with a single measure, the result of which is shown in Figure B-8.
Left Hand Side (LHS) Measure Properties
LHS measures must have the following attributes and properties:
-
Base intersection: At or higher than the worksheet intersection like any other workbook measure.
-
Aggregation Type: RECLC. (This is recalculated whenever the display intersection changes.)
-
Spread Type: None (gets recalculated whenever the measure gets spread down)
-
Materialized Type: Persistent. (This is persisted only in the workbook database. It cannot have a application database). LHS measures database property must not be specified.
-
Base State: Read only
-
Agg State: Read only
-
Measure Type: Numeric, Date, String and Boolean
-
The special expression must be part of a calc rule only. This validation check must be exclusively performed in the RPASCE Configuration Tools.
LHS Measure Restrictions and Validations
If the expression is triggered as part of a calc rule through workbook and any of the LHS measure properties are not met, then a marshallable exception is thrown by the server. An error message is displayed that describes the cause of exception. After closing the error message window, you can either close the workbook normally or continue working on the same workbook without performing any calculation. On the Configuration Tools side, a validation failure results in displaying the context of validation in red text and prevents the rpaInstall from building the PDS. The properties previous listed must be validated for the LHS measure on the RPAS CE Server and Configuration Tools.
Right Hand Side (RHS) Measure Properties
RHS measures must have the following attributes and properties:
-
MeasureType: RHS measures inputMeas1, inputMeas2,inputMeas3 are of the same type as the type of the LHS measure.
-
Base Intersection: RHS measures inputMeas1, inputMeas2,inputMeas3 must have different base intersections.
-
Min and Max Number of RHS measures: The minimum number is 1 and maximum number is 200.
-
Scalar measure: If LHS measure is a scalar, there can be only one RHS measure, and it must be a scalar measure. Since the number of RHS arguments can vary from 1 to 200, the condition when LHS measure is scalar can be met by providing a single RHS measure which is also a scalar.
-
Since aggregation of RHS measures is allowed, the RHS measures base intersection can be at or higher or lower than the LHS measure base intersection. Whenever an exact match for the LHS measure display intersection is found on the RHS side, that measure gets used otherwise whichever RHS measure that has the nearest base intersection to the LHS measure's display intersection gets used after aggregation.
-
RHS measures database property can have a value as they can be persisted in both PDS and workbook.
-
The right most argument of RHS must be checked for a constant after the previous validation check. If it is a constant, then the remaining RHS arguments must be all measures. There can be only one optional constant in the expression and that must be the right most argument.
RHS Measure Restrictions and Validations
The conditions previously described must be validated for the RHS measures on the RPASCE Server and Configuration Tools. If the validation fails, a marshallable exception is thrown on the RPASCE Server side.
Rule Group Restrictions
The following validation checks must be exclusively performed in the Configuration Tools:
-
The multisource expression can be used only in calc rule groups.
-
LHS measure cannot appear on the RHS of any expression in any rule group.
cover
The cover function returns the number of future periods for which stock covers sales.
Alternately phrased, that is a forward weeks of supply, or the number of future periods of sales that could be satisfied from the stock with no further receipts.
The cover function allows for two sales expressions, where the second is a wrap around expression to provide a well-defined cover for periods at or near the end of the calendar horizon that would otherwise run out of forward sales. An offset is also specified to allow the cover function to behave appropriately for both opening and closing stock.
Unlike other functions, use of the level modifier is not supported in the stockexpression, salesexpression, offsetexpression, or wraparoundsalesexpression. Calculation at aggregate levels is possible, but the aggregates need to be computed first, and then the aggregated expressions can be used in cover/uncover.
Syntax
cover(<stockexpression>, <salesexpression>[, <offsetexpression>,
[<wraparoundsalesexpression>]])
Where <stockexpression> is an expression or measure that represents the ‘stock' <salesexpression> is an expression or measure that represents the sales. <offsetexpression> is an expression that calculates a number that represents the offset to apply. If the value is non-integer, only the integer portion is used. If the value is non-numeric, an error is generated. If <offsetexpression> is not provided, the default value will be 1. <wraparoundsalesexpression> is an expression or measure that represents the wrap around sales. If <wraparoundsalesexpression> is not provided, there will be no wraparound, and the function will generate an error if there is insufficient forward sales to calculate the cover.
The <salesexpression> can be considered to define a time series of sales data values, starting at the current period offset by the <offsetexpression>, and stretching until the end of the calendar horizon. If this time series is too short to evaluate the cover value, it can be considered extended by one or more copies of the time series implied by the <wraparoundsalesexpression>, if specified, from the start until the end of the calendar horizon. The cover value is calculated by summing down the time series until a sum is reached that is equal to or greater than the value of the <stockexpression>. If the sum is equal to the <stockexpression>, the number of periods used is returned. If the sum is greater than the <stockexpression>, the value returned is the number of periods used minus 1, plus the proportion of the last period reached that is required to exactly reach the value of the <stockexpression>. If the <offsetexpression> causes the start of the time series to be before the start of the calendar horizon, or no <wraparoundsalesexpression> is specified, and there is insufficient ‘forward sales' to determine the cover, an error is generated.
Inverse
The cover function has an inverse function, uncover. uncover returns the amount of stock that is required to give a specified number of forward periods cover. There is no inverse function that solves this relationship for sales (which is used as a time series, rather than a single value).
Note:
The inverse can only apply if the <stockexpression> is a single measure, rather than an expression.
Examples
-
cover(EOP, Sales)
This provides an EOP based forward cover. There is no wraparound sales expression, so this function will generate errors towards the end of the plan horizon.
-
cover(BOP, Sales + MD, 0)
This provides a BOP based forward cover, using Sales plus markdowns as the expression to be covered. There is no wraparound sales expression, so this function will probably generate errors towards the end of the plan horizon.
-
cover(EOP, Sales, 1, Sales)
This provides an EOP based forward cover. Sales itself is used as the wraparound sales expression (this is typical where the plan horizon is a year, since the Sales measure has the appropriate seasonality; where this is not the case, another measure, such as next season sales would be used) so this function will return reasonable values towards the end of the plan horizon when the cover is greater than the number of weeks remaining.
Note:
The cover function is always calculated at the current time dimension. For example, in a plan where the bottom time dimension is week, a measure with an aggregation type of recalc that is calculated from a cover function at the month level will calculate forward months of supply. If forward weeks of supply are required to be calculated for the month dimension, it would be more appropriate to specify the measure with an aggregation type of first or last, so that aggregation, rather than calculation through the rule, is used to generate the values at the month dimension.
Make sure that the wrap around expression, if used, is seeded with appropriate values.
Both the stock and the sales used in the cover function are expressions. This supports various business needs, such as using covers based on sales plus markdowns. If the stock is provided as an expression, rather than just a single measure, the function will not have an inverse.
The offset expression is used to define the offset: from which period to start using the sales expression. It is assumed to be an offset from the current period, so that a value of zero means that the sales for the current period must be used in evaluating the cover (which is appropriate for an opening stock based cover), and an offset of 1 means start in the period following the current period (which is appropriate for a closing stock based cover). Values other than 0 and 1 may be used.
uncover
The uncover function returns the amount of stock required to cover sales for the specified number of forward periods.
The uncover function allows for two sales expressions where the second is a wrap around expression that provides a well-defined cover for periods at or near the end of the calendar horizon that would otherwise run out of forward sales. An offset is also specified to allow the uncover function to behave appropriately for both opening and closing stock.
Unlike other functions, use of the level modifier is not supported in the stockexpression, salesexpression, offsetexpression, or wraparoundsalesexpression. Calculation at aggregate levels is possible, but the aggregates need to be computed first, and then the aggregated expressions can be used in cover/uncover.
Syntax
uncover(<coverexpression>, <salesexpression>[, <offsetexpression>, [<wraparoundsalesexpression>]])
Where <coverexpression> is an expression or measure that represents the cover value <salesexpression> is an expression or measure that represents the sales. <offsetexpression> is an expression that calculates a number that represents the offset to apply. If the value is non-integer, only the integer portion is used. If the value is non-numeric, an error is generated. If <offsetexpression> is not provided, the default value will be 1. <wraparoundsalesexpression> is an expression or measure that represents the wrap around sales. If <wraparoundsalesexpression> is not provided, there will be no wraparound, and the function will generate errors if there is insufficient forward sales to calculate the stock.
The <salesexpression> can be considered to define a time series of sales data values, starting at the current period offset by the <offsetexpression>, and stretching until the end of the calendar horizon. If this time series is too short to evaluate the stock value, it can be considered extended by one or more copies of the time series implied by the <wraparoundsalesexpression>, if specified, from the start until the end of the calendar horizon. The stock value is calculated by summing down the time series for some periods equal to the integer portion of the <coverexpression> and adding the value of the next period, multiplied by the fractional portion of the <coverexpression>. If the <offsetexpression> causes the start of the time series to be before the start of the calendar horizon, or no <wraparoundsalesexpression>, is specified, and there is insufficient forward sales to determine the stock, an error is generated.
Inverse
The uncover function has an inverse function, the cover function. This function returns the number of forward periods of cover implicit in the specified stock. There is no inverse function that solves this relationship for sales (which is used as a time series, rather than a single value).
Note:
The inverse can only apply if the <coverexpression> is a single measure, rather than an expression.
Examples
-
uncover(WOS, Sales)
This provides an EOP stock value that gives the specified weeks of supply. There is no wraparound sales expression, so this function will generate errors towards the end of the plan horizon.
-
uncover(WOS, Sales + MD, 0)
This provides a BOP stock value that gives the specified weeks of supply, using Sales plus markdowns as the expression to be covered. There is no wraparound sales expression, so unless the value of WOS is less than 1, this function will generate errors towards the end of the plan horizon.
-
uncover(WOS, Sales, 1, Sales)
This provides an EOP stock value that gives the specified weeks of supply. Sales itself is used as the wraparound sales expression (this is typical where the plan horizon is a year, since the Sales measure has the appropriate seasonality; where this is not the case, another measure, such as next season sales would be used) so this function will return reasonable values towards the end of the plan horizon when the cover is greater than the number of weeks remaining.
Note:
The uncover function is always calculated at the current time dimension. For example, in a plan where the bottom time dimension is week, a rule or mapping rule that uses an uncover function at the month level will calculate the stock on the assumption that the <coverexpression> provides a forward months of supply. Make sure that the wrap around expression, if used, is seeded with appropriate values. Both the cover and the sales used in the uncover function are expressions. This supports various business needs, such as using covers based on sales plus markdowns. If the cover is provided as an expression, rather than just a measure, the function will not have an inverse. The offset expression is used to define the offset: from which period to start using the sales expression. It is assumed to be an offset from the current period, so that a value of zero means that the sales for the current period should be used in evaluating the cover (which is appropriate for an opening stock based cover), and an offset of 1 means start in the period following the current period (which is appropriate for a closing stock based cover). Values other than 0 and 1 may be used.
min
The min function returns the minimum value from a series of expressions or set of measures.
Syntax
min(<expression1>, <expression2> [, <expression3> … <expressionn>])
Where <expression1-n> are expressions or a set of measures (denoted by {<measureset>} ), which return numeric values. The function returns the minimum value of the expressions.
Inverse
The min function does not have an inverse.
Example
-
min (A, B, C)
-
Returns the minimum of the measures A, B, and C.
max
The max function returns the maximum value from a series of expressions or set of measures.
Syntax
max(<expression1>, <expression2> [, <expression3> … <expressionn>])
Where <expression1-n> are expressions or a set of measures (denoted by {<measureset>} ), which return numeric values. The function returns the maximum value of the expressions.
Inverse
The max function does not have an inverse.
Example
-
max (A, B, C)
-
Returns the maximum of the measures A, B, and C.
sum
The sum function returns the sum of a series of expressions or measure set.
Syntax
sum(<expression1>, <expression2> [, <expression3> … <expressionn>])
Where <expression1-n> are expressions or a set of measures (denoted by {<measureset>} ), which return numeric values. The function returns the summed value of the expressions or measure set.
Inverse
The sum function does not have an inverse.
Example
-
sum (A, B, C)
-
Returns the sum of the measures A, B, and C.
lag
The lag function returns the value of an expression from the previous time period in the dimension being evaluated.
The lag function cannot be used in rule groups containing recalc measures.
Syntax
lag(<expression>)
Where <expression> is any valid expression. The function returns the value of the expression in the previous period. If the current period being evaluated is the first period in the calendar horizon (so that there is no previous period), an error is generated. For that reason, lag functions are usually embedded in if functions or prefer functions to check for that case.
Inverse
The lag function does not have an inverse.
Example
-
lag(EOP)
-
Returns the value of the measure EOP from the previous period.
Note:
The lag function is deliberately intended as a simple version of the timeshift procedure for one of the most frequently used cases, which is that the offset is one period in the past. Use the timeshift procedure for lagging with a variable offset. The lag function has special cycle breaking logic that enables a series of expressions to be calculated in a manner that allows them to be evaluated period wise. This allows an apparent deadly embrace to be broken. Thus the following two expressions are allowed, and can be calculated in the same rule group, even though EOP seems to depend on BOP, which seems to depend on EOP: EOP = BOP + Rec – SLs – MD BOP = lag(EOP) Note, however, that the cycle breaking logic does not support the measure being calculated being lagged on the RHS of the expression. Thus the following expression is not allowed: AccumSls = Sls + lag(AccumSls)
lead
The lead function returns the value of an expression from the next (following) time period in the dimension being evaluated.
The lead function cannot be used in rule groups containing recalc measures.
Syntax
lead(<expression>)
Where <expression> is any valid expression. The function returns the value of the expression in the following period. If the current period being evaluated is the last period in the calendar horizon (so that there is no following period), an error is generated. For that reason, lead functions are usually embedded in if functions or prefer functions to check for that case.
Inverse
The lead function does not have an inverse.
Example
-
lead(BOP)
-
Returns the value of the measure BOP from the next period.
Note:
The lead function is deliberately intended as a simple version of the timeshift procedure for one of the most frequently used cases, which is that the offset is one period in the future. Use the timeshift procedure for leading with a variable offset. In a similar manner to the lag function, the lead function has special cycle breaking logic that enables a series of expressions to be calculated in a manner that allows them to be evaluated period wise. This allows an apparent ‘deadly embrace' to be broken. Even when an error is generated because the current period is the last period in the calendar horizon, the lead function itself, if not guarded by if or prefer functions, returns the re-evaluated NA value of the measure. For example, for the following expression group: A = lead(B) B = A + 1 ...assume that the NA value for both A and B is 0. The system first re-evaluates B's NA value to be A's NA value + 1 = 1 based on the second expression. The system will attempt to retrieve the time period after B's last time period when A = lag(B) is evaluated. Because that time period does not exist, the lead function will return B's re-evaluated NA value instead, which is 1.
timeshift
The timeshift procedure that returns the value of a measure from a time period in the dimension being evaluated that is lagged by a designated number of periods.
This procedure has the following special uses and restrictions:
-
Measures used in this procedure can be modified with the master modifier.
-
Currently timeshift cannot be used in calculation or commit rule groups.
-
Used for lagging the values of a measure by more than one period.
-
Used for lagging/shifting PDS measure data in the PDS batch run.
-
Used for retrieving values from time periods outside the scope of the workbook.
-
Used for addressing 52-53-week year differences.
Syntax
<output> <- timeshift(<input>, {<lagvalue>
| <lagmeas> | <lagmap>})
<input> is the measure that is being lagged and must have the same base intersection as <output> or must be forced to evaluate at the base intersection of <output> by using the level modifier. <input> must include a dimension in the calendar hierarchy and must be the same data type as <output>.
<lagvalue> is a scalar value that designates the number of periods each position in <input> is shifted. A negative value refers to shift forward in calendar dimension (lead), and a positive value refers to shift backward in calendar dimension (lag).
<lagmeas> is a numeric measure that contains values that determine how each position is shifted. <lagmeas> cannot have a calendar dimension and all non-calendar dimensions must be identical to <input>.
Note:
This implies that if either <input> or <lagmeas> measure is modified with the master modifier, the other measure must also be modified with the master modifier.
<lagmap> is a string measure used for sophisticated mappings. It must have the same calendar dimension as <input>. If <lagmap> has no calendar dimension, then the non-calendar dimension must be at same or aggregated level of <input>. The measure contains position names that indicate how each time period is mapped, and it must only contain positions from the dimension from the calendar hierarchy. The value of each position (called the source position here) in the lagmap measure is the name of position in the destination measure to which the data for that source position in the input is mapped. Multiple positions can be specified by separating them using a space. In other words, <lagmap> defines a mapping of positions from the input measure to the destination measure along time. Entries in <lagmap> that are not the names of valid positions in the dimension from the calendar hierarchy are ignored.
Note:
This implies that if either <input> or <lagmap> measure is modified with the master modifier, the other measure must also be modified with the master modifier.
This mapping technique is primarily used when lagging measures between 52 and 53-week years. When mapping multiple positions to a single position (such as mapping the last 2 weeks in a 53-week year to the last week in a 52-week year), the resulting value is the sum of the source values (that is, the sum of the last 2 weeks of the 53-week year). When mapping a single position to multiple positions (such as mapping the last week in a 52-week year to the last 2 weeks in a 53-week year), the source value is replicated to the resulting values (that is, weeks 52 and 53 in the 53-week year are updated to week 52 in the 52-week year).
Note:
timeshift
is a procedure so it cannot be combined with functions, modifiers,
or other procedures in any manner. As a procedure, it requires a different
syntax: “<-“ instead of “=" when being assigned.
Inverse
The timeshift procedure does not have an inverse.
Examples
-
salesly <- timeshift(sales.master, -4)
Updates the positions in the workbook measure for last year's sales with the values from the PDS measure sales where each position is advanced by four periods.
Table B-20 Input for salesly <- timeshift(sales.master, -4)
sales chnl scls week Value -
Catalog
Loafer
w01_2007
10
-
Catalog
Loafer
w02_2007
20
-
Catalog
Loafer
w03_2007
30
-
Catalog
Loafer
w04_2007
40
-
Catalog
Loafer
w05_2007
0
-
Catalog
Loafer
w06_2007
0
-
Catalog
Loafer
w07_2007
0
-
Catalog
Loafer
w08_2007
0
Table B-21 Output for salesly <- timeshift(sales.master, -4)
salesly chnl scls week Value -
Catalog
Loafer
w01_2007
0
-
Catalog
Loafer
w02_2007
0
-
Catalog
Loafer
w03_2007
0
-
Catalog
Loafer
w04_2007
0
-
Catalog
Loafer
w05_2007
10
-
Catalog
Loafer
w06_2007
20
-
Catalog
Loafer
w07_2007
30
-
Catalog
Loafer
w08_2007
40
-
salesly <- timeshift(sales.master, saleslag)
Where sales and salesly have a base intersection of SKU-week, the numeric measure saleslag contains a value for each SKU that indicates the number of periods to lag by SKU.
Table B-22 Input for salesly <- timeshift(sales.master, saleslag)
sales chnl scls week Value -
Catalog
Loafer
w01_2007
10
-
Catalog
Loafer
w02_2007
20
-
Catalog
Loafer
w03_2007
30
-
Catalog
Loafer
w04_2007
40
-
Catalog
Loafer
w05_2007
0
-
Catalog
Loafer
w06_2007
0
-
Catalog
Loafer
w07_2007
0
-
Catalog
Loafer
w08_2007
0
-
Catalog
Boots
w01_2007
10
-
Catalog
Boots
w02_2007
20
-
Catalog
Boots
w03_2007
30
-
Catalog
Boots
w04_2007
40
-
Catalog
Boots
w05_2007
0
-
Catalog
Boots
w06_2007
0
-
Catalog
Boots
w07_2007
0
-
Catalog
Boots
w08_2007
0
saleslag
chnl
scls
-
Value
-
Catalog
Loafer
-
2
-
Catalog
Boots
-
-2
Table B-23 Output for salesly <- timeshift(sales.master, saleslag)
salesly chnl scls week Value -
Catalog
Loafer
w01_2007
30
-
Catalog
Loafer
w02_2007
40
-
Catalog
Loafer
w03_2007
0
-
Catalog
Loafer
w04_2007
0
-
Catalog
Loafer
w05_2007
0
-
Catalog
Loafer
w06_2007
0
-
Catalog
Loafer
w07_2007
0
-
Catalog
Loafer
w08_2007
0
-
Catalog
Boots
w01_2007
0
-
Catalog
Boots
w02_2007
0
-
Catalog
Boots
w03_2007
10
-
Catalog
Boots
w04_2007
20
-
Catalog
Boots
w05_2007
30
-
Catalog
Boots
w06_2007
40
-
Catalog
Boots
w07_2007
0
-
Catalog
Boots
w08_2007
0
-
salesly <- timeshift(sales.master, salesmap)
Where salesmap is a string measure that contains position names indicating which position in sales to use for each position in salesly; the position in salesly whose name is cell contents of salesmap receives the corresponding value from sales. In cases where the current year in the workbook contains 52 weeks, the previous year that is not in the workbook contains 53 weeks; the 52nd position in salesmap could contain the position names w52_2007 and w53_2007, causing the value of salesly to contain the sum of the two positions.
Table B-24 Input for salesly <- timeshift(sales.master, salesmap)
sales chnl scls week Value -
Catalog
Loafer
w02_2007
20
-
Catalog
Loafer
w03_2007
30
-
Catalog
Loafer
w04_2007
40
-
Catalog
Loafer
w05_2007
0
-
Catalog
Loafer
w06_2007
0
-
Catalog
Loafer
w07_2007
0
-
Catalog
Loafer
w08_2007
0
salesmap
-
-
week
Value
-
-
v
w01_2007
w05_2007
-
-
w02_2007
w06_2007
-
-
w03_2007
w07_2007
-
-
w04_2007
w08_2007
-
-
w05_2007
w01_2007
-
-
w06_2007
w02_2007
-
-
w07_2007
w03_2007
-
-
-
w08_2007
w04_2007
Table B-25 Output for salesly <- timeshift(sales.master, salesmap)
salesly chnl scls week Value -
Catalog
Loafer
w01_2007
0
-
Catalog
Loafer
w02_2007
0
-
Catalog
Loafer
w03_2007
0
-
Catalog
Loafer
w04_2007
0
-
Catalog
Loafer
w05_2007
10
-
Catalog
Loafer
w06_2007
20
-
Catalog
Loafer
w07_2007
30
-
Catalog
Loafer
w08_2007
40
round
This returns the value of an expression rounded up or down to the nearest multiple.
Syntax
round(<expression>[, <multipleexpression>])
Where <expression> is any valid expression, which specifies the value to be rounded, <multipleexpression> is an expression that calculates a number that represents the multiplier to use. If the value is not specified, it is assumed to be 1. The value may be non-integer. If the value of either expression is non-numeric, an error is generated. The rounding is up or down to the nearest multiple of the multiplier. If there are 2 multiples equally near to the value (for instance, rounding 1.5 to the nearest integer), then rounding is up (away from zero).
Note:
When the round function is called with the <multipleexpression> argument, round first determines the nearest integer to the input and then determines the nearest multiple of the <multipleexpression>. For instance, round(2.8, 2) first rounds 2.8 to 3 and then returns 4 as the final value. However, round(3.8, 3) first rounds 3.8 to 4 and then returns 3 as the final value.
Inverse
The round function does not have an inverse.
Examples
-
round(qty)
Returns the value of the measure qty, rounded up or down to the nearest integer. If the qty is 14.324, this returns the result of 14, if the qty is 14.824, this returns the result of 15.
-
round(qty, packsize)
Returns the value of the measure qty, rounded up or down to the nearest multiple of the pack size. If the qty is 14.324 and the packsize is 6, this returns the result of 12. If the qty is 16.824 and the packsize is 6, this returns the result of 18.
roundup
The roundup function returns the value of an expression rounded up to the nearest multiple.
Syntax
roundup(<expression>[, <multipleexpression>])
Where <expression> is any valid expression, which specifies the value to be rounded. <multipleexpression> is an expression that calculates a number that represents the multiplier to use. If the value is not specified, it is assumed to be 1. The value may be non-integer. If the value of either expression is non-numeric, an error is generated. Rounding is always up (to the nearest multiple of the multiplier further away from zero).
Inverse
The roundup function does not have an inverse
Examples
-
roundup(qty)
Returns the value of the measure qty, rounded up to the nearest integer. If the qty is 14.324 or 14.824, this returns the result of 15.
-
roundup(qty, packsize)
Returns the value of the measure qty, rounded up to the nearest multiple of the pack size. If the packsize is 6 and the qty is 14.324 or 16.824, this returns the result of 18.
rounddown
The rounddown function returns the value of an expression rounded down to the nearest multiple.
Syntax
rounddown(<expression>[, <multipleexpression>])
Where <expression> is any valid expression, which specifies the value to be rounded, <multipleexpression> is an expression that calculates a number that represents the multiplier to use. If the value is not specified, it is assumed to be 1. The value may be non-integer. If the value of either expression is non-numeric, an error is generated. Rounding is always down (to the nearest multiple of the multiplier closer to zero).
Inverse
The rounddown function does not have an inverse.
Examples
-
rounddown(qty)
Returns the value of the measure qty, rounded down to the nearest integer. If the qty is 14.324 or 14.824, this returns the result of 14.
-
rounddown(qty, packsize)
Returns the value of the measure qty, rounded down to the nearest multiple of the pack size. If the packsize is 6 and the qty is 14.324 or 16.824, this returns the result of 12.
Note:
The round functions have no inverses. Great care should be used in designing rule groups that use these functions, and the preferred technique for rounding is often to not round during calculation, but to round values on display only. The round functions cause problems because they can compromise the integrity of rule and expression relationships. Consider a typical relationship between value, units and price. If the units are calculated through a round function (on the apparently reasonable assumption that units should be integers) after a change to, say, the value, then the integrity of the rule relationships is immediately compromised because the price is no longer the value divided by the units.
navalue
The navalue function returns the NA value of the specified expression.
Syntax
navalue(<expression>)
<expression> can be a constant, a measure, or an expression.
The navalue function does not directly generate errors, but it can propagate errors generated by <expression>.
Inverse
The navalue function does not have an inverse.
Examples
-
navalue(<meas>)
This returns the NA value of <meas>.
-
navalue(<meas1> + <meas2>)
This returns the NA value of the expression <meas1> + <meas2>. In this example, if the NA value of <meas1> is 2 and the NA value of <meas2> is 5, the result of the navalue function will be 7.
propspread
propspread is a multiple result function that spreads a value across a collection of measures while retaining their relative proportions. The multiple results are not named and are therefore positional only. The typical usage of this function is to allow spreading of hierarchical measures.
Syntax
propspread(<totalexpression>, <childexp1>, … <childexpn>)
Where <totalexpression> is an expression that returns a numeric value to which to balance the results of the function, <childexp1> - <childexpn> are expressions that provide the shape of the results. They will typically be the same measures as those assigned to the result of the function but using the old modifier. A measure defined as a result cannot be used on the right-hand side without old.
The function generates n positional results, where n is the number of child expressions. The results will sum to the <totalexpression>, using the shapes of the child expressions in the order of the child expressions.
The number of results must be equal to the number of child expressions, which means that there should be one more argument on the right-hand side than output measures on the left-hand side. Additional child expressions are ignored. If too few child expressions are defined, the function will fail. Currently, there is no validation to warn when this condition occurs.
If the sum of the child expressions is zero, the spread will be even.
Inverse
The propspread function does not have an inverse.
Example
The old modifier can be used in conjunction with the propspread function to implement a hierarchical relationship among measures. In the following example, Total sales (TotalSls) is the “parent" measure and regular sales (RegSls), promotional sales (PromSls), and markdown sales (MkdSales) are the “child" measures. Using old and propspread to configure this relationship allows the manipulation of any combination of these measures before calculating, except for all of them.
In the following example and in other such hierarchical measure relationships, the order of the expressions within a rule is critical for the measures to be correctly calculated.
TotalSls = RegSls + PromoSls + MkdSls RegSls, PromoSls, MkdSls = propspread(TotalSls, RegSls.old, PromoSls.old, MkdSls.old) PromoSls, MkdSls = propspread(TotalSls - RegSls, PromoSls.old, MkdSls.old) RegSls, MkdSls = propspread(TotalSls - PromoSls, RegSls.old, MkdSls.old) RegSls, PromoSls = propspread(TotalSls - MkdSls, RegSls.old, PromoSls.old) RegSls = TotalSls - PromoSls - MkdSls PromoSls = TotalSls - RegSls - MkdSls MkdSls = TotalSls - RegSls - PromoSls
passthrough
passthrough is a multiple result function that is used to encapsulate any number of normal computations into a single expression.
Note:
The passthrough function is not allowed for measures with a recalc agg type.
Syntax
passthrough(<exp1>, <exp2>, …, <exp-n>)
Where <exp1> - <exp-n> are normal expressions used to calculate the resulting measures.
All measures on the left-hand side must be computed at the same base intersection. The number of results must be less than or equal to the number of calculation expressions (additional calculation expressions are ignored). If too few calculation expressions are defined, then function will fail. Currently, there is no validation to warn an individual when this condition is met.
There are two main reasons for using this function:
-
Use passthrough in an expression for a rule when computing values for multiple measures without having to write (develop) a multiple-result function or procedure.
-
To improve performance. If many measures are computed using the same or similar set of RHS measures, combining those calculations using passthrough may be faster because there is less physical input/output with the data.
Inverse
The passthrough function does not have an inverse.
Examples
-
A, B = passthrough(C + D, C - D)
-
Computes the sum and difference of two measures simultaneously.
-
SalesA, SalesB =passthrough(SalesA.old * TempMeas / TotalSales.old, SalesB.old * TempMeas / TotalSales.old)
-
Proportionately spread TotalSales down to its components, SalesA and SalesB.
rankagg
This procedure is to use a numeric ranking to assign a value. When used in conjunction with the recalc aggregation type, rankagg will return the value associated with the highest/lowest rank cell as the aggregate value.
Syntax
The special expression is of the form D <- rankagg(R,
B [, S])
, where
On the left-hand side:
-
D is a string type measure, with aggregation type recalc.
On the right-hand side:
-
R is a numeric measure that contains rank information for each cell in the base intersection of S (if S is available), or each cell in the base intersection of D (if S is not available). This ranking can be generated as a result of calculation or can be loaded at workbook build time.
-
B is a Boolean value (or a scalar Boolean measure). If B is TRUE, the procedure will select the highest rank value, otherwise, the lowest rank value.
-
S is a source measure, which is optional. The rankagg procedure will assign the values of S to the LHS measure D, when evaluated at the base intersection of D. When evaluated at the aggregated intersection, S will provide the value returned by the procedure. When S is not provided, D will be used as both source and destination. At this time, the rankagg procedure will have no effect when evaluated at the base intersection of D. When evaluated at the aggregate level, the procedure will populate the aggregate array from base intersection of D based on the value of R, and then pass the value.
Example
Here is an example for the usage of rankagg procedure, D<-rankagg(R, B, S).
SKU-A, SKU-B, and SKU-C, are positions in a hierarchy that aggregate to SCLS-1.
In the procedure, the measure R is a numeric-valued measure. This is the measure from which the rankagg procedure will identify the maximum or minimum value, based on the Boolean measure B. A value of TRUE instructs the procedure to select the maximum value; FALSE corresponds to the minimum value. In the worksheet, R corresponds to the Sales value measure. For the purposes of this example, Sales value has an agg type of max, just to show what's going on at the SCLS-1 level.
The measure S represents a measure from which the procedure will draw the values that will eventually feed into the “Cell value measure on the worksheet. The “Cell value measure would be the expression's D (for display) measure. S (for source) in this example is a hidden measure. S contains values that could be specified by some calculation. The values in S could be, for example, strings that represent images, though they need not be so.
By evaluating the procedure, at the lowest (SKU/week) level, the rankagg procedure will just copy over the values of S to D. At higher levels, say SCLS-1/week, the rankagg procedure will select a representative value for the “Cell value measure s that is equal to the SKU-level value where the corresponding “Sales value measure (R) has its max (from B) value over the SKU positions.
Note:
In cases where there is more than one cell in the rank measure with the highest (or lowest, if lowest rank is specified) value, RPAS CE will select one of the tied cells to be the highest (or lowest) ranked position
In cases where the source data need not be calculated by an expression, then the rankagg procedure will also support a variant syntax. That is, the rule writer could specify simply D <- rankagg(R, B). In this case, D will be the source (at the base level) and the target (at the aggregate level).
ranksort
The ranksort procedure returns the rank of intersections given the rank order (ascending or descending), the measure to rank upon and the dimensions to rank over.
Syntax
<output> <- ranksort(<input>,<rank order> [,<dimspec1>, …, <dimspecn>])
<output> is the measure that will contain the ranking results. The result of ranking will always be an integer value, so the data type of <output> must be integer or numeric.
<input> is the measure to be ranked.
<rank order> is {ascending | descending}. ascending is a keyword meaning that the intersection will be ranked in ascending value of the <input> measure, and descending is a keyword meaning that the intersection will be ranked in descending value of the <input> measure. All keywords which need to be passed to a function must be wrapped in double quotes ( ). Any other syntax will throw an error.
<dimspec1-n> is [<hierarchy>].{[<dimension>] | top} <dimspec1-n> specifies the dimensions to rank over. For each <dimspec> that is specified, the <hierarchy> must be the name of a valid hierarchy and the <dimension> must be the name of a valid dimension in that hierarchy. top is a keyword that refers to the highest dimension (all) in the hierarchy. <dimspec1-n> is optional, and if omitted the value for each hierarchy in the base intersection of <output> will be [hierarchy].top. A <dimspec> for a hierarchy that is not in the base intersection of <output>, or that references a dimension that is not higher than (a parent/grandparent and so on, of) the dimension in that hierarchy in the base intersection of <output>, or which references a hierarchy that already has a <dimspec>, is an error.
The base intersection of <output> determines the intersections that will be ranked. If the base intersection of <input> is different to that of <output>, as will usually be the case, then the values of <input> used for ranking will be the values at the intersections implied by the base intersection of <output> obtained by normal non-conforming measure handling, with replication from higher dimensions and/or aggregation from lower dimensions.
The scope of the ranking is dictated by <dimspec1-n>. These will usually be implied rather than explicitly specified and be at the top of the hierarchy. However, when a dimension is specified, there will be a separate ranking for each position (or combination of positions where a dimension is specified in two or more hierarchies) in that dimension. Thus, for example, when evaluating a measure calculated from the ranksort procedure that has a base intersection of sku/week, where the <dimspecs> reference the dimensions class and season, in a workbook with 4 classes and 2 seasons, there will be eight sets of ranks, one per class/season, and the value for each sku/week intersection will be the order of that sku/week within its class/season.
The ranking process sorts the intersections in ascending or descending value of <input>, as required, and the ranking number is the order that each position is after sorting. The intersection with the highest value of <input> (lowest when ranking ascending) will have a rank of 1, with subsequent intersections having a rank higher by one. Where two or more intersections have the same value of <input>, they will be given the same rank, but the next rank value will account for the number of intersections with identical rankings. For example, the first few rankings might be 1, 2, 3, 3, 5, 6, …
Note:
ranksort is a procedure and thus cannot be combined with functions, modifiers, or other procedures in any manner. As a procedure, it requires a different syntax: “<-“ instead of “=" when being assigned. The level modifier cannot be used on the LHS of an expression that uses the ranksort procedure. That is, the level at which the ranking is executed will always be determined by the base intersection of <output>. The ranksort procedure must, by its nature, calculate a rank value for every intersection within a scope, not just those that have changed values for measures on the right-hand side of the expression. In incremental calculation mode (for example, when planning online) this may cause longer than expected calculation times, especially when the measure calculated through the ranksort procedure is used on the right-hand side of other expressions, as those expressions, plus any knock-on effects will also have to be calculated for every intersection within the scope.
Examples
-
Rank <- ranksort(WpSlsR, descending)
If Rank has a base intersection of sku, the result of this procedure is the integer value representing where each SKU's Sales value ranks amongst all SKUs. The SKU with the highest WpSlsR value will have a rank of 1.
-
Rank <- ranksort(WpSlsU, descending, [prod].[clss])
If Rank has a base intersection of sku, the result of this procedure is the integer value representing where each SKU's Sales units ranks amongst all SKUs within its class. The SKU with the highest WpSlsU value in each class will have a rank of 1, and there will be several SKUs with a rank of 1, one per class.
-
Rank <- ranksort(WpSlsR, descending, [prod].[clss])
If Rank has a base intersection of sku/week, the result of this procedure is the integer value representing where each SKU/Week's Sales value ranks amongst all SKU/weeks within its class for the entire time horizon. The SKU/week with the highest WpSlsR value in each class will have a rank of 1, and there will be several SKU/weeks with a rank of 1, one per class.
-
Rank <- ranksort(WpSlsR, descending, [prod].[clss], [clnd].[seas])
If Rank has a base intersection of sku/week, the result of this procedure is the integer value representing where each SKU/Week's Sales value ranks amongst all SKU/weeks within its class/season. The SKU/week with the highest WpSlsR value in each class/season will have a rank of 1, and there will be several SKU/weeks with a rank of 1, one per class/season.
positionLocked
Position locking allows a user to lock one or more positions at any level of a hierarchy in a workbook. Once locked, the values of cells corresponding to locked positions cannot change as a result of incremental evaluation, that is, calculations resulting from user edits in the workbook. However, those values can change as a result of a full evaluation resulting from either a full transition to the Calc rule after a refresh, a custom menu execution, or from the execution of an expression that cannot be evaluated incrementally; for example, lhsmeasure = 25. None of the RPASCE procedures, such as lookup or flookup, honor position locking.
The positionLocked function has been provided to help solution designers honor position locking during full evaluation. However, since usage of functions cannot be combined with the evaluation of special expressions (procedures), this provision does not help designers in honoring position locking when special expressions (procedures) are used. Position locking is not supported for special expressions. Position locking is also not supported or honored in scripts, whether they appear in batch or as part of a custom menu.
The positionLocked function is evaluated at the level at which calculation is being performed. It returns a FALSE if none of the positions for the current cell's dimensions are locked and returns TRUE otherwise. Since position locking is only available in a workbook and can only be used after a workbook has been built, the function always returns a FALSE when evaluated in a PDS, used in the load rule group, or used in a workbook. When used in a PDS, the function will log a warning in the RPASCE logs but will not fail evaluation. The function will work as expected when used in refresh, calc and commit rule groups. It will also work as expected in custom menu rule groups that operate on the workbook.
The positionLocked function does not provide for hierarchical protection processing. Refer to the following examples for a better understanding of this behavior.
Syntax
positionLocked()
The function does not take any arguments and returns a Boolean value. The function can be used by itself on the RHS.
Inverse
The function does not have an inverse.
Examples
-
Output = positionLocked()
Populates the Output measure with values that tell whether a cell is locked as a result of position locking along any of the dimensions in the base intersection of the measure.
-
Output = !positionLocked()
Populates the Output measure with values that tell whether a cell is not locked as a result of position locking along any of the dimensions in the base intersection of the measure.
-
Output.level([PROD].[clss]) = positionLocked()
Populates the Output measure (default spread type: repl) with values that tell whether a cell is locked as a result of position locking along any of the dimensions, except those belonging to the PROD hierarchy, in the base intersection of the measure. For the PROD hierarchy, the check is done at the clss dimension and the results would be spread down to the base intersection of the Output measure. Therefore, at the base intersection level, the cell value will be True if all child positions of the cell's clss are position locked, and False if any of them are unlocked irrespective of whether the position itself is locked or not; that is, the positionLocked function does not provide for hierarchical protection processing.
-
Price = if (positionLocked(), ignore, Price.master)
When used in a load rule group, this expression behaves the same as “Price = Price.master" because positionLocked() always returns FALSE. When used in a refresh rule group, the LHS is not updated for positions that are locked.
-
Price.level([PROD].[clss]) = if (positionLocked(), ignore, Price.master)
When used in a load rule group, this expression behaves the same as Price.level([PROD].[clss]) = Price.master because positionLocked() always returns FALSE. When used in a refresh rule group, the LHS is not updated for clss level positions that are locked, that is, all their children are locked. However, if any of the children is unlocked, and hence the clss level position is unlocked, the result of the spread after the expression evaluation will alter the child position's value, even if the child position was locked, that is, positionLocked function does not provide for hierarchical protection processing.
randMask
Used to create a randomly populated mask measure. In contrast to rand, the return type is always Boolean. In contrast to rand, it is a procedure rather than a function.
Syntax
boolMeas <- randMask(density:<density>, seed:<seed>)
Labels are required with all parameters since randMask can be called without any input parameters. A description of each of the optional parameters is provided later:
-
Density is the percentage of cells in the LHS measure that need to be filled with randomly determined true or false values. The cells that are set with random values depend on the iterator order but randMask will try to space out the values evenly, so they are not concentrated in any particular area in the dimspace. Density is an optional parameter and can be either a real or integer constant or scalar measure. Default value of density is 5, corresponding to 5% of the total cells being set.
-
Seed is an optional input into the random generation algorithm. Seed can be either an int or a real number. The same seed will produce the same set of random values. Note that this is the behavior of random number generator algorithms in general and not specific to RPAS CE. The seed argument may be more applicable in the testing/verification process where the same test random data can be generated multiple times using the same seed. When using the seed argument, the value needs to be preceded by the seed: label. The use cases have an example of proper usage.
-
Because both arguments are either literals or scalar measures, incremental mode evaluation of randMask is the same as full mode
Examples
-
boolMeas <- randMask()
Set a LHS measure of type Boolean with random Boolean values. Since density is not provided, a 5% (default density) of the LHS measures cells will be set with random values.
-
boolMeas <- randMask() (density:12.2, seed:1729)
Set approximately 12.2% of the cells in the LHS measure to random Boolean values and use 1729 as the seeded to the random generator algorithm.
loadagg
The loadagg procedure allows the loading of PDS measure data to a workbook using aggregation according to the roll-up information present within the workbook in which the loadagg procedure is run. It may be used within both load and refresh rule groups. Measure data aggregated to the result dimension of a dynamic hierarchy using a load or refresh rule that does not use the loadadd procedure is aggregated according to the parent-child relationships defined within the PDS.
Use of the loadagg procedure has the following constraints:
-
The LHS measure must be a workbook measure.
The LHS measure must be based at an intersection containing a dimension modified by a dynamic hierarchy in the workbook.
-
The RHS measure must be a PDS measure.
Loadagg may only be used in load and refresh rule groups.
Syntax
<measure1> <- loadagg(<measure2.master>)
Example
ClusterValues <- loadagg(StoreValues.master)
In theexample, ClusterValues is a measure defined on the cluster dimension, StoreValues is a measure defined on the store dimension, and the aggregation of stores to clusters is modified by a dynamic hierarchy in the workbook.
The values present in the measure StoreValues for those stores that roll-up to any given position in a cluster according to the dynamic hierarchy are aggregated according to the aggregation type of ClusterValues to determine the value assigned to ClusterValue for that cluster.
Were the loadagg procedure not used and the expression:
ClusterValues = StoreValues.master
were used instead, then the values in the measure StoreValues for those stores that roll-up to any given cluster in the PDS (as opposed to the workbook) would be aggregated by the ClusterValues aggregation method to be the value of ClusterValues for that cluster.
spreadcommit
The spreadcommit procedure allows the committing of workbook measure data to the PDS using spreading according to the roll-up information present within the workbook in which the spreadcommit procedure is run. It may be used only in commit rule groups and custom menu rule groups that perform commit operations. Measure data spread from the result dimension of a dynamic hierarchy using a commit rule that does not use the spreadcommit procedure is spread according to the parent-child relationships defined within the PDS.
Use of the spreadcommit procedure has the following constraints:
-
The RHS measure must be an PDS measure.
-
The LHS measure must be a workbook measure.
-
The LHS measure must be based at an intersection containing a dimension modified by a dynamic hierarchy in the workbook.
-
spreadcommit can only be used in the commit rule group and in the custom menu rule groups that perform a commit operation.
-
By default, spread operations that rely on data already present in the destination (for example, proportional spread) use the data present in the PDS. An optional argument <seed_measure> may be used to specify an alternate measure to use for this purpose.
Syntax
Labelled notation is also supported. If labels are not provided, then positional notation is supported.
<measure1.master> <- spreadcommit(<measure2>{,<seed_measure>,<mode_measure>,<maskMeasure>}) <measure1.master> <- spreadcommit(SOURCE:<measure2>{,TARGET:<seed_measure>,MODE:<mode_measure>,COMMITMASK:<maskMeasure>})
If COMMITMASK is passed in, then commit is performed only if mask is true. This must be Calendar dimension and must not be part of the alternate hierarchy.
Example
StoreValues.master <- spreadcommit(ClusterValues)
In the previous example, ClusterValues is a measure defined on the cluster dimension, StoreValues is a measure defined on the store dimension, and the aggregation of stores to clusters is modified by a dynamic hierarchy in the workbook.
The values present in the measure ClusterValues for any given cluster are spread to the cells of StoreValues whose store positions roll-up to that cluster according to the dynamic hierarchy defined in the workbook.
Were the spreadcommit procedure not used and the expression:
StoreValues.master = ClusterValues
were used instead, then the values in the measure StoreValues for those stores that roll-up to any given cluster in the PDS (as opposed to the workbook) would receive the spread values of ClusterValues for that cluster.
StoreValues.master <- spreadcommit(ClusterValues, Clst2StrSeed)
In the second example, values of CusterValues are being spread to StoreValues in a manner similar to the first example. However, in this example, a seed measure Clst2StrSeed is providing the initial data as opposed to the PDS data in StoreValues in the first example. In cases where ClusterValues uses a spread method dependent on data present in the destination (such as with the proportional spread method), the starting data is provided by Clst2StrSeed and not by StoreValues.
dynHierRefresh
The dynHierRefresh function can be used to trigger a refresh of the parent-child relationships in the dynamic hierarchies of a workbook. When called, dynHierRefresh reassigns the roll-ups of a workbook based upon the data present in the mapping measures driving those dynamic hierarchies. In cases where that mapping information has changed since the workbook was build, use of dynHierRefresh results in the new information being applied to the workbook's hierarchies.
Notes on the use of dynHierRefresh:
-
May only be used in custom menu rule groups.
-
Returns a string value of Success if the refresh could be performed; otherwise, it returns a value of Failure.
-
Cannot be used to refresh dimensions upon which dimension attributes are defined. Attempts to do so results in a value of Failure.
Syntax
<result_measure> = dynHierRefresh([<DynDimName1>,...<DynDimNameN>])
Example
RefreshFlag = dynHierRefresh()
RefreshFlag = dynHierRefresh("dm1", "dm2")
where RefreshFlag is a scalar String measure that contains either the string Success or the string Failure to indicate the success or failure of the refresh operation.
The dynHierRefresh function takes a list of dynamic dimension names as its input. The input list is optional. If no input is provided, it will refresh all dynamic dimensions defined in the workbook. If input is provided, only the dynamic dimensions specified will be refreshed.
preModified
The preModified function returns a value of true if the current cell has been modified at the beginning of the current expression's evaluation step.
The preModified function only works for workbook's incremental evaluation mode. The function takes a single input that must be a valid measure name that must exist in the current workbook. It returns a value of true for all cells of the rhs measure that have been modified when current expression is first evaluated.
If used in Full Mode evaluation, preModified will return a value of false for all cells.
Syntax
preModified(<measure>)
where <measure> is a valid measure name; no modifier, nor any other calculations are allowed.
Inverse
The preModified function does not have an inverse.
Example
preModified(A) returns a value of true at cells A has been calculated in the current workbook's incremental evaluation step.E = if (preModified(A), A+B, C+D)preModified is used to calculate lhs E using different logic, based on whether the measure A is modified or not. Assume all A, B, C, D are at sku/str/week level and filled with value 1, E initially has Value 2. If the user modified A for a sku/str/week combination to 100, and this rule is triggered. Because preModified(A) returns true, E will be evaluated to A+B, which is 101. If the user modified measure C at the same sku/str/week to 10 and this rule is triggered. Because preModified(A) is false, E will be evaluated to C+D, which is 11.
AggPEClc
The AggPEClc procedure computes the inner expression using the specified preserve Calendar level, then performs the final Calendar aggregation in the PET (Period Ending Total) method. The procedure is designed to wrap a RECLC expression within the CALC rulegroup within a workbook template. The LHS measure must have aggregation of RECLC, and the inner expression is expected to be a RECLC expression.
Syntax
<result_measure> = AggPEClc(<A RECLC expression>, <preserve calendar level name>)
Example
Lhs_dstrsclsmnth = aggpeclc(A_storskupweek + B_storskupday, "week")
The second parameter of AggPEClc indicate the computation of the inner expression must be maintained at calendar level week. When Lhs_dstrsclsmnth measure has aggregation method set as RECLC, then for each intersection that is viewable and is higher or equals to dstr_scls_mnth on UI Client grid, the AggPEClc function will first aggregate the RHS measures to LHS NonClndLevels+WEEK using their respective aggregation methods, will compute the expression, and finally, will set the all periods of LHS calendar level with values from last week values within the period. For example, if the UI view is displaying at rgn_clss_qrtr level, it computes the inner expression at rgn_clss _week level, aggregating measures to rgn_clss_week if needed, then PET aggregate to rgn_clss_qrtr.
Expr A = AggPEClc( B + C, "week")
A base intx = dstr+scls+mnth with RECLC aggregation
B base intx = stor+skup+week with total aggregation
C base intx = stor+skup_week with average aggregation.
And
B C
STR_X1, SKU_A1, WEEK_30 10 20
STR_X2, SKU_A1, WEEK_30 20 30
STR_X1, SKU_A1, WEEK_31 20 30
STR_X2, SKU_A1, WEEK_31 30 40
Agg to
DSTR_X, SCLS_A, WEEK_30 30 25 (B+C = 55)
DSTR_X, SCLS_A, WEEK_31 50 35 (B+C = 85)
FINAL PET To bring WEEK TO MNTH
A @ DSTR_X, SCLS_A, MNTH_5 will be set to last week (WEEK_31) of the sum, which is WEEK_31 and the value is 85. To compute the initial view at A base intx dstr+scls+mnth, the RHS will aggregate B and C to dstr+scls+week using their respective agg method, total for B and average for C. Then the inner expression will be evaluated. Resulting the sum of total of B and average of C @ dstr+sclr+week level. Finally, the respective mnth of the LHS is set with the last week of that mnth from the RHS. When the UI GRID is change to different level, for example, rgn+dept+year. the same process is used to computer the LHS values: Bring the RHS measures to rgn+dept+week using their respective agg method, evaluate the inner expression, then finally set the calendar period using the last week of the year.
intradayexport
The intradayexport procedure submits one or multiple EEBATCH export measure task to the task queue to perform measure export without going through the Configured Batch Tasks in Online Admin Tools. This procedure is expected to be only used by custom menu action. It offers a way for non-admin users to trigger measure export. The export operation does not lock the PDS normal batch tasks. Export operations created by this procedure are submitted to the task queue only and the JTD will determine the time of the actual export should occur.
Syntax
<result_measure> = intradayexport(<ExportTaskName1>[,...< ExportTaskName2>])
Example
ExportFlag = intradayexport("export_mg1", "export_mg2")
where ExportFlag is a scalar string measure that contains either the string Success or the string Failure to indicate the reason of failure. The export task group should use the |T| directive and without the |O| directive to prevent name collision. For detail explanation of these directives, please refer to Oracle Retail Predictive Application Service Cloud Service Implementation Guide, Release 19.0.
rmsNewItemExpr
Special Expression rmsNewItemExpr directly calls RMS Micro Service to enable new items. When called, the special expression will iterate all the new items that have the item mask set to true, collect all the associated attributes for each new item, and put all the new item and attributes into a micro service request. The service request is then sent to RMS to be processed.
Syntax
strscalar1←rmsNewItemExpr(mask:itemMask,[item:itemIdMeas, AttrName1:AttrVal1, AttrName2:AttrVal2, …])
To produce the RMS new item request, the special expression will produce the json request based on the list of arguments, so if an argument is not supplied as input, the request json will not have the entry for it. If a new json entry is needed for the request, a new labeled argument can be added to the input and the argument will be added to the request json object automatically. The special expression will use the label of the argument as the key to the json request and the value as the data for that key.
Example
msg:scalarString, itemmsg:itemStringMeas, status:scalarBoolMeas, retcode:scalarIntMeas←rmsNewItemExpr(mask:itemMask,item:itemIdMeas,itemParent:itemParentIdMeas,itemLevel:itemLevelMeas,diff1:diffMeas,dept:deptMeas,class:1,classMeas,itemDescription:itemDescMeas,itemSuppliers_supplier:splrMeas,itemAggregateInd:itemAggMeas,diff1AggregateInd:diff1IndMeas,brand:brandMeas)
The RHS arguments of the expression must use labeled input. Except for the ‘mask’ argument, all other arguments are optional.
For the RHS measure, the mask measure must be a one-dimensional Boolean measure and the base intx of the measure must be the dimension for the RMS item. For each position on this dimension, if the mask is true, the special expression will create the json object for this item and ask RMS to create new item for it.
The top level of the request will be a json object named as “items”, within the “items”, there will be a list of json objects, each populated with key/value pairs extracted from the list of input arguments, based on the requirement in the confluence page.
Note that each position can be created only once in RMS, so if one position is created a second time, the RMS micro service will report an error.
The “item” argument provides the item ID to be passed to RMS; if omitted, the position ID for the current item will be used.
For other arguments on the RHS, the input can be either a measure or a constant value for default. If it is a measure, it can be either a one-dimensional measure at the same intersection of the mask or a two-dimensional measure that includes the item dimension plus an extra dimension.
Each labelled input argument, for example arg1, can have a mask input associated with it labeled as arg1mask. The mask must be at the same intx of the arg1's input. It can also have specific labelled measure input, for example, arg1_attr1, arg1_attr2, and so on. The attribute name and the 'arg1' must be separated by '_'.
If the input is a one-dimensional measure, and if it has an associated mask measure, the mask will determine whether the attribute for the current item will be set in the request. If the mask is not present, the input attribute will be set.
If the argument arg1 has no associated attribute such asarg1_attr1 and so on, the following entry for "arg1" will be added to the request json:
"items": [ {
"item": "1000",
"arg1": "arg1value",
...
If the argument arg1 does have associated attributes such as arg1_attr1 and arg1_attr2, then the json entry for arg1 will be:
"arg1": [
{
"attr1": "attr1value" ,
"attr2": "attr2value"
}
]
The arg1 entry will have a collection with just one object per requirement, and each attribute will be an entry in the object.
If the input is a two-dimensional measure, the argument label must be in the form of argName_attrName: the attribute name is required and separated by the "_". It can also have the companion mask, such as argNamemask, and the mask measure must be at the same intersection as the other input measures of the same argName.
Since the input is two-dimensional, the arg will be a collection; each positions of the extra dimension, if the mask is present and is true, will be an element in the collection. Within the element, each attribute will be a data member. In the following example, the expressionis configured with:
... v2dmask:skustrb, v2d_attr1:skustrval1, v2d_attr2:skustrval2
Assuming the extra dimension is str and the v2dmask is true for all stores, and there are two stores in the workbook, the following entry will be created:
"v2d" : [
{ "attr1":"val11",
"attr2"::val12
},
{ "attr1":"val21",
"attr2":"val22"
}
]
Note that the "attr1" and "attr2" are the keys inside the element for each store. That is the reason the attribute name must be specified for two—dimensional measures.
Also, assume the first entry in the collection is for store 1 and the second entry is for store 2: If the v2dmask measure has 'false' for store 2, then the second entry will be removed from the request.
The LHS has four labeled output measures; all are optional but at least one must be specified. The msg specifies the scalar string output that stores the returned status/message from the microservice call.
The item msg specifies the item level string measure that stores the validation error for each item, if there is validation error.
The retcode stores the microservice return code in a scalar integer measure. The status stores the information indicating whether the microservice call is success or not in a scalar boolean measure.