EventTrendsTile Documentation

Purpose

The EventTrendsTile is a component of the Vantage analytics and data platform that allows users to visualize trends associated with various events over time. It enables users to search for specific events and explore their corresponding trends in terms of volume or tone. This visualization aids users in making data-driven decisions based on trending events.

How It Works

The EventTrendsTile leverages a canvas element to draw a responsive chart based on user-defined queries and settings. It fetches data from the GDELT (Global Database of Events, Language, and Tone) API and displays the results dynamically. The component handles user input, manages loading states, error states, and optimizes rendering using the device's pixel ratio.

Data Expectations

The component expects the following data from the API it queries:

• Query: The user-defined search term to find relevant events.
• Timespan: The time duration over which trends will be displayed (e.g., last 1 day, 7 days, etc.).
• Mode: A mode setting to determine if the trend should reflect 'volume' of events or 'tone' associated with those events.
• Data Points: The fetched data should include values (volume, count, or a tone) along with dates or timestamps.

Settings

The EventTrendsTile features several configurable settings that allow for a tailored user experience. Below is a comprehensive overview of each setting:

1. Query

• Input Type: String
• Description: The search string input by the user to fetch event trends. This query is used to filter the data returned by the API.
• Default Value: An empty string ''.
• Effect of Change: Affecting this input dynamically updates the results displayed and adjusts the chart based on the specified term.

2. Timespan

• Input Type: Dropdown (String)
• Description: Defines the time range over which the trends of the event will be observed. The options include:
  • 1d (24 hours)
  • 3d (3 days)
  • 7d (7 days)
  • 14d (14 days)
  • 1m (30 days)
  • 3m (90 days)
• Default Value: 7d
• Effect of Change: Changing the timespan modifies the dataset queried and affects the trend visual representation over a different duration.

3. Mode

• Input Type: Dropdown (String)
• Description: Determines whether the trend visualizes event 'volume' (the number of occurrences) or 'tone' (sentiment or mood of the events).
  • volume: Represents the number of events.
  • tone: Represents the sentiment associated with events.
• Default Value: volume
• Effect of Change: This setting alters both the appearance of the chart (color representation) and the data used, providing contextual insights into whether the user is interested in the number of events or their sentiment.

4. Search Button

• Input Type: Button
• Description: Initiates the data fetch based on the current values of Query, Timespan, and Mode.
• Default Value: Disabled when loading or when the query is empty.
• Effect of Change: When clicked, it triggers the search functionality to retrieve and update data, displaying results on the chart.

5. Error Handling

• Condition: The component shows error messages if the API request fails or if no trend data is found, providing feedback to the user regarding the interaction outcome.

6. Loading State

• Indication: A loader is displayed when the component is fetching data to inform the user of ongoing activity.

Use Cases & Examples

Use Cases

1. Event Monitoring: A media analyst tracks global crises or events (e.g., protests or natural disasters) to provide real-time updates or reports.
2. Market Research: A marketing team investigates public sentiment around their product launches or advertising campaigns by analyzing tone and volume of mentions.
3. Crisis Management: Public relations teams monitor trends in social media or news coverage to prepare appropriate responses and manage customer sentiment effectively.

Example Configuration to Solve a Use Case

Use Case: Event Monitoring for Crises

Configuration Data:

• Query: Earthquake
• Timespan: 14d
• Mode: volume

How to Configure:

const tileConfig = {
    defaultQuery: 'Earthquake',
    defaultTimespan: '14d',
};

// When rendering the component
<EventTrendsTile tile={{ config: tileConfig }} />

Expected Outcome: This configuration will prompt the EventTrendsTile to visualize the volume of mentions or reports regarding earthquakes over the past 14 days. The output will provide insights into when and where earthquake-related events are reported most frequently, supporting analysts and decision-makers in tracking such occurrences.

AI Integrations

The EventTrendsTile does not currently have explicit AI integrations, but there could be potential extensions to use AI-driven sentiment analysis on the event data to provide more nuanced insights into tone trends.

Billing Impact

The EventTrendsTile fetches data from the GDELT API, which may involve API rate limits and associated costs based on the number of requests made. Usage patterns involving frequent data querying might necessitate careful monitoring of API consumption under Vantage’s billing policies.

Incorporating the component effectively requires an understanding of these dependencies to avoid unexpected billing increases.