PredictabilityEstimateVersion - Global

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read

    • The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.

    This API requires the Predictive Intelligence plugin (com.glide.platform_ml) and is provided within the sn_ml namespace.

    Use this API when working with predictability estimate versions based on PredictabilityEstimate API objects in the PredictabilityEstimate store.

    The system activates the most recent version of the predictability estimate when it completes training, and only allows one version to be active at a time. However, you can activate any previously trained version you want to use to make predictions.

    Methods in this API are accessible using the following PredictabiltyEstimate methods:

    PredictabilityEstimateVersion - getProperties()

    Gets predictability estimate object properties and version number.

    Table 1. Parameters
    Name Type Description
    None
    Table 2. Returns
    Type Description
    Object Contents of the Dataset and PredictabilityEstimate version details. Results vary by object property setup.
    {
  "datasetProperties": {Object},
  "domainName": "String", 
  "inputFieldNames": [Array],
  "label": "String",
  "name": "String",
  "predictedFieldName": "String",
  "scope": "String",
  "trainingFrequency": "String",
  "versionNumber": "Number"
}
    <Object>.datasetProperties

    Lists the properties of the DatasetDefinition() object associated with the predictability estimate.

    {
  "encodedQuery": "String",
  "fieldDetails": [Array],
  "fieldNames": [Array],
  "tableName": "String"
}

    Data type: Object.
    <Object>.datasetProperties.tableName Name of the table for the dataset. For example, "tableName" : "Incident".

    Data type: String.
    <Object>.datasetProperties.fieldNames List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"].

    Data type: Array.
    <Object>.datasetProperties.fieldNames.fieldDetails List of JavaScript objects that specify field properties. 
    [
  {
    "name": "String",
    "type": "String"
  }
]

    Data type: Array.
    <Object>.datasetProperties.fieldNames.fieldDetails.<object>.name Name of the field defining the type of information to restrict this dataset to.

    Data type: String.
    <Object>.datasetProperties.fieldDetails.<object>.type Machine-learning field type.

    Data type: String.
    <Object>.datasetProperties.fieldDetails.encodedQuery Encoded query string in the standard platform format. See Encoded query strings.

    Data type: String.
    <Object>.domainName Domain name associated with this dataset. See Domain separation and Predictive Intelligence.

    Type: String
    <Object>.inputFieldNames List of candidate input fields as strings to be considered for estimation.

    Data type: String.
    <Object>.isActive Flag that indicates whether this version is active.
    Valid values:
    • true: Version is active.
    • false: Version is not active.

    Data type: String
    <Object>.label Identifies the prediction task. 
    {
  "label": "my first prediction"
}

    Data type: String.
    <Object>.name System-assigned name.

    Data type: String.
    <Object>.predictedFieldName Identifies a field to be trained for predictability.

    Data type: String.
    <Object>.scope Object scope. Currently the only valid value is global.

    Data type: String
    <Object>.trainingFrequency The frequency to retrain the model.
    Possible values:
    • every_30_days
    • every_60_days
    • every_90_days
    • every_120_days
    • every_180_days
    • run_once
    Default: run_once

    Data type: String.
    <Object>.versionNumber Version number of the PredictabilityEstimate object.

    Data type: String.

    The following example gets properties of the active object version in the store.

    // Get properties
