Home Server Calculations PythonTimeSeries()

PythonTimeSeries()

This article applies to IFS OI Explorer version 4.17 and later.

Format

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

Returns

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

Inputs

Script: The Python script to execute. This is case sensitive. 
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

Related: 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 PythonTimeSeries () (using the 2nd 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 Python script as a simple string with the name "parameterNName" where N is the index of the parameter.
    E.g. If you call PythonTimeSeries ("[Python 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 PythonTimeSeries ("[Python 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 Python 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, and 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:

  • IFS OI Server licence with R capabilities.
  • Python v3.7-v3.11 installed on the Explorer server machine.
  • We strongly recommend installing the pandas module, for full access to Python’s data analysis features.
  • Additional settings for configuring the Python Adaptor can be found in the "Python Adaptor" group in the ServerConfig.xml file.

Examples

The following examples demonstrate how the PythonTimesSeries() 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: PythonTimeSeries("output['value'] = parameter1", null, 5.6)
Output: Returns 5.6 as the value for each timestamp.

Expression: PythonTimeSeries("output['value'] = parameter1Name", null, 2.2 + 3.4)
Output: Returns the string 2.2 + 3.4 as the value for each timestamp.

Expression: PythonTimeSeries("output['value'] = scipy.interpolate.splev(1,scipy.interpolate.splrep(parameter1['timestamp'], parameter1['value']))", null, {0072895.PV})
Output: Fits a cubic smoothing spline on the values fetched by the 0072895.PV tag.

Release History

  • PythonTimeSeries() 4.17.0
    • Initial version

Comments are closed