Input and output

You submit a decision problem to the Tradeoff Analytics service via its HTTP POST dilemmas method. You submit the objectives and options for a decision problem as a JSON Problem object. In response, the service returns its results as a JSON Dilemma object that includes both the original Problem and its Resolution. For complete details about the programming interface, see the API reference.

You can elect to receive the parameters required by the Tradeoff Analytics widget as part of the resolution. For more information about coding with the widget, see Programming with the widget.

Input: The decision problem

You call the Tradeoff Analytics service by sending a JSON Problem object in the body of the request to the service's dilemmas method. The following Unified Modeling Language (UML) diagram describes the Problem object.

Tradeoff Analytics Problem Object

The following table describes the fields of the Problem object, all of which are required. The following sections describe the objects it comprises.

Fields of the Problem object
Field Type Status Description
subject String Required The name of the decision problem. The name typically reflects the category of the options.
columns Column[] Required An array of possible objectives for the decision problem. The field specifies the columns for the tabular representation of the data. For more information, see Specifying objectives.
options Option[] Required An array of options for the decision problem. The field specifies the rows for the tabular representation of the data. For more information, see Specifying options.

Generating a visualization

You can specify whether the service is to return just the resolution for the problem or both the resolution and the parameters for the Tradeoff Analytics visualization via The Map object. The optional query parameter generate_visualization accepts a boolean value that specifies whether the service returns the visualization parameters. If you set the parameter to true or omit it, the service returns the visualization parameters.

Using the Tradeoff Analytics interface imposes certain requirements and limits on the size of the decision problem:

  • You can specify a maximum of 10 objectives for which the is_objective field is true. To generate visualization results, the field must be true for at least three objectives

  • The maximum number of options is calculated as the number of objectives multiplied by the number of best candidates. This value must be less than 2000.

  • To generate visualization results, at least three options must have a status of FRONT in the Solution object that is returned as part of the problem Resolution object. For more information, see Output: The problem resolution.

If you exceed either of the limits, the service returns an HTTP 413 error code ("Problem received is too large"). The service imposes no limits on the size of the decision problem when generate_visualization is false.

Specifying objectives and Specifying options describe which fields of the Column and Option objects are needed to define the decision problem and which are needed only if you plan to use the Tradeoff Analytics widget.

Specifying objectives

The problem objectives specify the goals against which the service evaluates each option. You specify the objectives as an array of Column objects via the columns field of the Problem object. The following table describes the fields of the Column object that are needed to define the decision problem.

Fields of the Column object (definition)
Field Type Status Description
key String Required An identifier for the column that is unique among all columns for the problem.
type String =
 "text" |
 "numeric" |
 "datetime" |
 "categorical"
Optional The type of the column:
  • text columns (the default) require a string.
  • numeric columns require a number literal (integer or double).
  • datetime columns require a date and time string in full ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD (for example, 2015-05-25T19:20:30.45+01:00 or 2015-05-26T00:00:00Z)
  • categorical columns require a string that is one of the valid values specified by the range field for the column.
Use the range field to specify the range of valid values for an objective.
goal String =
 "min" |
 "max"
Optional The direction for the column:
  • min indicates that the goal is to minimize the objective (for example, the price of a vehicle).
  • max (the default) indicates that the goal is to maximize the objective (for example, the safety rating of a vehicle).
The goal is meaningful only for columns for which is_objective is true.
is_objective Boolean Optional An indication of whether the column is an objective for the problem. If true, the column contributes to the resolution; if false (the default), the column does not contribute to the resolution. A column of type text cannot be set to true. For restrictions that apply when you use the Tradeoff Analytics widget, see Generating a visualization.
range IRange Optional The range of valid values for the column. Any option whose value for the column is outside of the specified range is marked as incomplete and is excluded from the resolution. By default, the range is calculated automatically from the minimum and maximum values that are provided in the data set for the column. For more information, see Specifying ranges.
preference String[] Optional For categorical columns, specifies an array of strings that is a preferred subset of the strings in the column's range. The order of the values in preference indicates the actual preference for the values in range.

