Calculated Data function

• If you select the Data item option, the Calculated Data function returns one or more evenly-spaced, calculated values based on PI point or PI AF attribute values and specified calculation preferences. If you specify no filter expression and no time interval, the function supports bulk calls.

• If you select the Expression option, the Calculated Data function returns one or more evenly-spaced, calculated values based on an evaluated performance equation and specified calculation preferences.

  Note: Select + next to Advanced to access all function inputs.

  Input	Description
  Root path	The common path to specified data items, including those in expressions. Valid entries include: PI Data Archive server name if the data item is a PI point. PI AF server and database if the data item is a PI AF attribute. Blank if the data item is a PI point on the default PI Data Archive server. See Data items.
  Data item(s)	One or more PI point names or PI AF attribute names, for which the function returns values. To specify multiple data items, enter a range of cells that contain PI point names or PI AF attribute names. The function returns values for each. Required if you select the Data item option.
  Expression(s)	One or more performance equations that the function computes a value for. See Expressions. To specify multiple expressions, enter a range of cells that contain complete expressions. The function returns values for each. Required if you select the Expression option.
  Start time	The start of the time period for which the function returns values. See Time inputs. Required.
  End time	The end of the time period for which the function returns values. See Time inputs. Required.
  Time interval	The frequency that the function returns calculated values during the time period. Enter a value and time unit. For example, enter 15m (15 minutes) to return a value for every 15-minute interval in the time period. See Learn about time-interval specifications.
  Filter expression	A Boolean performance equation that the function uses to filter values. When the expression evaluates to false, the function excludes corresponding values. See Filter expressions.
  Conversion factor	A factor that the function applies to returned values. Enter 1 if a conversion factor is not needed. For time-weighted total calculations, specify a factor that converts recorded rate values to the server default time unit (units per day). Required. For example, common conversion factors include: 1.0 for values that store units/day 24 for values that store units/hour 1440 for values that store units/minute 86400 for values that store units/second
  Calculation mode	The type of calculation that the function performs: total Sums values during the interval. minimum Finds the minimum value during the interval. maximum Finds the maximum value during the interval. standard deviation Computes the standard deviation of values during the interval. range Computes the maximum value minus the minimum value during the interval. count Counts the number of seconds in the interval if the Calculation basis field is set to time-weighted. Counts the number of values stored during the interval if the Calculation basis field is set to event-weighted. average (time-weighted) Computes the time-weighted average of the recorded values during the interval. average (event-weighted) Computes the event-weighted average of the recorded values during the interval.
  Calculation basis	The calculation method: time-weighted Default for all calculation modes except for event-weighted average. The function weights each recorded value by the length of time that the value applies. The function interpolates values at the interval boundaries. event-weighted The function weights each recorded value equally. Select this option for batch values. This method requires at least one recorded value in a time period (two recorded values for standard deviation calculations). If you enter an expression in the Expression(s) field and set the Expression sampling field to interpolated, then the function interpolates values at the time interval boundaries when there are no recorded values.
  Expression sampling	The method that the function uses to determine when to evaluate an expression: compressed The function evaluates the expression during the time period at time stamps where PI points or PI AF attributes in the expression have stored values. If there are no stored values, the function returns either no value or an interpolated value. For best results, select interpolated rather than compressed during time periods with few stored values. interpolated The function evaluates the expression at evenly spaced sampling intervals, determined by Expression sampling frequency. See Interpolated values. Tip: For most accurate results, select interpolated and set the Expression sampling frequency field to a small frequency. Available if you select Expression or if you specify a Filter expression.
  Expression sampling frequency	The frequency that the function evaluates an expression. Required if you set Expression sampling to interpolated. For example, set to 10m (10 minutes) to compute an interpolated value every 10 minutes.
  Minimum percent good	The minimum percentage of good data required in each time interval to calculate and return a value for that interval. The function returns the label Insufficient good data for an interval that does not meet this percentage.
  Output cell	The worksheet cell where the function writes the resulting function array. If you select a cell before you open the function task pane, PI DataLink inserts the selected cell into the Output cell field. Specify the top-left corner of the function array. PI DataLink expands the range downward and to the right of the output cell, as necessary to return specified data. PI DataLink might overwrite adjacent cells. If you specify a multi-cell array in the Output cell field and the specified array is larger than the resulting function array, PI DataLink pastes the function formula in the unneeded cells of the specified array.
  Show start time	Select this check box to show the start time of the time interval used to calculate the returned value. PI DataLink shows the start time in a column to the left or in a row above returned values. Only available if you specify Time interval.
  Show end time	Select this check box to show the end time of the time interval used to calculate the returned value. PI DataLink shows the end time in a column to the left or in a row above returned values. Only available if you specify Time interval.
  Show min/max time	Select this check box to show the time stamp that corresponds to the minimum or maximum value during the interval used to calculate the value. Only available for three values of Calculation mode: maximum Shows the time stamp of the maximum value. minimum Shows the time stamp of the minimum value. range Shows the time stamps of the minimum value and the maximum value.
  Show percent good	Select this check box to show the percentage of time that good values were returned during the array time period. PI DataLink shows the percent-good values in a column to the right or in a row below returned values. Good values are recorded values that Data Archive determined were valid, and not in an error state. You might use the percentage of good values to assess the reliability of calculations built on PI point values, particularly if you use calculated values in further calculations. For example, if a time period includes bad data, the resulting time-weighted total equals the total divided by the fraction of the interval where good data is available. This normalization assumes that the average over the time period with bad data is equivalent to the average value over the entire period. Thus, the average becomes less reliable if a large fraction of the time period contains bad data.
  Column	Select this option to return values in a column.
  Row	Select this option to return values in a row. Note: If you specify a range of items in Data item(s) or a range of expressions in Expression(s), PI DataLink automatically selects Column or Row to match the orientation of the specified range.

See also

• PIAdvCalcVal()

  Specify a data item to retrieve a single value

• PIAdvCalcFilVal()

  Specify a data item and filter expression to retrieve a single value

• PIAdvCalcExpVal()

  Specify an expression to retrieve a single value

• PIAdvCalcExpFilVal()

  Specify an expression and a filter expression to retrieve a single value

• PIAdvCalcDat()

  Specify a data item and time interval to retrieve multiple values

• PIAdvCalcFilDat()

  Specify a data item, time interval, and filter expression to retrieve multiple values

• PIAdvCalcExpDat()

  Specify an expression and time interval to retrieve multiple values

• PIAdvCalcExpFilDat()

  Specify an expression, time interval, and filter expression to retrieve multiple values

• Retrieval of large amounts of data