Python Expression Tag Examples

This section provides examples for using Python® Expression Tags.

Using No Python Modules or Functions

In this example, we want to perform gross error detection on a signal "Signal" and clip the values to a range between 0 and 600.

Expression

To solve this, we create the following Python expression. 

                    0 if Signal.value<0 else (600 if Signal.value>600 else Signal.value)
Python Datatype Name Description
Expression Inputs SingleFloat Signal Represents the signal value.
Expression Result SingleFloat Not Applicable Represents the resulting expression value, with extreme outliers clipped.

Python Modules to Import for this Expression: None. (Only modules contained on the list of supported modules are available for this expression.)

Constructing the JSON:

Using the created expression, we construct the following JSON. For more information, refer to Constructing the JSON Configuration.
"script":"0 if Signal.value<0 else (600 if Signal.value>600 else Signal.value)", "parameters":[
                    {
                    "name":" Signal",
                    "source":{"address":"Simulation00001", "dataType":"SingleFloat"}
                    }
                    ]
                    }

Note that the address parameter is stipulated in the context of the chosen collector, which must be on the list of collectors supporting Python Expression Tags.

In this example, we have used the Simulation Collector. Your collector might use a different source address.

We then transform the above into a minified JSON string:
{"script":"0 if Signal.value < 0 else (600 if Signal.value > 600 else Signal.value)","parameters":
                    [{"name":"Signal","source":{"address":"Simulation00001",dataType":"SingleFloat"}}]}

Adding the Expression Tag to Historian

For this example, we choose to add a Python Expression tag to the Historian using the File collector to import a CSV file. (We could also have added the tag via the Historian Excel Add-In.)

The file contents look like this:
[Tag]
                    Tagname,CollectorName,CalcType,SourceAddress,DataType,DescriptionGEDSignalTag,SimulationCollector,PythonExpr,
                    "{""script"":""0 if Signal.value < 0 else (600 if Signal.value > 600 else Signal.value)"",""parameters"":
                    [{""name"":""Signal"",""source"":{""address"":""Simulation00001"",""dataType"":""SingleFloat""}}]}",
                    SingleFloat,Python Expression Tag example
Note the following:
  • The CalcType header is included and set to PythonExpr.
  • The Source Address is set to the minified JSON created in the previous step.
  • The CollectorName is set to SimulationCollector, which is a Simulation Collector. Your collector might be called by a different name.
  • The quotation marks within the JSON string are escaped with other quotation marks.

We then import the file, following the instructions specified in File collector.

Using a Bulit-In Python Function

In this example, we want to calculate the maximum of two temperature values to be collected.

Expression

To solve this, we create the following Python expression:
max(ThermocoupleA.value, ThermocoupleB.value)
Python Datatype Name Description
Expression Inputs SingleFloat ThermocoupleA Represents a temperature value.
SingleFloat ThermocoupleB Represents a temperature value.
Expression Result SingleFloat Not Applicable Represents the maximum of the two given temperature values

Python Modules to Import for this Expression: None. A built-in Python module from the Python Standard Library is used. (Only modules contained on the list of supported modules are available to this expression.)

Constructing the JSON

Using the created expression, we construct the following JSON:
{
 "script":"max(ThermocoupleA.value,ThermocoupleB.value)",
 "parameters":[
  {   
  "name":"ThermocoupleA",
  "source":{"address":"Simulation00001","dataType":"SingleFloat"}
  },
  {   
  "name":"ThermocoupleB",
  "source":{"address":"Simulation00002","dataType":"SingleFloat"}
  }
 ]
}

Note that the address parameter is stipulated in the context of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. In this example, we have used the Simulation Collector. Your collector might use a different source address.

We then transform the above into a minified JSON string:
{"script":"max(ThermocoupleA.value,ThermocoupleB.value)","parameters":[{"name":"ThermocoupleA","source":
{"address":"Simulation00001","dataType":"SingleFloat"}},{"name":"ThermocoupleB","source":
{"address":"Simulation00002","dataType":"SingleFloat"}}]}

Adding the Expression Tag to Historian

For this example, we choose to add a Python Expression tag to the Historian using the Historian Excel Add-In. (We could also have added the tag by using via the File collector to import a CSV file. )

Ensure the following for your Python Expression Tag:
  • The CalcType is set to PythonExpr.

  • The SourceAddress contains the JSON configuration.

  • The CollectorName is set to the name of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. Your collector might be called by a different name.
  • The quotation marks within the JSON string are escaped with other quotation marks in the CSV file.
Otherwise, the tag is added in exactly the same way as for a regular tag.

Using A Python Standard Library Module

In this example we want to calculate a result based on a specific time range for an expression input. We set a supply voltage to zero within prescribed time ranges.

Expression

To solve this, we create the following Python expression:
0 if (SupplyVoltage.timestamp.astimezone().time() &gt;= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() &lt;= datetime.time(20, 30)) else 
SupplyVoltage.value
Python Datatype Name Description
Expression Inputs SingleFloat SupplyVoltage Represents the value we wish to transform.
Expression Result datetime Not Applicable Represents the resulting supply voltage, set to zero in the prescribed time ranges.

Python Modules to Import for this Expression: datetime module. This module is shipped with Historian.

Constructing the JSON

Using the created expression, we construct the following JSON:
{
 "imports":["datetime"],
 "script":"0 if (SupplyVoltage.timestamp.astimezone().time() >= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() <= datetime.time(20, 30)) else 
SupplyVoltage.value","parameters":[
  {   
  "name":" SupplyVoltage",
  "source":{"address":"Simulation00001", "dataType":"SingleFloat"}
  }
 ]
}

Note that the address parameter is stipulated in the context of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. In this example, we have used the Simulation Collector. Your collector might use a different source address.

We then transform the above into a minified JSON string:
{"imports":["datetime"],"script":"0 if (SupplyVoltage.timestamp.astimezone().time() >= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() <= datetime.time(20, 30)) else 
SupplyVoltage.value","parameters":[{"name":"SupplyVoltage","source":
{"address":"Simulation00001","dataType":"SingleFloat"}}]}

