RTimeSeries()

This article applies to P2 Server version 4.5.4 and later, and P2 Sentinel 4.1.3 and later.

Format

RTimeSeries (Script [,Timestamp Pattern] [,Parameters])

Returns

Allows users to pass an R script into the calculation, and returns values as time series data.

Inputs

Script: The R Input Symbols in a script that uses the R Language syntax. This is case sensitive. Typically, this will use the output$value parameter (see below for more information).
Behaviour: Required
Dimensions: SingleValue, MultiCollection
Valid data types: String

Timestamp Pattern: The formatting string used to pass the timestamps of the data points as text e.g. dd/M/yyyy H:mm:s
Behaviour: Optional [0..1]
Dimensions: SingleValue
Valid data types: Null, String

Parameters: The parameters to use as inputs for the Script. These parameters are case sensitive and are passed as data frames. For more information, see Parameters below.
Behaviour: Optional [0..n]
Dimensions: Expression
Valid data types: Expression

How to format data types

Parameters

The input parameters are passed as data frames with the following columns:

• timestamp: If a timestamp pattern is specified for RTimeSeries() (using the 2^nd parameter) then this will be a string type, otherwise it will be a numeric type (expressed in seconds since Unix epoch).
• value: The value of this column depends on the type of parameter passed into the script. It can be a numeric, integer, or string data type.
• confidence: This is an integer data type.

There are also some additional input parameters:

• The expression of the parameter is passed to the R script as a simple string with the name "parameterNName" where N is the index of the parameter.
  E.g. If you call RTimeSeries("[R script]", null, 1 + 2, {Silver}, {Well 1:THP}) then, in your script:
  • parameter1Name will be a string which contains "1 + 2"
  • parameter2Name will be a string which contains "{Silver}"
  • parameter3Name contains "{Well 1:THP}"
• If the above-mentioned expression is an entity-attribute fetch then an additional string variable called "parameterNEntity" will be created, where N is the index of the parameter.
  E.g. If you call RTimeSeries("[R script]", null, 1 + 2, {Silver}, {Well 1:THP}) then:
  • parameter1Entity and parameter2Entity will not exist
  • parameter3Entity will exist and will contain "Well 1"

output$value

The output parameter output$value is a data frame with the following columns:

• timestamp: This is pre-populated with timestamps based on the timestamp pattern parameter (string vs numeric), and a timestamp will be created for every sample interval within the start and end time of the fetch (this applies to raw requests as well).
• value: This is left empty and the R script is expected to fill it in.
• confidence: This is set to 100 in every row.

The output parameter will have as many rows as the sample intervals are expected to have. This makes writing R scripts easier since you only have to concentrate on the value column. However, the RTimeSeries() function is quite flexible in what you can do with this output parameter. The important thing to know is that the function will expect the result in the output variable. This variable can be either a:

• Data frame, in which case:
  • A column called "value" must exist and it must be an integer, numeric, or string data type.
  • If a column called "timestamp" also exists (this is optional), then its type must be string or numeric (based on the timestamp pattern parameter).
  • If a column called "confidence" also exists (this is optional), then its type must be integer.
• Vector:
  • Character vectors will be turned into string collections.
  • Integer vectors will be turned into integer collections.
  • Numeric vectors will be turned into decimal collections.

Useful to Know

This function requires a P2 Server licence with R capabilities. The R Adaptor must also be configured before this function can be used.

Examples

Examples with No Timestamp Returned

The following examples demonstrate how the RTimesSeries() function works, but cannot be used in Explorer trends or pages as tags, as there are no timestamps returned.

You can paste these examples into the calculation editor and test to see what the results are, in the editor.

Expression: RTimeSeries('output <- 5')
Output: This will assign a single number to output which will be handled as a single-value vector. The function will return a collection with 1 value which won't have a timestamp and its confidence will be the default 100.

Expression: RTimeSeries('output <- c(5,6,7)')
Output: This will assign a numeric vector and not a data frame to the output parameter. The function will translate this as a decimal collection where the values won't have a timestamp and their confidence will be the default 100.