The order of the values in preference is important. If goal is min, elements in the low position (at the front) of the array are favored over later elements; if goal is max, elements in the high position of the array are favored. By default, values are preferred according to their ordering in range and the direction indicated by goal.
significant_gain Number Optional A significant gain for the column in the range of 0 to 1. The value is a proportion of the complete range for the column. The field is relevant only for columns for which is_objective is true.
significant_loss Number Optional A significant loss for the column in the range of 0 to 1. The value is a proportion of the complete range for the column. The field is relevant only for columns for which is_objective is true.
insignificant_loss Number Optional An insignificant loss for the column in the range of 0 to 1. The value is a proportion of the complete range for the column. The field is relevant only for columns for which is_objective is true.

The following table describes the fields of the Column object that are needed only if you plan to use the Tradeoff Analytics widget. The service does not use these fields to determine a problem resolution; it passes them as specified to the widget.

Fields of the Column object (visualization)
Field Type Status Description
format String Optional For columns whose type is numeric or datetime, specifies how the value is to be displayed by the widget's interface. For more information, see Formatting numbers and dates.
full_name String Optional A short description of the column. The full_name is displayed in the widget's interface. If you omit this field, the interface displays the column's key instead.
description String Optional A long description of the column. The description is displayed when the user examines the column more closely in the widget's interface.

Specifying ranges

You can specify the range of valid values for a column via the range field of the Column object. The service excludes from the resolution any option whose value for the column is outside of the specified range, indicating that it is incomplete. In addition, the Tradeoff Analytics interface applies the specified range when it displays the problem resolution, so you can use the range to enforce a scale in the interface.

Specifying a range is useful, for example, when an objective has a natural range that you want to enforce. For instance, valid percentages lie between 0 and 100. You can specify a range to enforce this constraint, and the widget's interface also reflects the specified range.

The range field accepts an abstract object of type IRange, which in turn accepts different types of ranges depending on the type of the column:

  • For numeric columns, you specify a ValueRange that indicates the high and low, or maximum and minimum, valid values for the column's range. You specify the values as integers or doubles. The following example specifies a range of 50 to 100 for a numeric objective:

    "range": {
       "low": 50,
       "high": 100
    }
  • For datetime columns, you specify a DateRange that indicates the high and low, or latest and earliest, valid dates for the column's range. You specify the values as strings in full ISO 8601 format. The following example specifies a range from July 1, 2015, to December 31, 2015, for a datetime objective:

    "range": {
       "low": "2015-07-01T00:00:00Z",
       "high": "2015-12-31T23:59:59Z"
    }
  • For categorical columns, you specify a CategoricalRange that lists the keys that are valid for the column. By default, values are preferred in the order in which you list them in the array. The column's goal field indicates the order of preference. If goal is min, elements in the low position (at the front) of the array are preferred; if goal is max, elements in the high position are preferred. You can also use the preference field to list a subset of the elements in the range in their preferred order. The following example specifies a range of four acceptable values for a categorical objective:

    "range": [
            "Apple",
            "HTC",
            "Samsung",
            "Sony"
    ]

You cannot specify a range for a column of type text.

Formatting numbers and dates

For a column of type numeric or datetime, you can use the format field of the Column object to specify how the interface of the Tradeoff Analytics widget is to format values specified by options for the column. The format field accepts different types of specifications for the two types of columns. In both cases, the Tradeoff Analytics interface interprets the pattern according to the locale of the user's browser.

For numeric columns, you can specify the following:

  • The number of decimal places in the format "number: n", where n is a positive integer value that indicates the number of decimal places.

  • A currency symbol in the format "currency: 'symbol' : n", where symbol is the currency symbol and n is a positive integer value that indicates the number of decimal places.

  • A prefix in the format "taPrefix: 'symbol'", where symbol is the prefix string.

  • A suffix in the format "taSuffix: 'symbol'", where symbol is the suffix string.

You can combine formatters with a | (vertical bar). The following table shows examples of the numeric formatters.

Pattern Input Locale Result
"format": "number: 2" 239.9 English

