PredictabilityEstimate - Global

The PredictabilityEstimate API is a scriptable object used in Predictive Intelligence stores. This object provides estimation of how predictable fields of a dataset can be, and which features can be useful for predicting those fields.

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

The predictability estimate setup-to-training flow is as follows:

1. Create a dataset using the DatasetDefinition API.
2. Use the constructor to create a predictability estimate object.
3. Add the predictability estimate object to the predictability estimate store using the PredictabilityEstimateStore - add() method.
4. Train the predictability estimate using the submitTrainingJob() method. This creates a version of the object that you can manage using the PredictabilityEstimateVersion API.
5. Get estimated predictive values using the PredictabilityEstimateVersion – getResults() method.

注:

This API runs with full privileges before the Vancouver Patch 7 Hotfix 2b and Washington DC Patch 7 releases. With later releases, grant access using ACLs. For more information see Query ACLs.

For usage guidelines, refer to Using ML APIs.

PredictabilityEstimate - PredictabilityEstimate(Object config)

Creates a predictability estimate.

To get new predictability estimates on the same dataset, use this constructor to create a new PredictabilityEstimate object with a unique name.

表 : 1. Parameters

Name	Type	Description
config	Object	JavaScript object containing configuration properties of the predictability estimate. { "dataset": {Object}, "domainName": "String", "inputFieldNames": [Array], "label": "String", "minRowCount": "String", "predictedFieldName": "String", "trainingFrequency": "String" }
config.dataset	Object	DatasetDefinition name.
config.domainName	String	Optional. Domain name associated with this dataset. See Domain separation and Predictive Intelligence. Default: Current domain, for example, "global".
config.inputFieldNames	Array	List of candidate input fields as strings to be considered for estimation.
config.label	String	Identifies the prediction task.
config.minRowCount	String	Optional. Minimum number of records required in the dataset for training. Default: 10000
config.predictedFieldName	String	Identifies a field to be trained for predictability.
config.trainingFrequency	String	Optional. 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

The following example shows how to create an estimation job and add it to the PredictabilityEstimate store.

var myIncidentData = new sn_ml.DatasetDefinition({
  'tableName' : 'incident',
  'encodedQuery' : 'activeANYTHING'
});

var myEstimate = new sn_ml.PredictabilityEstimate({
  'label': "predictability estimate",
  'dataset' : myIncidentData,
  'inputFieldNames':['short_description'], 
  'predictedFieldName': 'category'
});

var myEstimateName = sn_ml.PredictabilityEstimateStore.add(myEstimate);

PredictabilityEstimate - cancelTrainingJob()

Cancels a job for a predictability estimate object that has been submitted for training.

表 : 2. Parameters

Name	Type	Description
None

表 : 3. Returns

Type	Description
None

The following example shows how to cancel an existing training job.

var myEstimate = sn_ml.PredictabilityEstimateStore.get('ml_sn_global_global_predictability_estimate');

myEstimate.cancelTrainingJob();

PredictabilityEstimate - getActiveVersion()

Gets the active PredictabilityEstimateVersion object.

表 : 4. Parameters

Name	Type	Description
None

表 : 5. Returns

Type	Description
Object	Active PredictabilityEstimateVersion object.

The following example shows how to get an active PredictabilityEstimate version from the store and return its training status.

var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

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

Output:

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

PredictabilityEstimate - getAllVersions()

Gets all versions of a predictability estimate.

表 : 6. Parameters

Name	Type	Description
None

表 : 7. Returns

Type	Description
Array	Existing versions of a solution object. See also PredictabilityEstimateVersion API.

The following example shows how to get all PredictabilityEstimate version objects and call the getVersionNumber() and getStatus() estimate version methods on them.

var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

var mlEstimateVersions = mlEstimate.getAllVersions();

for (i = 0; i < mlEstimateVersions.length; i++) {
gs.print("Version " + mlEstimateVersions[i].getVersionNumber() + " Status: " + mlEstimateVersions[i].getStatus() +"\n");
};

Output:

Version 3 Status: {"state":"predictability_estimate_complete","percentComplete":"100","hasJobEnded":"true"}

Version 2 Status: {"state":"predictability_estimate_complete","percentComplete":"100","hasJobEnded":"true"}

Version 1 Status: {"state":"predictability_estimate_cancelled","percentComplete":"0","hasJobEnded":"true"}

PredictabilityEstimate - getLatestVersion()

Gets the latest version of a predictability estimate.

表 : 8. Parameters

Name	Type	Description
None

表 : 9. Returns

Type	Description
Object	PredictabilityEstimateVersion object corresponding to the latest version of a PredictabilityEstimate().

The following example shows how to get the latest version of a predictability estimate and return its training status.

var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

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

Output:

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

PredictabilityEstimate - getName()

Gets the name of the object to use for interaction with the store.

表 : 10. Parameters

Name	Type	Description
None

