Output: Understanding a problem resolution

When you submit a decision problem to the Tradeoff Analytics service, the service returns its results as a JSON Dilemma object that includes both the original Problem and its Resolution. The following Unified Modeling Language (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 Description
problem

Required
Problem The Problem object submitted in the call to the dilemmas method of the service. For more information, see Input: Submitting a decision problem.
resolution

Required
Resolution The resolution of the decision problem sent to the service. For more information, see The Resolution object.

To see the Resolution object that the service returns for the problem.json file described in Input: Specifying a decision problem, see Example solutions, Example preferable solutions, and Example map visualization.

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 Description
solutions

Required
Solution[ ] 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.
preferable_solutions

Optional
PreferableSolutions A PreferableSolutions object that usually identifies no more than five of the best candidate solutions that are likely to satisfy the greatest number of users. The resolution includes this field only if the query parameter find_preferable_options is true. For more information, see The PreferableSolutions object.
map

Optional
Map 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 Description
solution_ref

Required
String The key that uniquely identifies the option in the decision problem.
status

Required
String =
 "FRONT" |
 "EXCLUDED" |
 "INCOMPLETE" |
 "DOES_NOT_MEET_PREFERENCE"
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

Optional
ExcludedBy[ ] 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

Optional
StatusCause 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

Optional
String[ ] An array of references to the keys of solutions that are shadowed by this solution.
shadow_me

Optional
String[ ] 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 Description
solution_ref

Required
String The key that uniquely identifies the option that was strictly better than the current option.
objectives

Required
Objective[ ] An array of Objective objects that describes each value of the superior option that was better than the current option.

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

Fields of the Objective object
Field Type Description
key

Required
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

Required
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

Optional
String 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 Description
message

Required
String A description in English of the cause for the option's status.
tokens

Required
String[ ] An array of values used to describe the cause for the option's status. The strings appear in the message field.
error_code

Required
String =
 "MISSING_OBJECTIVE_VALUE" |
 "RANGE_MISMATCH" |
 "DOES_NOT_MEET_PREFERENCE"
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.

Example solutions

The service returns a JSON Dilemma object that includes a Problem object that duplicates the decision problem exactly as it was submitted by the problem.json file. The Problem object includes the subject field and the Columns and Options objects in their entirety. For a complete description of the contents of the file, see Example objectives and Example options.

The Dilemma object then includes a Resolution object that provides the results of the service's evaluation of the seven phones defined by the decision problem. The solutions field provides an array of Solution objects with results for each option. For each element of the array, the solution_ref field identifies the key of an option, and the status field indicates the option's disposition in the resolution:

  • The first three options have a status of FRONT to indicate that they are among the best candidates.

  • The next two options have a status of EXCLUDED. This means that one or more clearly superior choices exist for each option. For both options, the output includes an excluded_by field that lists the superior option and describes the values of that option that were better than those of the option in question. The field is an array that can list multiple superior options if the service finds more than one.

  • Option 6 has a status of INCOMPLETE. The status_cause field indicates that the option has a RANGE_MISMATCH with the price column: Its price exceeds the maximum range of that objective.

  • Option 7 has a status of DOES_NOT_MEET_PREFERENCE. The status_cause field indicates that the option has a value (Sony) that is not included among the preferred list of brands.

{
  "problem": {
    "columns": [
      . . .
    ],
    "subject": "phones",
    "options": [
      . . .
    ]
  },
  "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"
          ]
        }
      }
    ]
  }
}

For examples of the preferred solutions and the map visualization that the service can return, see Example preferable solutions and Example map visualization.

The PreferableSolutions object

The PreferableSolutions object identifies the subset of best candidates that are likely to satisfy the greatest number of users. The reduced list of preferred solutions can make it easier to select the best possible candidate. The Resolution object includes the PreferableSolutions object only if the query parameter find_preferable_options is true. The following table describes the fields of the object.

Fields of the PreferableSolutions object
Field Type Description
solution_refs

Required
String[ ] An array of keys that identifies the subset of preferred solutions from among the best candidates of the decision problem. The service selects the subset from the solutions that have a status of FRONT.
score

Required
Number A confidence score that indicates the percentage of users that the service believes will choose one of the preferred solutions as opposed to one of the other best candidates. The higher the percentage, the greater the service's confidence in its selections.

Example preferable solutions

