Sentiment analysis engines

A sentiment analysis engine classifies text according to sentiment or emotion, which may be a score representing a negative, positive, or neutral sentiment, or could include a wider breadth of tags like "happy" or "excited".

Engine input

Sentiment analysis engines can specify supportedInputFormats in their manifest for mime types they can support natively (e.g. text/plain, application/pdf). In this case, engines are given the entire file as their input and are responsible for outputting the sentiment analysis results for the entire file in their .aion output.

Engine output

Sentiment analysis engine output can express multiple values depending on the format of the data being analyzed and the depth and detail of the insights the engine can express.

See the sentiment validation contract json-schema.

Positive values Positive values express the strength of positive sentiments from 0.0 (neutral: "I woke up") to 1.0 (extreme: "The joy of waking up is the most supremely happy feeling!"), and positive confidence is the confidence that the positive value is accurate. Lower confidence can indicate uncertainty or sarcasm ("I'm so ... happy to be awake.") or indeterminate interpretation. ("That sandwich was sick!")

Negative values Negative values express the strength of negative sentiments from 0.0 (neutral: "I ate dinner") to 1.0 (extreme: "I ate the most foul, disgusting slop that was ever unfortunate enough to touch a plate"), and the negative confidence is the confidence that the negative value is accurate.

Mixed sentiments Text can also have mixed sentiments. For example, "Although the Daytona hotel was the best I'd stayed at, it still had a lot of problems and I wouldn't recommend it" or "Though his prowess exceeded that of any other man, sadly he was defeated in the end." This may be indicated by both positive and negative values being present.

When both values are present, their values are independent of one another. (That is, they don't have to add up to 1.0.) A positive value of 0.6 with a negative value of 0.1 simply means that the document or phrase was significantly positive with a slight negative tone ("Even though I didn't want to, I found myself thoroughly enjoying the experience.") and a positive value of 0.1 with a negative value of 0.6 means that the document or phrase was significantly negative with a slight positive tone ("Everything about the experience was poor, except for one enjoyable moment.")

You must provide at least one value, positive or negative. Missing values default to 0.0 (neutral). Confidences are always optional and default to 1.0 if not specified.

Example 1: Simple output

The simplest possible sentiment output reports a single positive or negative sentiment value for the entire document. A positive analysis reports like this:

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "positiveValue": 0.56
  }
}

And a negative analysis would be reported like this:

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "negativeValue": 0.17
  }
}

Example 2: Richer output

To report complex sentiments or emotions, additional fields are available.

• sentiment: Used for a general positive/negative emotion. It can have both positive and negative values and separate confidences for each.
• emotions: You can express as many different emotions as you want, each with its own values and confidences. The value of the emotion field can include any descriptor you want.

[Note] This example shows an engine output with both sentiment and emotions. This is a supported configuration, however, we recommend using one output format or the other.

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "positiveValue": 0.56,
    "positiveConfidence": 0.8,
    "negativeValue": 0.2,
    "negativeConfidence": 0.5
  },

  "emotions": [
    {
      "emotion": "excited",
      "emotionValue": 0.14,
      "emotionConfidence": 0.88
    },
    {
      "emotion": "confused",
      "emotionValue": 0.82,
      "emotionConfidence": 0.75
    },
    {
      "emotion": "🤯",
      "emotionValue": 1,
      "emotionConfidence": 1
    }
  ]
}

[Note] There aren't any current engine providers expressing emotions as emojis (such as 🤯), but they are supported as valid utf-8 characters. Their use above does show that these emotion codes don't need to conform to an aiWARE-managed list and can be anything the engine developer wishes.

Example 3: Per-phrase reporting

Both sentiment and emotions can be reported at a per-phrase resolution by putting them within a text object and optionally referencing the page, paragraph, and/or sentence index where they occur.

{
  "validationContracts": ["sentiment"],
  "object": [
    {
      "type": "text",
      "text": "I'm feeling mostly good but a little bad I think, with just a twitch of anger; but mostly I'm confused.",
      "page": 3,
      "paragraph": 2,
      "sentence": 4,

      "sentiment": {
        "positiveValue": 0.56,
        "positiveConfidence": 0.8,
        "negativeValue": 0.2,
        "negativeConfidence": 0.5
      },

      "emotions": [
        {
          "emotion": "excited",
          "emotionValue": 0.14,
          "emotionConfidence": 0.88
        },
        {
          "emotion": "confused",
          "emotionValue": 0.82,
          "emotionConfidence": 0.75
        }
      ]
    }
  ]
}

Example 4: Polarized

A common output of standalone "sentiment analysis" engines is to report a single sentiment value of "positive," "negative," or "neutral" with a single confidence value. In .aion format, those are expressed by mapping the polarization score to the appropriate value.

Example with error range

If the sentiment analysis reports a 56% ±3% positive score, then the positive value is 0.56 and the uncertainty is the ratio of the error value to the score: 0.03/0.56 = 0.0535714. Subtract this from 1.0 to convert the "uncertainty" to "confidence".

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "positiveValue": 0.56,
    "positiveConfidence": 0.9464286
  }
}

Example from a single-value scale

If the sentiment analysis reports the sentiment as a single value in a range, for example from -1.0 (negative) to 1.0 (positive), then divide the range into two portions and map to the appropriate positive or negative value.

For example, if the engine reports on a scale of 0.0 (negative) to 1.0 (positive) with 0.5 being neutral, and the output is 0.46 then the positiveValue is 0.0 (or just left undefined) and the negativeValue is calculated as follows:

• Invert the strength from high meaning neutral 0.5 -> 0.0 to low meaning neutral 0.0 -> 0.5: 0.5 - 0.46 = 0.04.
• Change the scale from 0.0 -> 0.5 to 0.0 -> 1.0: 0.04 * 2 = 0.08.

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "positiveValue": 0,
    "negativeValue": 0.08
  }
}

Example of a neutral value

If the sentiment analysis reports "neutral sentiment", set both positive and negative values to 0.0:

{
  "validationContracts": ["sentiment"],
  "sentiment": {
    "positiveValue": 0,
    "negativeValue": 0
  }
}