表 : 11. Returns

Type	Description
String	Name of the estimate object.

The following example shows how to update PredictabilityEstimate dataset information and print the name of the object.

// Update estimate
var myIncidentData = new sn_ml.DatasetDefinition({
   'tableName' : 'incident',
   'fieldNames' : ['category', 'short_description', 'priority'],
   'encodedQuery' : 'activeANYTHING'
});

var myEstimate = new sn_ml.PredictabilityEstimate({
   'label': "my estimate",
   'dataset' : myIncidentData,
   'inputFieldNames':['short_description'],
   'predictedFieldName': 'category'
});

// update estimate
sn_ml.PredictabilityEstimateStore.update('ml_x_snc_global_global_my_definition_4', myEstimate);

// print estimate name
gs.print('Estimate Name: '+myEstimate.getName());

Output:

Estimate Name: ml_x_snc_global_global_my_definition_4

PredictabilityEstimate - getProperties()

Gets predictability estimate object properties.

表 : 12. Parameters

Name	Type	Description
None

表 : 13. Returns

Type	Description
Object	Contents of the Dataset and PredictabilityEstimate() object details in the PredictabilityEstimateStore. { "datasetProperties": {Object}, "domainName": "String", "inputFieldNames": [Array], "label": "String", "name": "String", "predictedFieldName": "String", "scope": "String", "trainingFrequency": "String" }
<Object>.datasetProperties	Lists the properties of the DatasetDefinition() object associated with the estimate. { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" }
<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 standard Glide format. See Encoded query strings. Data type: String.
<Object>.domainName	Domain name associated with this dataset. See Domain separation and Predictive Intelligence. Data type: String.
<Object>.inputFieldNames	List of candidate input fields as strings to be considered for estimation. 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.

The following example gets properties of a predictability estimate object in the store.

var mySolution = sn_ml.PredictabilityEstimateStore.get('ml_sn_global_global_predictability_estimate');

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

Output:

*** Script: {
  "datasetProperties": {
    "tableName": "incident",
    "fieldNames": [
      "category",
      "short_description",
      "priority",
      "assignment_group.name"
    ],
    "fieldDetails": [
      {
        "name": "category",
        "type": "nominal"
      },
      {
        "name": "short_description",
        "type": "text"
      }
    ]
  },
  "domainName": "global",
  "inputFieldNames": [
    "short_description"
  ],
  "label": "my estimate definition",
  "name": "ml_x_snc_global_global_my_definition_26",
  "predictedFieldName": "category",
  "processingLanguage": "en",
  "scope": "global",
  "stopwords": [
    "Default English Stopwords"
  ],
  "trainingFrequency": "run_once"
}

PredictabilityEstimate - getVersion(String version)

Gets a predictability estimate by provided version number.

表 : 14. Parameters

Name	Type	Description
version	String	Existing version number of a predictability estimate.

表 : 15. Returns

Type	Description
Object	Specified version of the PredictabilityEstimate() object on which you can call PredictabilityEstimateVersion API methods.

The following example shows how to get the training status of a predictability estimate by version number.

var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

gs.print(JSON.stringify(JSON.parse(mlEstimate.getVersion('1').getStatus()), null, 2));

Output:

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

PredictabilityEstimate - setActiveVersion(String version)

Activates a specified version of a predictability estimate in the store.

表 : 16. Parameters

Name	Type	Description
version	String	Name of the PredictabilityEstimate() object version to activate. Activating this version deactivates any other version.

表 : 17. Returns

Type	Description
None

The following example shows how to activate a predictability estimate version in the store.

sn_ml.PredictabilityEstimate.setActiveVersion("ml_x_snc_global_global_my_estimate_definition");

PredictabilityEstimate - submitTrainingJob()

Submits a training job.

注:

Before running this method, you must first add a predictability estimate to the store using the PredictabilityEstimateStore - add() method.

表 : 18. Parameters

Name	Type	Description
None

表 : 19. Returns

Type	Description
Object	PredictabilityEstimateVersion object corresponding to the PredictabilityEstimate being trained.

The following example shows how to create a dataset, apply it to a predictability estimate, add it to a store, and submit the training job.

// Create a dataset 
var myData = new sn_ml.DatasetDefinition({

  'tableName' : 'incident',
  'fieldNames' : ['assignment_group', 'short_description', 'description'],
  'encodedQuery' : 'activeANYTHING'

});

// Create an estimate 
var myEstimate = new sn_ml.PredictabilityEstimate({

  'label': "my estimate definition",
  'dataset' : myData,
  'predictedFieldName' : 'assignment_group',
  'inputFieldNames':['short_description']

});

// Add the estimate to the store to later be able to retrieve it.
var my_unique_name = sn_ml.PredictabilityEstimateStore.add(myEstimate);

// Train the estimate - this is a long running job 
var myEstimateVersion = myEstimate.submitTrainingJob();