Curl Node Java Python

Tradeoff Analytics

API Reference
IBM Watson Tradeoff Analytics API reference

Introduction

The IBM Watson™ Tradeoff Analytics service helps people make better choices when faced with a decision problem that includes multiple, often conflicting, goals and alternatives. By using mathematical filtering techniques to identify the top options based on different criteria, the service can help users explore the trade-offs between options to make complex decisions. The service also offers smart visualization via a JavaScript library for intuitive graphical exploration of trade-offs.

API endpoint


https://gateway.watsonplatform.net/tradeoff-analytics/api

The code examples on this tab use the client-side library that is provided for Node.js.

GitHub

https://github.com/watson-developer-cloud/node-sdk

Node Package Manager


npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for Java.

GitHub

https://github.com/watson-developer-cloud/java-sdk

Maven


<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.5.3</version>
</dependency>

Gradle


compile 'com.ibm.watson.developer_cloud:java-sdk:3.5.3'

The code examples on this tab use the client-side library that is provided for Python.

GitHub

https://github.com/watson-developer-cloud/python-sdk

Python


pip install --upgrade watson-developer-cloud

easy_install --upgrade watson-developer-cloud

Synchronous and asynchronous requests

The Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of all methods. All methods are called with the Java ServiceCall interface.

  • To call a method synchronously, use the execute method of the ServiceCall interface. You can also call the execute method directly from an instance of the service, as shown in Get dilemma. Note that the method can return an unchecked RuntimeException.

  • To call a method asynchronously, use the enqueue method of the ServiceCall interface to receive a callback when the response arrives. The ServiceCallback interface of the method's argument provides onResponse and onFailure methods that you override to handle the callback.

Example synchronous request


ServiceCall call = service.dilemmas(problem, false);
Dilemma dilemma = call.execute();
    

Example asynchronous request


ServiceCall call = service.dilemmas(problem, false);
call.enqueue(new ServiceCallback<Dilemma>() {
  @Override public void onResponse(Dilemma dilemma) {
    . . .
  }
  @Override public void onFailure(Exception e) {
    . . .
  }
});
    

More information

An interactive tool for testing calls to the API and viewing live responses from the service is available in the Tradeoff Analytics API explorer. Descriptions of Node classes referred to in this reference are available in the Node documentation for the Watson Developer Cloud Node.js SDK. Descriptions of Java classes referred to in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK. Descriptions of Python modules referred to in this reference are available in the Python documentation for the Watson Developer Cloud Python SDK. Detailed information about using the service is available at Using the Tradeoff Analytics service.

Authentication

You authenticate to the Tradeoff Analytics API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses HTTP basic authentication.

After creating an instance of the Tradeoff Analytics service, select Service Credentials from the navigation on the left side of its dashboard page to see the username and password that are associated with the instance. For more information, see Obtaining credentials for Watson services.

Applications can also use tokens to establish authenticated communications with Watson services without embedding their service credentials in every call. You write an authentication proxy in Bluemix to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Using tokens with Watson services.

Replace {username} and {password} with your service credentials. Use either of the two constructors shown.


curl -u "{username}":"{password}"
"https://gateway.watsonplatform.net/tradeoff-analytics/api/v1/{method}"

var TradeoffAnalyticsV1 = require('watson-developer-cloud/tradeoff-analytics/v1');
var tradeoff_analytics = new TradeoffAnalyticsV1({
  username: '{username}',
  password: '{password}'
});

TradeoffAnalytics service = new TradeoffAnalytics();
service.setUsernameAndPassword("{username}", "{password}");

TradeoffAnalytics service = new TradeoffAnalytics("{username}", "{password}")

tradeoff_analyitcs = TradeoffAnalyticsV1(
    username='username}',
    password='{password}')

Request logging

By default, Bluemix collects data from all requests and uses the data to improve the Watson services. If you do not want to share your data, you can disable request logging by setting the X-Watson-Learning-Opt-Out header to true for each request. Data is not collected for any request that includes this header. setting the X-Watson-Learning-Opt-Out parameter to true when you create the service instance. Data is not collected for any calls by that instance of the service. setting the X-Watson-Learning-Opt-Out header to true when you create the service instance. Data is not collected for any calls by that instance of the service. setting the x-watson-learning-opt-out parameter to True when you create the service instance. Data is not collected for any calls by that instance of the service. For more information, see Controlling request logging for Watson services.