var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getProperties()), null, 2));

    Output:

    "datasetProperties": {
    "encodedQuery": "activeANYTHING^EQ",
    "fieldNames": [
      "short_description",
      "category"
    ],
    "tableName": "incident"
  },
  "domainName": "global",
  "inputFieldNames": [
    "short_description"
  ],
  "isActive": "true",
  "label": "Incident Categorization_Trainer",
  "name": "ml_incident_categorization",
  "predictedFieldName": "category",
  "processingLanguage": "en",
  "stopwords": [
    "Default English Stopwords"
  ],
  "versionNumber": "1"
}

    PredictabilityEstimateVersion - getResults()

    Returns JSON results containing suggested input fields for an output field.

    Table 3. Parameters
    Name Type Description
    None
    Table 4. Returns
    Type Description
    Object JSON object results containing suggested input field options for an output field.
    <Object>.<output field name> Output field name, e.g., category, containing suggested input fields.
    {
  "<output field name>": {
    "nominalInputFields": [Array],
    "textInputFields": [Array]
  }
}

    Data type: Object
    <Object>.<output field name>.nominalInputFields Nominal input field details.
    "nominalInputFields": [
      {
        "fieldName": "String",
        "modelImprovement": "String"     
      }
    ]

    Data type: Array.
    <Object>.<output field name>.nominalInputFields.fieldName Nominal input field name.

    Data type: String.
    <Object>.<output field name>.nominalInputFields.modelImprovement Score as a relative indication of how likely this field is to improve results.

    Data type: Number as a string.
    <Object>.textInputFields Text input field details.
    
    "textInputFields": [
      {
        "fieldName": "String",
        "density": "String"
      }
    ]

    Data type: Array.
    <Object>.textInputFields.fieldName Text input field name.

    Data type: String.
    <Object>.textInputFields.density Value between 0 and 1.0 that represents frequency that the field is not empty. A value of 1.0 means that the field is not empty in all rows, and a value of 0 indicates that the field is empty in all rows.

    Data type: Number as a string.

    The following example shows how to get results for a selected version of a predictability estimate in the store.

    // Get results
var estimateName = "ml_x_snc_global_global_predictability_estimate;"
var mlEstimate = sn_ml.PredictabilityEstimateStore.get(estimateName);

var results = mlEstimate.getActiveVersion().getResults();

gs.print(JSON.stringify(JSON.parse(results), null, 2));

    Output:

    {
  "category": {
    "nominalInputFields": [
      {
        "fieldName": "number",
        "modelImprovement": "0.167052396325189"
      },
      {
        "fieldName": "task_effective_number",
        "modelImprovement": "0.167052396325189"
      }
    ],
    "textInputFields": [
      {
        "fieldName": "short_description",
        "density": "1.0"
      }
    ]
  }
}

    PredictabilityEstimateVersion - getStatus(Boolean includeDetails)

    Gets training completion status.

    Table 5. Parameters
    Name Type Description
    includeDetails Boolean Flag that indicates whether to return status details.
    Valid values:
    • true: Return additional details.
    • false: Don't return additional details.

    Default: False
    Table 6. Returns
    Type Description
    Object JavaScript object containing training status information for a PredictabilityEstimate object.
    {
  "state": "String",
  "percentComplete": "Number as a String",
  "hasJobEnded": "Boolean value as a String",
  "details": {Object}
}
    <Object>.state Training completion state. If the training job reaches a terminal state, the job does not leave that state. If the state is terminal, the hasJobEnded property is set to true.
    Possible values:
    • fetching_files_for_training
    • preparing_data
    • retry
    • solution_cancelled (terminal)
    • solution_complete (terminal)
    • solution_error (terminal)
    • solution_incomplete
    • training_request_received
    • training_request_timed_out (terminal)
    • training_solution
    • uploading_solution
    • waiting_for_training

    Data type: String
    <Object>.hasJobEnded Flag that indicates whether training is complete.
    Valid values:
    • true: Training is complete.
    • false: Training is incomplete.

    Data type: Boolean value as a String
    <Object>.percentComplete Training percent complete. If the completion percentage is less than 100, the job might be in a terminal state. For example, if training times out.

    Data type: Number as a String

    Range: 0 thru 100
    <Object>.details Object containing a list of additional training details.

    Data type: Object

    The following example shows a successful result with training complete.

    // Get status
var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getStatus(true), null, 2)));

    Output:

    {
 "state":"solution_complete",
 "percentComplete":"100",
 "hasJobEnded":"true",
 "details":{"stepLabel":"Solution Complete"} // This information is only returned if getStatus(true);
}

    The following example shows an unsuccessful result with training complete.

    // Get status
var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_my_estimate_definition');
var trainingStatus = mlEstimate.getLatestVersion().getStatus();

gs.print(JSON.stringify(JSON.parse(trainingStatus), null, 2));

    Output:

    {
  "state": "solution_complete",
  "percentComplete": "100",
  "hasJobEnded": "true"
}

    PredictabilityEstimateVersion - getVersionNumber()

    Gets the version number of a predictability estimate object.

    Table 7. Parameters
    Name Type Description
    None
    Table 8. Returns
    Type Description
    String Version number.

    The following example shows how to get a version number.

    // Get version number
var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

gs.print("Version number: "+JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getVersionNumber()), null, 2));

    Output:

    Version number: 1