Expression: RTimeSeries('output <- data.frame (value = c(5,6,7))')
Output: This script creates a brand new data frame which contains only 1 column (value) and 3 rows. If you test it in the calculation editor, then it will return a decimal collection with 3 values (5, 6, and 7) and none of them will have timestamp. They will have the default confidence value of 100.

Expression: RTimeSeries('output <- data.frame(value = c(5, 6, 7), confidence = as.integer(c(90, 95, 100)))')
Output: This is very similar to the previous example except that it also defines a confidence column, so the returned values will show 90, 95, and 100 confidence. However they still will not have timestamps.

Examples with Timestamps Returned

The following examples can be used as tags in Explorer, as timestamps are returned.

Expression: RTimeSeries('output$value <- 5')
Output: This is the most basic example. The script uses the existing output parameter and only fills in its value column. If you test this in the calculation editor with default settings, then it will return a collection with 13 values, with both the timestamp and confidence filled in.

Expression: RTimeSeries('output <- data.frame(timestamp = c(10, 20, 30), value = c(5, 6, 7), confidence = as.integer(c(90, 95, 100)), lastcolumn = c("one", "two", "three"))')
Output: This example creates a data frame with 4 columns. The last column will be ignored as the function cannot handle it. The other 3 columns will be processed, and the function will return a decimal collection with 3 values (5, 6, and 7), with confidences (90, 95, and 100), and with timestamps (10, 20, and 30 seconds after Unix epoch).

Expression: RTimeSeries('output$value <- parameter1', null, 5.6)
Output: Returns 5.6 as the value for each timestamp.

Expression: RTimeSeries('output$value <- parameter1Name', null, 2.2 + 3.4)
Output: Returns the string 2.2 + 3.4 as the value for each timestamp.

Expression: RTimeSeries('output$value <- parameter2Name', null, 2.2 + 3.4, {Silver})
Output: Returns the string {Silver} as the value for each timestamp.

The following examples return the "parameterNEntity" string variable:

Expression: RTimeSeries('output$value <- parameter1Entity', null, {Beardy:Choke})
Output: Returns the string value of 'Beardy' for each timestamp.

Expression: RTimeSeries('output$value <- parameter1Entity', null, {Beardy:Choke!Max position})
Output: Returns the string value of 'Beardy' for each timestamp.

Expression: RTimeSeries('output$value <- parameter1Entity', null, {Beardy[Oil Producing Well]:Choke})
Output: Returns the string value of 'Beardy' for each timestamp.

Expression: RTimeSeries('output$value <- parameter1Entity', null, {Beardy[Oil Producing Well]:Choke!Max position})
Output: Returns the string value of 'Beardy' for each timestamp.

Using the ParameterN$value within the R Script

The following examples use the value parameters within the R script, returning a decimal value for each timestamp:

Expression: RTimeSeries('output$value <- parameter1$value', null, {z.gold})
Output: Returns the value of {z.gold} for each timestamp.

Expression: RTimeSeries('output$value <- parameter1$value + parameter2$value', null, {z.gold}, {silver})
Output: Returns the sum of {z.gold} and {silver} for each timestamp.

Expression: RTimeSeries('output$value <- cor(parameter1$value, parameter2$value)', null, {z.gold}, {silver})
Output: Returns the correlation between {z.gold} and {silver} values for the period (this is the same value for each timestamp).

Expression: RTimeSeries('output$value <- rank(parameter1$value)', null, DDGetAttributes("Archer","[Oil Producing Well]:Choke"))
Output: Returns the rank for each of entity Archer's Choke values for the period.

Expression: RTimeSeries('output$value <- smooth.spline(parameter1$timestamp, parameter1$value)$y', null, {silver})
Output: Fits a cubic smoothing spline on the values fetched by the Silver tag.

Release History

• RTimeSeries() 4.6.5
  • Changed Script parameter to support MultiCollection values.
• RTimeSeries() 4.5.4
  • Initial version