IBM InfoSphere Streams Version 4.1.1

Control input port and supported control signals and parameters

SPL standard and specialized toolkits > com.ibm.streams.timeseries 3.2.0 > Control input port and supported control signals and parameters

The control port is an optional input port where you can send control signals to control the behavior of an operator. You can change the behavior of the operator at run time without having to recompile your application.

For example, you can send a control signal to the control port to retrain operators that are not adaptive. If the input data that was used during the learning cycle to estimate the model loses its relevance or the trend of the input data changes significantly, the operator can no longer predict values accurately. You can send a control signal to the operator and provide sample data for re-estimating the model. The operator can then use this sample data to re-estimate the model to predict values accurately.

The control port supports the following control signals:
  • Retrain:

    Use new input time series data to rebuild the model. When you retrain a model, the operator takes additional input data and rebuilds the internal mathematical model so that the prediction is more accurate.

  • Load:

    Initialize the model with the provided coefficients. If you provide incorrect coefficients, the operator logs a warning message in the log file and continues to predict values by using the older coefficients.

  • Monitor:

    Write the coefficients to the optional monitor output port for later use or for further analysis.

  • Suspend:

    Stop the training of the model and forecasting of values temporarily. The training of the model and forecasting is suspended until the operator receives the Resume signal.

  • Resume:

    Continue with the model training process and forecasting.

Operators and supported control signals

The following list contains the supported control signals for the operators that support the optional input control port:
  • ARIMA
    • Supported control signals: Retrain, Monitor, Load, Suspend, and Resume
  • AutoForecaster
    • Supported control signals: Retrain, Suspend, and Resume
  • HoltWinters
    • Supported control signals: Retrain, Monitor, Load, Suspend, and Resume
  • LPC
    • Supported control signals: Retrain, Monitor, Load, Suspend, and Resume
  • VAR
    • Supported control signals: Retrain, Monitor, Load, Suspend, and Resume
  • DSPFilter
    • Supported control signals: Monitor and Load

Control port parameters

The following optional parameters represent the attributes that contain the control signal and the parameters for the control port:
  • controlSignal:

    This optional parameter is an attribute expression that specifies the name of the attribute in the control port, which holds the control signal. The supported type is TSSignal.

  • partitionBy:

    This optional parameter is an attribute expression that specifies the name of the attribute in the control port, which the operator uses for retraining, loading, and monitoring a model. If the operator uses the partitionBy parameter, you must also specify the key value to identify the model that you want to retrain, monitor, or load.

  • inputCoefficient:
    This optional parameter is an attribute expression that specifies the name of the attribute in the control port, which ingests the coefficients that are used for loading the model. If this parameter is not specified, by default, the inputCoefficient attribute is used. If the default attribute or the inputCoefficient parameter is not provided, the operator throws an exception. If the attribute or the parameter value does not contain valid coefficients, the load operation fails and the operator logs a warning message for each failed operation. The operator continues to predict values by using the older coefficients. The supported type is map<rstring,map<uint32,float64>>. The following list contains the format for specifying the coefficients:
    • ARIMA
      • Format: {"AR":{0u:{0u:1.1,1u:1.2},1u:{0u:1.2,1u:1.3}},"MA":{0u:{0u:1.1,1u:1.2}}
    • Holtwinters
      • Format: {"Alpha":{0u:0.5,1u:1.3},"Beta":{0u:0.5,1u:1.3},"Gamma":{0u:0.5,1u:1.3}}
    • LPC
      • Format: {{0u:{0u:1.1,1u:1.2},1u:{0u:1.2,1u:1.3}}
    • VAR
      • Format: {{0u:{0u:[1.1,1.2],1u:[1.2,1.3]},1u:{0u:[1.1,1.2],1u:[1.1,1.2]}}…}
    • DSPFilter
      • Format: {"xcoeff":{0u:1.1,1u:1.2},”ycoef”:{0u:1.2,1u:1.3}}
  • retrainingConfig:
    This optional parameter is an attribute expression that specifies the name of the attribute in the control port, which ingests the configurations that are used for retraining the model. If this parameter is not specified, by default, the retrainingConfig attribute is used. If the default attribute or the retrainingConfig parameter is not provided, the operator throws an exception. If the attribute or the parameter does not contain valid configurations, the retrain operation fails and the operator logs a warning message for each failed operation. The operator continues to predict values by using the older configuration. The supported type is map<rstring,uint32>. The following list contains the format for specifying the retraining configurations:
    • ARIMA
      • Use the initSamples parameter of the operator to specify the number of samples to use for retraining the model. For example: {"initSamples":12}.
    • AutoForecaster
      • Use the initSamples parameter of the operator to specify the number of samples to use for retraining the model. For example,: {"initSamples":13}.
    • Holtwinters
      • Use the initSeason parameter of the operator to specify the number of seasons to use for retraining the model and the samplesperSeason parameter specify the samples per season. For example: {"initSeason":13, "samplesperSeason":4}.
    • LPC
      • Use the initSamples parameter of the operator to specify the number of samples to use for retraining the model and the order parameter to specify the order of the autoregressive model. For example: {"initSamples":13,"order":4}.
    • VAR
      • Use the initSamples parameter of the operator to specify the number of samples to use for retraining the model and the order parameter to specify the order of the multivariate autoregressive model. For example: {"initSamples":13,"order":2}.

Exceptions

An operator throws an exception in the following cases:
  • A Load signal is sent to the control port and the inputCoefficient attribute is missing.
  • A Retrain signal is sent on the control port and the retrainingConfig attribute is missing.
  • A Load signal is sent to the control port and the Alpha, Beta, or Gamma value for the HoltWinters operator is less than zero or greater than one. The HoltWinters operator terminates after throwing an exception.