How to interpret results

Before you start

This article helps you interpret the result returned by the PREDICT, MATCH, SEARCH, and GENERIC QUERY API.

The examples in this article use the dataset of our grocery store demo app. The data model is presented below:

We have created an instance already populated with the data. The credentials of the instance are as follows:

• Instance URL: https://aito-grocery-store.api.aito.ai
• API key: bc4Ck3nDwM1ILVjNahNJL8hPEAzCes8t2vGMUyo9

You can take a look at our get started articles for platform specific instruction on how to run a query.

Let's begin!

The structure of the returned result

The PREDICT, MATCH, SEARCH and GENERIC QUERY results would look similar to:

{
  "offset": 0,
  "total": 10,
  "hits": [
    {...},
    ...
  ]
}

• offset: corresponds to the offset in the query, defaults to 0 if offset was not specified
• total: corresponds to the limit in the query, defaults to 10 in SEARCH query if limit was not specified and defaults to the number of predictions in inference query
• hits: An array of the returned results. The hits can be the entries of a table in a SEARCH query or the predictions in inference query such as PREDICT or MATCH. The hits are sorted by the order specified in the orderBy clause of the query. If orderBy was not specified, the hits are sorted by the ascending order of the index of the entries in SEARCH query or by the descending order of the probability in the inference query.

The returned hit

The hit of an query usually contains the following fields:

• $p: The probability of the prediction

• $value: The prediction

Understanding the explanation

For most queries, you can specify the $why to make Aito show the reasoning behind its returned result. In this section, we will learn how to interprete the returned explanation.

Explanation of the inference query

Let's take a look at a simple PREDICT query that predicts the most likely category for a product based on the name with the explanation enquiry $why.

{
  "from": "products",
  "where": {
    "name": "1st class Pirkka international banana"
  },
  "predict": "tags",
  "select": ["$p", "$value", "$why"]
}

The first returned hit (the highest probability one) would be:

{
  "$p": 0.2640443012464906,
  "$value": "pirkka",
  "$why": {
    "type": "product",
    "factors": [
      {
        "type": "baseP",
        "value": 0.234375,
        "proposition": {
          "tags": {
            "$has": "pirkka"
          }
        }
      },
      {
        "type": "product",
        "factors": [
          {
            "type": "normalizer",
            "name": "exclusiveness",
            "value": 0.2651089537482237
          },
          {
            "type": "normalizer",
            "name": "trueFalseExclusiveness",
            "value": 0.3280229907163439
          }
        ]
      },
      {
        "type": "relatedPropositionLift",
        "proposition": {
          "name": {
            "$has": "banana"
          }
        },
        "value": 1.2649746464232334
      },
      {
        "type": "relatedPropositionLift",
        "proposition": {
          "name": {
            "$has": "pirkka"
          }
        },
        "value": 2.8283229123079803
      },
      {
        "type": "relatedPropositionLift",
        "proposition": {
          "$and": [
            {
              "name": {
                "$has": "1st"
              }
            },
            {
              "name": {
                "$has": "class"
              }
            }
          ]
        },
        "value": 2.1484710040052364
      },
      {
        "type": "relatedPropositionLift",
        "proposition": {
          "name": {
            "$has": "intern"
          }
        },
        "value": 1.6853749097672814
      }
    ]
  }
}

Let's breakdown the different components of the explanation in $why:

• type: shows how the probability is calculated. In this case, it is the product of multiple factors.
• factors: a list of factors that contribute to the calculated probability. In this case, you can multiply the value of each factor to achieve the returned probability

  • baseP factor: This is the base probability or the prior probability of the predicting feature. This is derived from how often the feature appears in the sampling data

  • normalizer factors:

    • exclusiveness normalizer: appears when exclusiveness is specified as true in the predict query. This factor adjusts the probability between single-label and multi-label classification problem
    • trueFalseExclusiveness: Under the hood, Aito considers both scenarios to get the prediction: when the predicting feature is true (is in this case, P(tags == "pirkka")) and when the predicting feature is false (in this case, P(tags != pirkka)). This normalizer adjusts the probability so that P(tags == "pirkka") = 1 - P(tags != pirkka)

  • relatedPropositionLift factor: shows the impact of an evident proposition (which was defined in the where clause of the query) towards the predicting feature. For example:

    {
      "type": "relatedPropositionLift",
      "proposition": {
        "name": {
          "$has": "banana"
        }
      },
      "value": 1.2649746464232334
    }
    

    shows that when the product name has the word banana, it has a lift of approximately of 1.26. In other words, when the product name has the word banana, it increases the chance of the tags to be pirkka by roughly 26%

    NOTE: In some cases, the related proposition can be a combination of multiple propositions. This is because of Aito's concept learning feature. For instance, in the following related proposition:

    {
        "type": "relatedPropositionLift",
        "proposition": {
          "$and": [
            {
              "name": {
                "$has": "1st"
              }
            },
            {
              "name": {
                "$has": "class"
              }
            }
          ]
        },
        "value": 2.1484710040052364
      }
    

    instead of treating "name": {"$has": "1st"} and "name": {"$has": "class"} independently, Aito recognizes that these 2 features together have a high impact on the product's tag to be "pirkka". More information about concept learning can be found here. In the explanation, the combined proposition is presented in a machine readable format through the operators (in this case, it is the $and operator) so that you can use it to build a query. More information about explanation proposition can be found in our API docs.