Monitor API Tutorial, Part 3: Basic Concepts

Owned by Fredrik Espinoza (Deactivated)
Last updated: Sept 14, 2017 by Nina Viereckel
4 min read

This is a basic tutorial series for using the Gavagai API v2.

Basic Concepts of Monitor API

To be able to use the Monitor API you need to familiarize yourself with some of the basic concepts of Monitor API. This will make it easier to understand what you can accomplish with the API. Once you understand the basics it will be easy to understand the API documentation which is the key to creating clients using the API.

Observers (also known as Targets)

Let's start by revisiting a concept that we introduced in an earlier part of the tutorial: the observer (AKA target). This is an important concept in Monitor API. It is at the focus of our interest and much of the information that is available through the API is tied to the observer. Think of an observer as you would think of the main character of a movie or the brand featured in a commercial. It could be a person, place, brand, or something more abstract like flu symptoms or the name of a country. You describe your target with a set of terms. For example, if your target is Obama your target terms would be "president obama", "barack obama", "obama", etc.

Mentions

So we are following a target. What happens then? The Monitor API system receives documents (blog entries, tweets, newspaper articles, and so on) that are published on the internet. Some of these are about our target of interest Obama and "Mentions" is a way of counting those documents. This is a pretty basic measurement but it still has an important place since it can give a general sense of how important a target is over time. It can also serve to normalize other values (more on this later).

Sentiment

What is the attitude towards Obama in a newspaper article written in the editorial section of a newspaper? What was the general opinion towards Obama in social media over the last month? This is sentiment, and it can be detected and measured by Monitor API. Every sentence in every article on every webpage that Monitor API receives is being analyzed for its sentiment. All of these values are then aggregated and processed in different ways depending on the type of the sentiment. Is the attitude positive or negative or does it indicate worry or fear? Monitor API can measure any type of sentiment and you get the results as time series aggregated in orderly blocks of hours, days, or months.

Associations

Sentiment measures the attitudes in texts. Associations show us what the texts are about. Associations are the terms that are most strongly associated with our target in the given set of texts. For Obama, some of the more usual associations are (of course) president, senate, committee, barack and so on. The more common an association is to a target the more stable it is considered by Monitor API. Associations which are not common over long periods of time, but rather pop up unexpectedly, perhaps as some event unfolds, or some significant piece of news is published, are called trending, in Monitor API. Trending associations are usually short lived and come and go. Stable associations can be a permanent part of a target (like "president" for Obama).

Sectors

Sectors group targets together for easy comparison. Sectors can include many different targets of the same language. Each target in a sector is represented by its own curve in a graph. Have a look at Gavagai Monitor for examples of sectors. Another feature of sectors is that they are able to display and analyze data defined by cross cutting aspects called "key subjects". These are described below.

Key Subjects

Key subject enable analysis of all the contained targets in a sector in regards to a certain aspect of the data. You can define aspects as you define targets: by specifying keywords and then, after getting related suggestions, supplementing your definition with more suggestions as appropriate. Key subjects are usually about cross cutting concerns: aspects of the data which would be relevant to each and every target in your sector and which would be useful to separate out to view separately. For example, if you fill a sector with political parties, your key subjects could be the issues that are discussed in your political arena, things that all the political parties are concerned with such as schooling, taxes, foreign affairs and so on. By defining these key subjects you could view only the relevant documents about all parties in regards to taxes for example. You can experiment with key subjects if you get a free account in Gavagai Monitor and then create a sector and install some key subjects in it. Or check out our example sector of political parties and their key subjects.

Concepts (a.k.a poles)

A "Concept" in the Gavagai systems is a model of a concept in a language. A concept could a feeling, an attitude, an abstract idea or anything else that can be expressed using the language. In Gavagai's systems we use concepts to model things we need to measure in streams of texts. Let's say we want to measure the sentiment towards a brand; we can model it as a Concept. Or if we want to measure whether a text is about a certain subject we could model the subject to find out to what degree texts in collection are about that subject. To model a concept we use a concept modelling tool. Such a tool will soon be available in Gavagai Monitor.

Replays

A replay is a analysis and calculation of results for a target or sector going backwards in time. By doing a replay it is as if the target or sector in question had actually been created and activated at the start of the replay period. Replays are very convenient for getting some historical data in place for your target and sector.

 

These are the basic concepts of Monitor API. There are several others but we will get to them in a later part of the tutorial.

Next Steps