Adding the Expression Tag to Historian

For this example, we choose to add a Python Expression tag to the Historian using the Historian Excel Add-In. (We could also have added the tag via the File collector to import a CSV file.)

Ensure the following for your Python Expression Tag:
  • The CalcType is set to PythonExpr.

  • The SourceAddress contains the JSON configuration.

  • The CollectorName is set to the name of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. Your collector might be called by a different name.
Otherwise, the tag is added in exactly the same way as for a regular tag.

Using A Python Standard Library Module

In this example we want to calculate a result based on a specific time range for an expression input. We set a supply voltage to zero within prescribed time ranges.

Expression

To solve this, we create the following Python expression:
0 if (SupplyVoltage.timestamp.astimezone().time() &gt;= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() &lt;= datetime.time(20, 30)) else 
SupplyVoltage.value
Python Datatype Name Description
Expression Inputs SingleFloat SupplyVoltage Represents the value we wish to transform.
Expression Result datetime Not Applicable Represents the resulting supply voltage, set to zero in the prescribed time ranges.

Python Modules to Import for this Expression: datetime module. This module is shipped with Historian.

Constructing the JSON

Using the created expression, we construct the following JSON:
{
 "imports":["datetime"],
 "script":"0 if (SupplyVoltage.timestamp.astimezone().time() >= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() <= datetime.time(20, 30)) else 
SupplyVoltage.value","parameters":[
  {   
  "name":" SupplyVoltage",
  "source":{"address":"Simulation00001", "dataType":"SingleFloat"}
  }
 ]
}

Note that the address parameter is stipulated in the context of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. In this example, we have used the Simulation Collector. Your collector might use a different source address.

We then transform the above into a minified JSON string:
{"imports":["datetime"],"script":"0 if (SupplyVoltage.timestamp.astimezone().time() >= datetime.time(18) and 
SupplyVoltage.timestamp.astimezone().time() <= datetime.time(20, 30)) else 
SupplyVoltage.value","parameters":[{"name":"SupplyVoltage","source":
{"address":"Simulation00001","dataType":"SingleFloat"}}]}

Adding the Expression Tag to Historian

For this example, we choose to add a Python Expression tag to the Historian using the Historian Excel Add-In. (We could also have added the tag via the File collector to import a CSV file.)

Ensure the following for your Python Expression Tag:
  • The CalcType is set to PythonExpr.

  • The SourceAddress contains the JSON configuration.

  • The CollectorName is set to the name of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. Your collector might be called by a different name.
Otherwise, the tag is added in exactly the same way as for a regular tag.

Using A Historian Python Module

In this example we want to convert a temperature value from Fahrenheit to Celsius.

Expression

To solve this, we create the following Python expression:
uom.to_Celsius(Thermocouple.value, uom.Temperature.Fahrenheit)
Python Datatype Name Description
Expression Inputs SingleFloat Thermocouple Represents the temperature value in degrees Fahrenheit
Expression Result SingleFloat Not Applicable Represents the temperature value in degrees Celsius

Python Modules to Import for this Expression: uom module. This Python module is shipped with Historian.