curl -u "{username}":"{password}"
--header "X-Watson-Learning-Opt-Out: true"
"https://gateway.watsonplatform.net/personality-insights/api/v3/{method}"

var TradeoffAnalyticsV1 = require('watson-developer-cloud/tradeoff-analytics/v1');
var tradeoff_analytics = new TradeoffAnalyticsV1({
  username: '{username}',
  password: '{password}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

TradeoffAnalytics service = new TradeoffAnalytics();
service.setUsernameAndPassword("{username}", "{password}");
service.setDefaultHeaders(headers);

tradeoff_anaytics = TradeoffAnalyticsV1(
    username='username}',
    password='{password}',
    x-watson-learning-opt-out=True
)

Response handling

The Tradeoff Analytics service uses standard HTTP response codes to indicate whether a method completed successfully. A 200-level response always indicates success. A 300-level response indicates the requested resource has not been modified. A 400-level response indicates some sort of failure. And a 500-level response typically indicates an internal system error.

Response codes that indicate success are not readily available with the Node.js SDK. In general, the lack of an error response indicate a 200-level success response. For errors, response codes are indicated in the error object that is returned.

The Java SDK raises equivalent exceptions. The exceptions include the error message returned by the service.

The Python SDK raises exceptions. The exceptions include the error message returned by the service.

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (The same problem was received.)
400 Bad Request The submitted problem was malformed.
401 Unauthorized Access is denied due to invalid service credentials.
413 Request Entity Too Large The submitted problem was too large.
500 Server Error The service encountered an internal error.

Exceptions thrown

Exception Description
IllegalArgumentException An illegal argument was passed to a method that accepts one or more arguments.
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
BadRequestException A required input parameter is null or a specified input parameter or header value is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid service credentials. (HTTP response code 401.)
RequestTooLargeException The submitted problem is too large. (HTTP response code 413.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Exceptions thrown

Exception Description
WatsonInvalidArgument The call to the Python method was invalid; for example, the call passed an invalid argument. The Python module raises this exception without calling the service.
WatsonException The service returned an error in response to the call. The Python module raises this exception to report the error from the service.

Error format

Name Description
error string A description of the error.
code integer The HTTP status code.
Name Description
Exception string The name of the exception that was raised.
status integer The HTTP status code.
error string A description of the error.
Name Description
Exception string The name of the exception that was raised.
Error string A description of the error.
Code integer The HTTP status code.

Example error


{
  "error": 'Data supplied is missing critical information. All objectives must have keys',
  "code": 400
}

{
  Error: Not Authorized
  . . .
  code: 401,
  error: 'Not Authorized',
  description: '2017-01-21T14:00:49-05:00, Error ERCDPLTFRM-DNAUTHZERR occurred when accessing https://158.85.132.88:443/tradeoff-analytics/api/v1/dilemmas?generate_visualization=false, Tran-Id: gateway-dp01-1351909404 - Invalid UserId and/or Password.'
}

SEVERE: POST https://gateway.watsonplatform.net/tradeoff-analytics/api/v1/dilemmas?generate_visualization=false, status: 401, error: Not Authorized
Exception in thread "main" com.ibm.watson.developer_cloud.service.exception.UnauthorizedException: Unauthorized: Access is denied due to invalid credentials
  . . .

Traceback (most recent call last):
  . . .
    raise WatsonException(error_message)
watson_developer_cloud.watson_developer_cloud_service.WatsonException:
  Error: Data supplied is missing critical information. an option must have a valid key, Code: 400

Methods

Get dilemma

Returns a dilemma that contains a problem and its resolution. The problem contains a set of columns (objectives) and options. The resolution contains a set of optimal options, their analytical characteristics, and, by default, their representation on a two-dimensional space.


POST /v1/dilemmas

dilemmas(params, callback())

Dilemma dilemmas(Problem problem)
Dilemma dilemmas(Problem problem, Boolean generateVisualization)

dilemmas(params, generate_visualization=True)

Request

Parameter Type Description
Content-Type header string The type of the input, application/json.
body body object A Problem object that provides the decision problem.
generate_visualization query boolean Indicates whether to calculate the map visualization for the results. If true (the default), the visualization is returned if 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.
Arguments for params
Parameter Description
columns object[ ] An array of Column objects that lists the objectives for the decision problem. The field typically specifies the columns for the tabular representation of the data.
options object[ ] An array of Option objects that lists the options for the decision problem. The field typically specifies the rows for the tabular representation of the data.
subject string A name for the decision problem. The field typically provides a heading for the column that represents the options in the tabular representation of the data.
generate_visualization boolean Indicates whether to calculate the map visualization for the results. If true (the default), the visualization is returned if 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.
metadataHeader string Metadata that can sent by the calling application for usage and analytical purposes. In a request to the service, the metadata fields are concatenated in the format key=value and sent via the HTTP x-watson-metadata. For more information, see Tracking usage for analysis.
Parameter Description
params string A Problem object that provides the decision problem.
generate_visualization boolean Indicates whether to calculate the map visualization for the results. If true (the default), the visualization is returned if 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.
Problem
Name Description
columns object[ ] An array of Column objects that lists the objectives for the decision problem. The field typically specifies the columns for the tabular representation of the data.
options object[ ] An array of Option objects that lists the options for the decision problem. The field typically specifies the rows for the tabular representation of the data.
subject string A name for the decision problem. The field typically provides a heading for the column that represents the options in the tabular representation of the data.
Column
Name Description
key string An identifier for the column. The key must be unique among all columns for the decision problem.
type string The type of the column's values:
  • numeric columns accept number values (integers or doubles).
  • datetime columns accept date and time values in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
  • categorical columns accepts string values specified by using the range field.
  • text (the default) columns accept strings.
goal string The direction of 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 Indicates whether the column is an objective for the decision problem. If true, the column contributes to the resolution; if false (the default), the column does not contribute to the resolution. The value cannot be set to true for a column of type text. If generate_visualization is true, is_objective must be true for a minimum of three columns and a maximum of 10 columns.
range object A CategoricalRange, DateRange, or ValueRange object that indicates the range of valid values for a categorical, datetime, or numeric column, respectively. An option whose value is outside of the specified range is marked as INCOMPLETE and is excluded from the resolution. By default, the range is calculated from the minimum and maximum values provided in the data set for the column.
preference string[ ] For columns whose type is categorical, a preferred subset of the strings in the column's range; valid only for categorical columns. The order of the values is important because it indicates the actual preference for the values in range:
  • 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 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 whose is_objective field is true.
significant_loss number 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 whose is_objective field is true.
insignificant_loss number 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 whose is_objective field is true.
format string For columns whose type is numeric or datetime, an optional pattern that indicates how the value is to be presented by the visualization. For numeric columns:
  • Number of decimal places: "format": "number: n"
  • Currency symbol and number of decimal places: "format": "currency: 'symbol' : n"
  • Prefix: "format": "taPrefix: 'symbol'"
  • Suffix: "format": "taSuffix: 'symbol'"
  • Combinations: "format": "number: n | taSuffix: 'symbol'"
For datetime columns:
  • Date: "format": "date: 'MMM dd, yyyy'"
  • Time: "format": "date: 'h:m:s a'"
  • Date and time: "format": "date: 'MMM dd, yyyy h:m:s a'"
For more information about number, currency, and date formatter patterns, see the descriptions of the corresponding filter components in the AngularJS documentation. Used only by the Tradeoff Analytics widget; not part of the problem definition.
full_name string A descriptive name for the column. Used only by the Tradeoff Analytics widget; not part of the problem definition.
description string A long description for the column. Used only by the Tradeoff Analytics widget; not part of the problem definition.
Option
Name Description
key string An identifier for the option. The key must be unique among all options for the decision problem.
values {string: number | string, ...} A map of key-value pairs that specifies a value for each column (objective) of the decision problem in the format "values": { "key1": value1, "key2": value2 }. Value requirements vary by column type; 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.
name string The name of the option. Used only by the Tradeoff Analytics widget; not part of the problem definition.
description_html string A description of the option in HTML format. The description is displayed when the user selects the option in the interface. Used only by the Tradeoff Analytics widget; not part of the problem definition.
app_data {string: string, ...} 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. Used only by the Tradeoff Analytics widget; not part of the problem definition.
CategoricalRange
Name Description
string[ ] The values in the range. By default, values are preferred in the order in which you list them. 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. Use the preference field to list a subset of the elements in the range in their preferred order.
Example:   "range": [ "string", "string", ... ]
DateRange
Name Description
low string The low end of the range in full ISO 8601 format.
high string The high end of the range in full ISO 8601 format.
Example:   "range": { "low": "string", "high": "string" }
ValueRange
Name Description
low number The low end of the range.
high number The high end of the range.
Example:   "range": { "low": number, "high": number }
Parameter Description
problem object A Java Problem object that specifies the objectives (columns) and options for the decision problem.
generateVisualization boolean Indicates whether to calculate the map visualization for the results. If true (the default), the visualization is returned if 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.
Java Problem object
Parameter Description
subject string A name for the decision problem. The field typically provides a heading for the column that represents the options in the tabular representation of the data. Can also be specified by methods of the Java Problem class.
columns List A List of Java Column objects that lists the objectives for the decision problem. The field typically specifies the columns for the tabular representation of the data. Specified by methods of the Java Problem class.
options List A List of Java Option objects that lists the options for the decision problem. The field typically specifies the rows for the tabular representation of the data. Specified by methods of the Java Problem class.
Constructors:
Java Column object
Name Description
key string An identifier for the column. The key must be unique among all columns for the decision problem. Specified by methods of the Java Column class.
type string The type of the column's values:
  • ColumnType.NUMERIC columns accept number values (integers or doubles). Instantiated with the constructor for the Java NumericColumn class.
  • ColumnType.DATE columns accept date and time values in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD). Instantiated with the constructor for the Java DateColumn class.
  • ColumnType.CATEGORICAL columns accepts string values specified by using the range field. Instantiated with the constructor for the Java CategoricalColumn class.
  • ColumnType.TEXT (the default) columns accept strings. Instantiated with the constructor for the Java TextColumn class.
goal string The direction of the column:
  • Goal.MIN indicates that the goal is to minimize the objective (for example, the price of a vehicle).
  • Goal.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 objective is true. Specified by methods of the Java Column class.
objective boolean Indicates whether the column is an objective for the decision problem. If true, the column contributes to the resolution; if false (the default), the column does not contribute to the resolution. The value cannot be set to true for a column of type TEXT. If generateVisualization is true, objective must be true for a minimum of three columns and a maximum of 10 columns. Specified by methods of the Java Column class.
range varies Indicates the range of valid values for a CATEGORICAL, DATE, or NUMERIC column:
  • For CATEGORICAL columns, a List of strings that specifies the values in the range. By default, values are preferred in the order in which you list them. The column's goal indicates the order of preference. If goal is MIN, elements in the low position (at the front) of the list are preferred; if goal is MAX, elements in the high position are preferred. Use the column's preference to list a subset of the elements in the range in their preferred order. Specified by methods of the Java CategoricalColumn class.
  • For DATE columns, a pair of strings that indicate the low and high ends of the range in full ISO 8601 format. Specified by a method of the Java DateColumn class.
  • For NUMERIC columns, a pair of integers or doubles that indicate the low and high ends of the range. Specified by methods of the Java NumericColumn class.
An option whose value is outside of the specified range is marked as INCOMPLETE and is excluded from the resolution. By default, the range is calculated from the minimum and maximum values provided in the data set for the column.
preference List For columns whose type is CATEGORICAL, a List that indicates the preferred subset of the strings in the column's range; valid only for CATEGORICAL columns. The order of the values is important because it indicates the actual preference for the values in range:
  • If goal is MIN, elements in the low position (at the front) of the list are favored over later elements.
  • If goal is MAX, elements in the high position of the list are favored.
Specified by a method of the Java CategoricalColumn class. By default, values are preferred according to their ordering in range and the direction indicated by goal.
significantGain number 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 value is relevant only for columns for which objective is true. Specified by methods of the Java Column class.
significantLoss number 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 value is relevant only for columns for which objective is true. Specified by methods of the Java Column class.
insignificantLoss number 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 value is relevant only for columns for which objective is true. Specified by methods of the Java Column class.
format string For columns whose type is NUMERIC or DATE, an optional pattern that indicates how the value is to be presented by the visualization.

For NUMERIC columns:
  • Number of decimal places: "format": "number: n"
  • Currency symbol and number of decimal places: "format": "currency: 'symbol' : n"
  • Prefix: "format": "taPrefix: 'symbol'"
  • Suffix: "format": "taSuffix: 'symbol'"
  • Combinations: "format": "number: n | taSuffix: 'symbol'"
For DATE columns:
  • Date: "format": "date: 'MMM dd, yyyy'"
  • Time: "format": "date: 'h:m:s a'"
  • Date and time: "format": "date: 'MMM dd, yyyy h:m:s a'"
For more information about number, currency, and date formatter patterns, see the descriptions of the corresponding filter components in the AngularJS documentation. Specified by a method of the Java Column class.Used only by the Tradeoff Analytics widget; not part of the problem definition.
fullName string A descriptive name for the column. Specified by methods of the Java Column class. Used only by the Tradeoff Analytics widget; not part of the problem definition.
description string A long description for the column. Specified by a method of the Java Column class. Used only by the Tradeoff Analytics widget; not part of the problem definition.
Constructors:
Java Option object
Name Description
key string An identifier for the option. The key must be unique among all options for the decision problem. Can also be specified by methods of the Java Option class.
name string The name of the option. Can also be specified by methods of the Java Option class. Used only by the Tradeoff Analytics widget; not part of the problem definition.
values HashMap A HashMap of key-value pairs that specifies a value for each column (objective) of the decision problem. Value requirements vary by column type; a value must be of the type defined for its column. An option that fails to specify a value for a column for which objective is true is marked as INCOMPLETE and is excluded from the resolution. Can also be specified by methods of the Java Option class.
descriptionHtml string A description of the option in HTML format. The description is displayed when the user selects the option in the interface. Can also be specified by methods of the Java Option class. Used only by the Tradeoff Analytics widget; not part of the problem definition.
appData HashMap A HashMap of key-value pairs in which the application can pass application-specific information. The service carries the information but does not use it. Specified by methods of the Java Option class.Used only by the Tradeoff Analytics widget; not part of the problem definition.
Constructors:
  • Option()
  • Option(String key, String name)
  • Option(String key, String name, HashMap<String,Object> values, String descriptionHtml)

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data @problem.json
"https://gateway.watsonplatform.net/tradeoff-analytics/api/v1/dilemmas?generate_visualization=false"

var TradeoffAnalyticsV1 = require('watson-developer-cloud/tradeoff-analytics/v1');
var tradeoff_analytics = new TradeoffAnalyticsV1({
  username: '{username}',
  password: '{password}'
});

var params = require('problem.json');

tradeoff_analytics.dilemmas(params, function(error, resolution) {
  if (error)
    console.log('Error:', error)
  else
    console.log(JSON.stringify(resolution, null, 2));
});

TradeoffAnalytics service = new TradeoffAnalytics();
service.setUsernameAndPassword("{username}", "{password}");

String price = "price";
String weight = "weight";
String brand = "brand";
String rDate = "rDate";

String apple = "Apple";
String htc = "HTC";
String samsung = "Samsung";
String sony = "Sony";

List<String> categories = new ArrayList<String>();
categories.add(apple);
categories.add(htc);
categories.add(samsung);
categories.add(sony);

List<String> preferences = new ArrayList<String>();
preferences.add(samsung);
preferences.add(apple);
preferences.add(htc);

Problem problem = new Problem("phones");

// Define the objectives.
List<Column> columns = new ArrayList<Column>();
problem.setColumns(columns);

NumericColumn priceColumn = new NumericColumn();
priceColumn.setKey(price);
priceColumn.setGoal(Goal.MIN);
priceColumn.setObjective(true);
priceColumn.range(0, 400);
priceColumn.setFullName("Price");
priceColumn.setFormat("number:2");
columns.add(priceColumn);

NumericColumn weightColumn = new NumericColumn();
weightColumn.setKey(weight);
weightColumn.setGoal(Goal.MIN);
weightColumn.setObjective(true);
weightColumn.setFullName("Weight");
weightColumn.setFormat("number:0");
columns.add(weightColumn);

CategoricalColumn brandColumn = new CategoricalColumn();
brandColumn.setKey(brand);
brandColumn.setGoal(Goal.MIN);
brandColumn.setObjective(true);
brandColumn.setRange(categories);
brandColumn.setPreference(preferences);
brandColumn.setFullName("Brand");
columns.add(brandColumn);

DateColumn rDateColumn = new DateColumn();
rDateColumn.setKey(rDate);
rDateColumn.setGoal(Goal.MIN);
rDateColumn.setObjective(true);
rDateColumn.setFullName("Release Date");
rDateColumn.setFormat("date: 'MMM dd, yyyy'");
columns.add(rDateColumn);

// Define the options.
List<Option> options = new ArrayList<Option>();
problem.setOptions(options);

HashMap<String, Object> galaxyS4Specs = new HashMap<String, Object>();
galaxyS4Specs.put(price, 249);
galaxyS4Specs.put(weight, 130);
galaxyS4Specs.put(brand, samsung);
galaxyS4Specs.put(rDate, "2013-04-29T00:00:00Z");
options.add(new Option("1", "Galaxy S4").values(galaxyS4Specs));

HashMap<String, Object> iphone5Specs = new HashMap<String, Object>();
iphone5Specs.put(price, 349);
iphone5Specs.put(weight, 112);
iphone5Specs.put(brand, apple);
iphone5Specs.put(rDate, "2012-09-21T00:00:00Z");
options.add(new Option("2", "iPhone 5").values(iphone5Specs));

HashMap<String, Object> oneSpecs = new HashMap<String, Object>();
oneSpecs.put(price, 299);
oneSpecs.put(weight, 112);
oneSpecs.put(brand, htc);
opneSpecs.put(rDate, "2013-03-01T00:00:00Z");
options.add(new Option("3", "One").values(oneSpecs));

HashMap<String, Object> galaxyS5Specs = new HashMap<String, Object>();
galaxyS5Specs.put(price, 349);
galaxyS5Specs.put(weight, 135);
galaxyS5Specs.put(brand, samsung);
galaxyS5Specs.put(rDate, "2014-04-29T00:00:00Z");
options.add(new Option("4", "Galaxy S5").values(galaxyS5Specs));

HashMap<String, Object> iphone6Specs = new HashMap<String, Object>();
iphone6Specs.put(price, 399);
iphone6Specs.put(weight, 118);
iphone6Specs.put(brand, apple);
iphone6Specs.put(rDate, "2013-09-21T00:00:00Z");
options.add(new Option("5", "iPhone 6").values(iphone6Specs));

HashMap<String, Object> iphone7Specs = new HashMap<String, Object>();
iphone7Specs.put(price, 499);
iphone7Specs.put(weight, 118);
iphone7Specs.put(brand, apple);
iphone7Specs.put(rDate, "2014-09-21T00:00:00Z");
options.add(new Option("6", "iPhone 7").values(iphone7Specs));

HashMap<String, Object> xperiaSpecs = new HashMap<String, Object>();
xperiaSpecs.put(price, 199);
xperiaSpecs.put(weight, 120);
xperiaSpecs.put(brand, sony);
xperiaSpecs.put(rDate, "2014-08-21T00:00:00Z");
options.add(new Option("7", "Xperia").values(xperiaSpecs));

// Call the service and get the problem resolution
Dilemma dilemma = service.dilemmas(problem, false).execute();
System.out.println(dilemma);

tradeoff_analytics = TradeoffAnalyticsV1(
  username='{username}',
  password='{password}')

with open(os.path.join(os.path.dirname(__file__), 'problem.json')) as problem_json:
  dilemma = tradeoff_analytics.dilemmas(json.load(problem_json),
                                        generate_visualization=False)

print(json.dumps(dilemma, indent=2))

Response

The ordering of the fields in the JSON output might differ from the example response. The contents are equivalent to the results returned by the REST interface.

Dilemma
Name Description
problem object The Problem object problem (columns and options) Java Problem object that was submitted in the call to the dilemmas method.
resolution object A Resolution object that provides the resolution of the decision problem.
Resolution
Name Description
solutions object[ ] An array of Solution objects that contains the analytical data prepared by the service for each option of the decision problem.
map object A Map object that provides the two-dimensional positioning of each option on the map polygon displayed by the Tradeoff Analytics visualization. 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 in the call to the dilemmas method, and more than one option has a status of FRONT in the problem resolution.
Solution
Name Description
solution_ref string The key that uniquely identifies the option in the decision problem.
status string 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 one or more options are 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 its column values lies outside of the range specified for the column. Only a column whose is_objective field is true can generate this status.
  • DOES_NOT_MEET_PREFERENCE indicates that the option specifies a value for a categorical column that is not included in the column's preferences.
excluded_by object[ ] 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.
status_cause object 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.
shadows string[ ] A list of references to the keys of solutions that are shadowed by this solution.
shadow_me string[ ] A list of references to the keys of solutions that shadow this solution.
ExcludedBy
Name Description
solution_ref string The key that uniquely identifies the option that was strictly better than the current option.
objectives object[ ] An array of Objective objects that describes each value of the superior option that was strictly better than the current option.
Objectives
Name Description
key string 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 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 For categorical columns, a description of the difference between the two values as a preference; for example, Prefer category_one over category_two. For datetime columns, a description of the difference between the two values as a number of days, hours, and minutes, as needed; for example, 350 days or 225 days 21 hours 30 minutes.
StatusCause
Name Description
message string A description in English of the cause for the option's status.
tokens string[ ] Elements of the message field that describes the cause for the option's status.
error_code string 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.
Map
Name Description
anchor object[ ] An array of Anchor objects that represent the vertices for the objectives and their positions on the map visualization.
nodes object[ ] 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. The structure of an array element is {"coordinates": {"x": 0, "y": 0}, "solution_refs": ["key1", "key3"]}, where coordinates describe the position on the map visualization of options identified by the keys in solution_refs.
Anchor
Name Description
name string The name of the anchor point.
position object[ ] An array of MapNodeCoordinates objects that provides the positions of the anchors on the map visualization.
MapNode
Name Description
coordinates object An array of MapNodeCoordinates objects that provides the positions of a cell on the map visualization.
solution_refs string[ ] References to solutions (the keys for options) that are positioned on this cell.
MapNodeCoordinates
Name Description
x number An X-axis coordinate on the map visualization.
y number A Y-axis coordinate on the map visualization.

Example response


{
  "problem": {
    "columns": [
      {
        "type": "numeric",
        "key": "price",
        "full_name": "Price",
        "range": {
          "low": 0,
          "high": 400
        },
        "format": "number:2",
        "goal": "min",
        "is_objective": true
      },
      {
        "type": "numeric",
        "key": "weight",
        "full_name": "Weight",
        "format": "number:0",
        "goal": "min",
        "is_objective": true
      },
      {
        "type": "categorical",
        "key": "brand",
        "full_name": "Brand",
        "range": [
          "Apple",
          "HTC",
          "Samsung",
          "Sony"
        ],
        "goal": "min",
        "preference": [
          "Samsung",
          "Apple",
          "HTC"
        ],
        "is_objective": true
      },
      {
        "type": "datetime",
        "key": "rDate",
        "full_name": "Release Date",
        "format": "date: 'MMM dd, yyyy'",
        "goal": "max",
        "is_objective": false
      }
    ],
    "subject": "phones",
    "options": [
      {
        "key": "1",
        "name": "Samsung Galaxy S4",
        "values": {
          "price": 249,
          "weight": 130,
          "brand": "Samsung",
          "rDate": "2013-04-29T00:00:00Z"
        }
      },
      {
        "key": "2",
        "name": "Apple iPhone 5",
        "values": {
          "price": 349,
          "weight": 112,
          "brand": "Apple",
          "rDate": "2012-09-21T00:00:00Z"
        }
      },
      {
        "key": "3",
        "name": "HTC One",
        "values": {
          "price": 299,
          "weight": 112,
          "brand": "HTC",
          "rDate": "2013-03-01T00:00:00Z"
        }
      },
      {
        "key": "4",
        "name": "Samsung Galaxy S5",
        "values": {
          "price": 349,
          "weight": 135,
          "brand": "Samsung",
          "rDate": "2014-04-29T00:00:00Z"
        }
      },
      {
        "key": "5",
        "name": "Apple iPhone 6",
        "values": {
          "price": 399,
          "weight": 118,
          "brand": "Apple",
          "rDate": "2013-09-21T00:00:00Z"
        }
      },
      {
        "key": "6",
        "name": "Apple iPhone 7",
        "values": {
          "price": 499,
          "weight": 118,
          "brand": "Apple",
          "rDate": "2014-09-21T00:00:00Z"
        }
      },
      {
        "key": "7",
        "name": "Sony Xperia",
        "values": {
          "price": 199,
          "weight": 120,
          "brand": "Sony",
          "rDate": "2014-08-21T00:00:00Z"
        }
      }
    ]
  },
  "resolution": {
    "solutions": [
      {
        "solution_ref": "1",
        "status": "FRONT"
      },
      {
        "solution_ref": "2",
        "status": "FRONT"
      },
      {
        "solution_ref": "3",
        "status": "FRONT"
      },
      {
        "solution_ref": "4",
        "status": "EXCLUDED",
        "excluded_by": [
          {
            "solution_ref": "1",
            "objectives": [
              {
                "key": "price",
                "difference": 100
              },
              {
                "key": "weight",
                "difference": 5
              }
            ]
          }
        ]
      },
      {
        "solution_ref": "5",
        "status": "EXCLUDED",
        "excluded_by": [
          {
            "solution_ref": "2",
            "objectives": [
              {
                "key": "price",
                "difference": 50
              },
              {
                "key": "weight",
                "difference": 6
              }
            ]
          }
        ]
      },
      {
        "solution_ref": "6",
        "status": "INCOMPLETE",
        "status_cause": {
          "message": "A column of a option is out of range. Option \"6\" has a value in column \"price\" which is:\"499\" while the column range \"is: [0.0,400.0]\"",
          "error_code": "RANGE_MISMATCH",
          "tokens": [
            "price",
            "499",
            "[0.0,400.0]"
          ]
        }
      },
      {
        "solution_ref": "7",
        "status": "DOES_NOT_MEET_PREFERENCE",
        "status_cause": {
          "message": "Option \"7\" has a value that does not meet preference for column \"brand\"",
          "error_code": "DOES_NOT_MEET_PREFERENCE",
          "tokens": [
            "brand"
          ]
        }
      }
    ]
  }
}

{
  "problem": {
    "columns": [
      {
        "type": "numeric",
        "key": "price",
        "full_name": "Price",
        "range": {
          "low": 0,
          "high": 400
        },
        "format": "number:2",
        "goal": "min",
        "is_objective": true
      },
      {
        "type": "numeric",
        "key": "weight",
        "full_name": "Weight",
        "format": "number:0",
        "goal": "min",
        "is_objective": true
      },
      {
        "type": "categorical",
        "key": "brand",
        "full_name": "Brand",
        "range": [
          "Apple",
          "HTC",
          "Samsung",
          "Sony"
        ],
        "goal": "min",
        "preference": [
          "Samsung",
          "Apple",
          "HTC"
        ],
        "is_objective": true
      },
      {
        "type": "datetime",
        "key": "rDate",
        "full_name": "Release Date",
        "format": "date: 'MMM dd, yyyy'",
        "goal": "max",
        "is_objective": false
      }
    ],
    "subject": "phones",
    "options": [
      {
        "key": "1",
        "name": "Samsung Galaxy S4",
        "values": {
          "price": 249,
          "weight": 130,
          "brand": "Samsung",
          "rDate": "2013-04-29T00:00:00Z"
        }
      },
      {
        "key": "2",
        "name": "Apple iPhone 5",
        "values": {
          "price": 349,
          "weight": 112,
          "brand": "Apple",
          "rDate": "2012-09-21T00:00:00Z"
        }
      },
      {
        "key": "3",
        "name": "HTC One",
        "values": {
          "price": 299,
          "weight": 112,
          "brand": "HTC",
          "rDate": "2013-03-01T00:00:00Z"
        }
      },
      {
        "key": "4",
        "name": "Samsung Galaxy S5",
        "values": {
          "price": 349,
          "weight": 135,
          "brand": "Samsung",
          "rDate": "2014-04-29T00:00:00Z"
        }
      },
      {
        "key": "5",
        "name": "Apple iPhone 6",
        "values": {
          "price": 399,
          "weight": 118,
          "brand": "Apple",
          "rDate": "2013-09-21T00:00:00Z"
        }
      },
      {
        "key": "6",
        "name": "Apple iPhone 7",
        "values": {
          "price": 499,
          "weight": 118,
          "brand": "Apple",
          "rDate": "2014-09-21T00:00:00Z"
        }
      },
      {
        "key": "7",
        "name": "Sony Xperia",
        "values": {
          "price": 199,
          "weight": 120,
          "brand": "Sony",
          "rDate": "2014-08-21T00:00:00Z"
        }
      }
    ]
  },
  "resolution": {
    "solutions": [
      {
        "solution_ref": "1",
        "status": "FRONT"
      },
      {
        "solution_ref": "2",
        "status": "FRONT"
      },
      {
        "solution_ref": "3",
        "status": "FRONT"
      },
      {
        "solution_ref": "4",
        "status": "EXCLUDED"
      },
      {
        "solution_ref": "5",
        "status": "EXCLUDED"
      },
      {
        "solution_ref": "6",
        "status": "INCOMPLETE",
        "status_cause": {
          "message": "A column of a option is out of range. Option \"6\" has a value in column \"price\" which is:\"499\" while the column range \"is: [0.0,400.0]\"",
          "error_code": "RANGE_MISMATCH",
          "tokens": [
            "price",
            "499",
            "[0.0,400.0]"
          ]
        }
      },
      {
        "solution_ref": "7",
        "status": "DOES_NOT_MEET_PREFERENCE",
        "status_cause": {
          "message": "Option \"7\" has a value that does not meet preference for column \"brand\"",
          "error_code": "DOES_NOT_MEET_PREFERENCE",
          "tokens": [
            "brand"
          ]
        }
      }
    ]
  }
}