Parameter Definition¶

The parameter definition object provides input for controlling the common-properties dialog. It consists of information that is available in the operator object combined with UI hints, information on data sets, and resources.

The parameter definition has a defined schema and set of examples located here: schema and examples

The parameter definition consists of the following sections:

Title Definition¶

The title of the properties editor. If editable is set to true (default), the title can be edited. If set to false, the title will be readonly.

"titleDefinition": {
    "title": "Properties Title",
    "editable": true
  }

Current Parameters¶

A list of input parameters and initial values upon input. The list is a set of key/value pairs with the key being the field name and the value is the initial value.

Example

"current_parameters": {
    "targetField": [],
    "inputFieldList": [],
    "elasticNetParam": 0.0,
    "fitIntercept": false,
    "maxIter": 75,
    "regParam": 0.1,
    "standardization": true,
    "threshold": 0.5,
    "tol": 0.0000010
  }

Parameter Definitions¶

The list of parameters definitions for this property dialog. The list contains the name of the parameter, the data type of the parameter, the role and the default value. The information provided is as needed by the backend engine, i.e. the parameter name should be the name of the parameter that is expected for the backend engine.

The list of parameter definitions has the following attributes:

id (string) Required Parameter identifier as consumed by the backend engine.
default (any) The default value of the parameter.
enum (array[string]) A restricted list of string values that are valid for the field.
type (string) Parameter type as consumed by the backend engine.
role (string) Parameter role, which is an optional specialization of the type.
required (boolean) Indication whether parameter is required or optional.

Parameter types have one of a fixed set of basic types. These are:

integer
double
string
date
time
timestamp
custom

These can be used as maps or arrays e.g.:

array[<value-type>]: a sequence or list of values

Parameter roles defined by the role attribute can be one of:

expression: an expression assumed to be in the expression language for the run time
column: value represents one or more columns from the data model visible to this operator
new_column: value represents the name of a new column to be added to the data model and must therefore not match an existing column and conform to existing syntactic restrictions.

Example

"parameters": [
    {
      "id":"targetField",
      "type":"string",
      "default":"",
      "role":"column"
    },
    {
      "id":"inputFieldList",
      "type":"array[string]",
      "default":[],
      "role":"column"
    },
    {
      "id": "impurity",
      "enum": [
        "gini",
        "entropy"
      ],
      "default": "gini"
    },
    {
      "id":"elasticNetParam",
      "type":"double",
      "default":0.0
    }
]

UI-only Parameters¶

A list of input parameters and initial values upon input. This set of parameters are separated from the backend parameters (current parameters). The idea is that these parameters are not passed into the backend engine by the common-properties consumer.

Example

"current_ui_parameters": {
    "databaseResource": true,
    "tol": 0.0000010
  }

UI-only parameters require information about the parameters same as the parameter definition information used for the backend parameters. The UI-only parameter definition information is stored in the UI-hints section in the sub-section named ui_parameters. A description of the UI hints specifications can be found on the UI Hints page.

UI-only properties are returned to the consuming application via a separate parameter on the applyPropertiesChanges callback. See the Callbacks page.

Complex Types¶

The complex types section is an array of

The complex types have the following attributes:

id (string) Required Identifier of complex type, can be referenced in other places.
type (string) If object is specified, Common Properties will return the values as an array of objects consisting of key value pairs. This defaults to array.
key_definition (object) A parameter definition attribute on the key parameter field.
parameters (object) Required List of parameters fields. Each parameter can be defined as a parameter definition attribute or a complex type attribute.

Example of complex types

"complex_types": [
    {
      "id": "SortEntry",
      "type": "object",
      "key_definition": {
        "id": "field",
        "type": "string",
        "role": "column",
        "default": ""
      },
      "parameters": [
        {
          "id": "sort_order",
          "enum": [
            "Ascending",
            "Descending"
          ],
          "default": "Ascending"
        }
      ]
    }
  ]

A Note on Parameters and Complex Types:¶

Note that both parameter and complex type definitions are in the exact same format as defined in the operator schema. Therefore the contents of operator JSON files can be used for these two sections.

UI Hints¶

A set of specifications for controlling the layout and flow of Common Properties. A description of the UI hints specifications can be found on the UI Hints page.

Conditions¶

A set of specifications for controlling validation checking of parameters during the common-properties dialog. A description of the Conditions specifications can be found here on the Conditions page.

Data Set Metadata¶

The data set metadata is an array of datarecord-metadata objects as defined in the datarecord-metadata JSON schema. Each datarecord-metadata object contains and array of fields that provide column information on the input data set. schema and examples

The fields have the following attributes:

name (string) Required Field name. Must be unique within the dataset.
type (string) Required Field type. Can be a primitive type (string, integer, double, date, time, timestamp), or a vector, map, or struct containing those types. Required.
nullable (boolean) Indicates whether or not one can place null values into the field. Default: False.
metadata (object) A set of additional metadata attributes.

The additional metadata attributes are as follows:

description (string) A description of the field.
measure (string) The field measurement type. The value can be one of the following. range, discrete, flag, set, ordered-set, typeless, collection, geospatial, default
role (string) Field role for modeling. The value can be one of the following. input, target, both, none, partition, split, frequency, record-id
max_string_length (number) Maximum character length for string fields. Length is unlimited when not present.
values (array[string]) Array of unique categorical values for the column.
ranges (object) Minimum and maximum discovered values for scalar data.

Example

"dataset_metadata": [
  {
    "name": "Schema-1",
    "fields": [
      {
        "name": "Age",
        "type": "integer",
        "metadata": {
          "description": "",
          "measure": "range",
          "role": "input"
        }
      },
      {
        "name": "Sex",
        "type": "string",
        "metadata": {
          "description": "",
          "measure": "discrete",
          "role": "input"
        }
      },
      {
        "name": "BP",
        "type": "string",
        "metadata": {
          "description": "",
          "measure": "discrete",
          "role": "input"
        }
      }
    ]
  },
  {
    "name": "Schema-2",
    "fields": [
      {
        "name": "Birthdate",
        "type": "date",
        "metadata": {
          "description": "Date of birth",
          "measure": "range",
          "role": "input"
        }
      }
    ]
  }
]

Resources¶

This is a map of string resources.

Example:

"resources":{
  "org.apache.spark.ml.classification.DecisionTreeClassifier.label":"Random Forest Classifier",
  "org.apache.spark.ml.classification.DecisionTreeClassifier.desc":"Fitted Random Forest Classification Model",
  "inputFieldList.label":"Input columns",
  "inputFieldList.desc":"Select one or more input columns",
  "targetField.label":"Target column",
  "targetField.desc":"Select a target column",
  "max_depth_not_valid":"The max depth parameter must be greater than or equal to zero",
  "max_iter_not_valid": "The max iterations parameter must be greater than or equal to zero",
  "min_instances_per_node_not_valid": "The minimum instances per node value must be >= 1",
  "subsampling_rate_not_valid": "The subsampling rate value must be > 0 and <= 1"
}