French
239.90

239,90
"format": "number: 1" 150.92 English

French
150.9

150,9
"format": "currency: 'USD$' : 2" 199 English

French
USD$199.00

199,00 USD$
"format": "taPrefix: 'g'" 199 English

French
g199

g199
"format": "taSuffix: 'g'" 199 English

French
199g

199g
"format": "number: 2 | taSuffix: 'g'" 199 English

French
199.00g

199,00g

For datetime columns, you can specify how dates and times are to be presented in the format "date: 'format'", where format indicates the date and time pattern. The following table shows examples of the datetime formatter.

Pattern Input Locale Result
"format": "date: 'MMM dd, yyyy'" 2015-05-07T09:23:31Z English

French
May 7, 2015

mai 7, 2015
"format": "date: 'h:m:s a'" 2015-05-07T09:23:31Z English

Chinese
9:23:31 AM

9:23:31 上午
"format": "date: 'MMM dd, yyyy h:m:s a'" 2015-05-07T09:23:31Z English

Spanish
May 7, 2015 9:23:31 AM

may 7, 2015 9:23:31 am

For more information about specifying number, currency, and date formatter patterns, see the descriptions of the corresponding filter components in the AngularJS documentation.

Specifying options

The problem options define the candidates the service is to evaluate against the specified objectives. The objectives define the goals of the problem; the options meet those objectives to varying extents. You specify options as an array of Option objects via the options field of the Problem object. Each option must specify a valid value for each column whose is_objective field is true. The following table describes the fields of the Option object that are needed to define the decision problem.

Fields of the Option object (definition)
Field Type Status Description
key String Required An identifier for the option that is unique among all options for the problem.
values {String: Number | String, ...} Required A map of key-value pairs that specifies a value for each column in the format

"values": { "key1": value1, "key2": value2 }

A value must be of the type defined for its column. An option that fails to specify a value for a column for which is_objective is true is marked as INCOMPLETE and is excluded from the resolution.

The following table describes the fields of the Option object that are needed only if you plan to use the Tradeoff Analytics widget. The service does not use these fields to determine a problem resolution; it passes them as specified to the widget.

Fields of the Option object (visualization)
Field Type Status Description
name String Optional The name of the option.
description_html String Optional A description of the option in HTML format. The description is displayed when the user selects the option from the widget's interface.
app_data {String: String, ...} Optional A map of key-value pairs in which the application can pass application-specific information in the format

"app_data": { "key1": value1, "key2": value2 }

The service carries the information but does not use it.

Output: The problem resolution

The Tradeoff Analytics service sends its response to a call to the dilemmas method in the form of a JSON Dilemma object. The following UML diagram describes the Dilemma object.

Tradeoff Analytics Dilemma Object

The following table describes the fields of the Dilemma object, both of which are always included in the response.

Fields of the Dilemma object
Field Type Status Description
problem Problem Required The Problem object submitted in the call to the dilemmas method of the service. For more information, see Input: The decision problem.
resolution Resolution Required The resolution of the decision problem sent to the service. For more information, see The Resolution object.

The Resolution object

The Resolution object contains the service's response to the decision problem. The following table describes the fields of the Resolution object.

Fields of the Resolution object
Field Type Status Description
solutions Solution[] Required An array of Solution objects that contains the analytical data prepared by the service for each option of the decision problem. For more information, see The Solution object.
map Map Optional The two-dimensional positioning of each option on the map polygon displayed by the widget's interface. The resolution includes this field only if the query parameter generate_visualization is true, the is_objective field is true for at least three columns, and at least three options have a status of FRONT in the problem resolution. For more information, see The Map object.

The Solution object

The service returns an array of Solution objects that always includes an element for each option of the decision problem. The resolution contains the results of the service's analysis of each option in the context of both the objectives and the other options. The information includes the option's status and its possible relationship to other options. The following table describes the fields of the Solution object.

Fields of the Solution object
Field Type Status Description
solution_ref String Required The key that uniquely identifies the option in the decision problem.
status String =
 "FRONT" |
 "EXCLUDED" |
 "INCOMPLETE" |
 "DOES_NOT_MEET_PREFERENCE"
