How to interpret results
- Updated On 10 Aug 2020
- 4 Minutes To Read
-
Print
-
DarkLight
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 theoffset
in the query, defaults to 0 ifoffset
was not specifiedtotal
: corresponds to thelimit
in the query, defaults to 10 in SEARCH query iflimit
was not specified and defaults to the number of predictions in inference queryhits
: 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
This field will be replaced with $lift
if you use the $lifts instead of ordering the results by probability by default.
$value
: The prediction
In the PREDICT API, by default the returned hit contains field
which is the name of the predicing field and feature
which is similar to $value
. You can specify $value
in the select
clause of the query to make the $value
field appear in the returned hit.
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 thevalue
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 whenexclusiveness
is specified as true in the predict query. This factor adjusts the probability between single-label and multi-label classification problemtrueFalseExclusiveness
: 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 thewhere
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.
-