(Only modules contained on the list of supported modules are available to this expression.)

Constructing the JSON

Using the created expression, we construct the following JSON:
{
 "imports":["uom"],
 "script":"uom.to_Celsius(Thermocouple.value, uom.Temperature.Fahrenheit)",
 "parameters":[
  {   
  "name":" Thermocouple",
  "source":{"address":"Simulation00001", "dataType":"SingleFloat"}
  }
 ]
}

Note that the address parameter is stipulated in the context of the chosen collector supporting Python Expression Tags. In this example, we have used the Simulation Collector. Your collector might use a different source address.

We then transform the above into a minified JSON string:
{"imports":["uom"],"script":"uom.to_Celsius(Thermocouple.value,uom.Temperature.Fahrenheit)","parameters":
[{"name":"Thermocouple","source":{"address":"Simulation00001","dataType":"SingleFloat"}}]}

Adding the Expression Tag to Historian

For this example, we choose to add a Python Expression tag to the Historian using the File collector to import a CSV file. (We could also have added the tag via the Historian Excel Add-In.)

The file contents look like this:
[Tag]
Tagname,CollectorName,CalcType,SourceAddress,DataType,DescriptionConvertedTempTag,SimulationCollector,PythonExpr,
"{""imports"":[""uom""],""script"":""uom.to_Celsius(Thermocouple.value,uom.Temperature.Fahrenheit)"",
""parameters"":[{""name"":""Thermocouple"",""source"":{""address"":""Simulation00001"",""dataType"":
""SingleFloat""}}]}",
SingleFloat,Python Expression Tag example
Note the following: The CalcType header is included and set to PythonExpr.
Note the following:
  • The CalcType header is included and is set to PythonExpr.

  • The SourceAddress contains the JSON configuration.

  • The CollectorName is set to the name of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. Your collector might be called by a different name.
  • The quotation marks within the JSON string are escaped with other quotation marks in the CSV file.

    For more information, see File collector > CSV File Formats.

We then import the file, following the instructions in the File collector section.

Using Array/Table Lookup

In this example we want to translate a string representing order of magnitude into a corresponding numerical value using array/table lookup.

This example will be explained by means of a hypothetical collector called PlantSensorCollector that is a Python Expression enabled collector. The collector collects a source tag with address TemperatureSetpoint of type VariableString, having values 'Low', 'Medium', and 'High'.

Expression

To solve this, we create the following Python expression:
{'Low':100, 'Medium':400, 'High':800}.get(Setpoint.value, 0)
Python Datatype Name Description
Expression Inputs VariableString Setpoint Represents the given ordinal string value we wish to transform.
Expression Result SingleFloat Not Applicable Represents the numerical value corresponding to the ordinal string input.

Python Modules to Import for this Expression: None. (Only modules contained on the list of supported modules are available to this expression.)

Constructing the JSON: Using the created expression, we construct the following JSON:
{
                 "script":"{'Low':100,'Medium':400,'High':800}.get(Setpoint.value, 0)",
                 "parameters":[
                  {   
                  "name":" Setpoint",
                  "source":{"address":"TemperatureSetpoint", "dataType":"VariableString"}
                  }
                 ]
                }
We then transform the above into a minified JSON string:
{"script":"{'Low':100,'Medium':400,'High':800}.get(Setpoint.value,0)","parameters":
                [{"name":"Setpoint","source":{"address":"TemperatureSetpoint","dataType":"VariableString"}}]}

Adding the Expression Tag to Historian: For this example, we choose to add a Python Expression tag to the Historian using the File collector to import a CSV file. (We could also have added the tag via the Historian Excel Add-In.)

The file contents look like this:
[Tag]Tagname,CollectorName,CalcType,SourceAddress,DataType,DescriptionNumericalTagDerivedFromOrdinalVal,PlantSensorCollector,PythonExpr,
                "{""script"":""{'Low':100,'Medium':400,'High':800}.get(Setpoint.value,0)"",""parameters"":
                [{""name"":""Setpoint"",""source"":{""address"":""TemperatureSetpoint"",""dataType"":""VariableString""}}]}",
                VariableString, Python Expression Tag example
Note the following:
  • The CalcType is set to PythonExpr.

  • The SourceAddress contains the JSON configuration.

  • The CollectorName is set to the name of the chosen collector, which must be on the list of collectors supporting Python Expression Tags. Your collector might be called by a different name.
  • The quotation marks within the JSON string are escaped with other quotation marks in the CSV file.

    For more information, see File collector > CSV File Formats.

We then import the file, following the instructions specified in File collector.