Required The status of the option for the problem resolution:
  • FRONT indicates that the option is included among the best candidates for the problem.
  • EXCLUDED indicates that another option is strictly better than the option.
  • INCOMPLETE indicates that either the option's specification does not include a value for one of the columns or its value for one of the columns lies outside the range specified for the column. Only a column whose is_objective field is set to true can generate this status.
  • DOES_NOT_MEET_PREFERENCE indicates that the the option specifies a value for a categorical column that is not included in the column's preference.
excluded_by ExcludedBy[] Optional If the status of the option is EXCLUDED, an array of ExcludedBy objects that lists each of the superior options that excluded the current option and describes each value that was strictly better than the current option's value. For more information, see The ExcludedBy object.
status_cause StatusCause Optional If the status of the option is INCOMPLETE or DOES_NOT_MEET_PREFERENCE, a StatusCause object that provides more information about the cause of the status. For more information, see The StatusCause object.
shadows String[] Optional An array of references to the keys of solutions that are shadowed by this solution.
shadow_me String[] Optional An array of references to the keys of solutions that shadow this solution.

The ExcludedBy object

If the status of an option is EXCLUDED, the excluded_by field of the Solution object for the option specifies an array of ExcludedBy objects that provides information about the options that were strictly better. The following table describes the fields of the ExcludedBy object.

Fields of the ExcludedBy object
Field Type Status Description
solution_ref String Required The key that uniquely identifies the option that was strictly better than the current option.
objectives Objectives[] Required An array of Objectives objects that describes each value of the superior option that was better than the current option.

An Objectives object provided in the objectives field includes the following fields.

Fields of the Objectives object
Field Type Status Description
key String Required The key that uniquely identifies the column (objective) of the superior option whose value was better than the corresponding value of the current option.
difference Number Required The difference between the values of the superior option and the current option for the column (objective). The difference can be an integer or a double depending on the column definition.
text String Optional For categorical columns, a description of the difference between the two values as a preference. For datetime columns, a description of the difference between the two values as a number of days, hours, and minutes, as needed.

The StatusCause object

If the status of an option is INCOMPLETE or DOES_NOT_MEET_PREFERENCE, the status_cause field of the Solution object for the option specifies a StatusCause object that provides more information about the option's status. The following table describes the fields of the StatusCause object.

Fields of the StatusCause object
Field Type Status Description
message String Required A description in English of the cause for the option's status.
tokens String[] Required An array of values used to describe the cause for the option's status. The strings appear in the message field.
error_code String =
 "MISSING_OBJECTIVE_VALUE" |
 "RANGE_MISMATCH" |
 "DOES_NOT_MEET_PREFERENCE"
Required An error code that specifies the cause of the option's status:
  • MISSING_OBJECTIVE_VALUE indicates that a column for which the is_objective field is true is absent from the option's specification.
  • RANGE_MISMATCH indicates that the option's specification defines a value that is outside of the range specified for an objective.
  • DOES_NOT_MEET_PREFERENCE indicates that a categorical column value for the option is not included among the preferences for that column.

The Map object

The Map object specifies the two-dimensional positioning of each option on the Tradeoff Analytics map visualization. The Tradeoff Analytics widget consumes the fields of this object to render the visualization. The Resolution object includes the map field only if the following are all true:

  • The query parameter generate_visualization is true.

  • The is_objective field is true for at least three columns.

  • At least three options have a status of FRONT in the problem resolution.

The following UML diagram depicts the Map object.

Tradeoff Analytics Map Object

The following table describes the fields of the Map object that are related to the placement of nodes and cells. Additional fields intended for use only by the widget are not described.

Fields of the Map object
Field Type Status Description
anchors Anchor[] Required An array of Anchor objects that represent the vertices for the objectives and their positions on the map visualization.
nodes MapNode[] Required An array of MapNode objects for the cells on the map visualization. Each cell in the array includes coordinates that describe the position on the map of the glyphs for one or more listed options, which are identified by their keys.