If the service returns preferable solutions, the Resolution object includes the PreferableSolutions object. The following example shows the object that the service returns for the decision problem submitted by the problem.json file. This output continues the description of the service's response begun in Example solutions.

The response lists the keys for two of the problem's seven options, three of which were identified as best candidates with a status of FRONT. The response includes a score of 94 percent, indicating a high degree of confidence in the preferred solutions.

{
  "problem": {
    "columns": [
      . . .
    ],
    "subject": "phones",
    "options": [
      . . .
    ]
  },
  "resolution": {
    "solutions": [
      . . .
    ],
    "preferable_solutions": {
      "solution_refs": [
        "1",
        "2"
      ],
      "score": 0.94
    }
  }
}

The following three candidates have a status of FRONT:

Key Option Price (min) Weight (min) Brand (min)
1 Samsung Galaxy S4 249 130 Samsung
2 Apple iPhone 5 349 112 Apple
3 HTC One 299 112 HTC

None of the three is strictly better than the others: Option 1 has a lower price than the others, while options 2 and 3 have a lower weight than option 1. But the brand of option 1 is also the most preferred of those listed for the decision problem, giving it an edge over the other two options (in the map visualization, more of its glyph would be filled). But its higher weight compelled the service to consider additional solutions, and the service's algorithm chose option 2. The algorithm does not and cannot consider the meaning of the individual objectives, but its probabilistic model concluded that options 1 and 2 are most likely to satisfy the needs of a majority of users.

For an example of the map visualization that the service can return, see Example map visualization.

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 object only if all of the following are true:

  • The query parameter generate_visualization is true (the default value if the parameter is omitted).

  • 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 high-level fields of the Map object. Additional low-level fields of the object are not described. All of the object's fields are related to the placement of nodes and cells on the map visualization.

Tradeoff Analytics Map Object

The following table describes these fields of the Map object.

Fields of the Map object
Field Type Description
anchors

Required
Anchor[ ] An array of Anchor objects that represent the vertices for the objectives and their positions on the map visualization.
nodes

Required
MapNode[ ] 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.

Example map visualization

If the service generates the map visualization, the Resolution object includes the Map object. This object provides the parameters that are consumed by the Tradeoff Analytics client widget to display the visualization. Its fields have meaning only for the widget; you do not need to understand them to use the visualization interface. The following example shows the object that the service returns for the decision problem submitted by the problem.json file. This completes the description of the service's response from Example solutions and Example preferable solutions.

{
  "problem": {
    "columns": [
      . . .
    ],
    "subject": "phones",
    "options": [
      . . .
    ]
  },
  "resolution": {
    "solutions": [
      . . .
    ],
    "map": {
      "nodes": [
        {
          "coordinates": {
            "x": 3,
            "y": 0
          },
          "solution_refs": [
            "1"
          ]
        },
        {
          "coordinates": {
            "x": 2,
            "y": 3.4641016151378
          },
          "solution_refs": [
            "3"
          ]
        },
        {
          "coordinates": {
            "x": 4,
            "y": 3.4641016151378
          },
          "solution_refs": [
            "2"
          ]
        }
      ],
      "anchors": [
        {
          "name": "price",
          "position": {
            "x": 0,
            "y": 0
          }
        },
        {
          "name": "weight",
          "position": {
            "x": 3,
            "y": 5.1961524227066
          }
        },
        {
          "name": "brand",
          "position": {
            "x": 6,
            "y": 0
          }
        }
      ],
      "version": "APIV1-ANN",
      "config": {
        "params": {
          "rInit": 4.8151012450415,
          "rFinish": 1,
          "seed": 20008,
          "rAnchor": 1.5,
          "alpha_init": 0.75,
          "map_size": 27,
          "training_period": 100,
          "anchor_epoch": 3
        },
        "drivers": {
          "r_fin": 1,
          "r_init": 1.2,
          "r_anchor_init": 1.8,
          "training_length": 100,
          "max_map_size": 200,
          "alpha_init": 0.75,
          "training_anchors": 1,
          "data_multiplier": 9
        }
      },
      "metrics": {
        "mqe": "NaN",
        "tau": "NaN",
        "somers": "NaN",
        "kappa": 1,
        "kappa_delta": "NaN",
        "weighted_kappa": "NaN",
        "final_kappa": 1
      }
    }
  }
}