Adding Annotation Layers to Line Charts in UpMetrics

Annotation layers help you add important context to your line charts by highlighting specific time periods or events. This guide will show you how to create interval and event annotations using table charts as your data source.

What Are Annotation Layers?

Annotation layers overlay additional information on your line charts to provide context about specific dates or time periods. They're particularly useful for:

• Highlighting important business events or milestones

• Marking seasonal trends or campaign periods

• Identifying external factors that may have influenced your data

• Adding context for stakeholders reviewing your dashboards

Types of Annotations Available

Advanced Analytics supports three main types of annotations that can be created using table charts and formulas:

Interval Annotations

• Purpose: Mark specific time periods or ranges on your chart

• Use cases: Marketing campaigns, product launches, seasonal periods, business quarters

• Requirements: Table Chart with start date and end date columns

Event Annotations

• Purpose: Mark specific dates or points in time on your chart

• Use cases: Product releases, policy changes, major announcements, incidents

• Requirements: Table Chart with a single date column

Formula Annotations

• Purpose: Create dynamic lines or markers based on mathematical formulas
• Use cases: Target lines, thresholds, trend lines, calculated benchmarks
• Requirements: Either of the following:
  • Mathematical expression using variable x (time in milliseconds since Epoch date: January 1, 1970) 
  • Static number to mark a fixed line on the Y axis

Setting Up Your Annotation Data Source

Before creating annotation layers, you'll need to prepare your data in a table chart within UpMetrics.

For Interval Annotations

Create a table chart with at minimum the following columns:

• Start Date: The beginning of the time period (required)

• End Date: The conclusion of the time period (required)

• Title: The name of the interval (optional but recommended)

• Description: A brief description of the interval (optional)

For Event Annotations

Create a table chart with at minimum the following columns:

• Date: The specific date of the event (required)

• Title: The name of the event (optional but recommended)

• Description: A brief description of the event (optional)

Creating Annotation Layers

Setup

1. Data is uploaded to UpMetrics Collect to create a line chart; or a line chart already exists

2. Interval or Event data is uploaded to UpMetrics Collect following the structure above

Step 1: Prepare Your Table Chart

1. Navigate to Advanced Analytics

2. Create a new Table Chart using your annotation data source

3. Configure the table to display raw records including your date columns, titles, and descriptions

4. Save the table chart with a descriptive name (e.g., "Marketing Campaign Intervals" or "Product Launch Events")

Step 2: Add Annotation Layer to Your Line Chart

1. Open the line chart where you want to add annotations

2. Scroll down to the Annotations and Layers section in the chart configuration

3. Click + Add annotation layer

Step 3: Configure the Annotation Layer

For Interval Annotations:

1. Layer Configuration:

   • Name: Enter a descriptive name for this annotation layer

   • Annotation Layer Type: Select Interval

   • Annotation Source: Select Table

   • Chart: Choose your prepared table chart

2. Column Mapping:

   • Interval Start Column: Select the column containing start dates

   • Interval End Column: Select the column containing end dates

   • Title Column: Select the column with the title (optional but recommended)

   • Description Columns: Select the column (or multiple) that contain the description (optional)

3. Display Configuration:

   • Opacity: Adjust transparency of the annotation overlay (0-1) (0.5 is recommended)

   • Color: Choose a color for the interval highlighting

For Event Annotations:

1. Layer Configuration:

   • Name: Enter a descriptive name for this annotation layer

   • Annotation Layer Type: Select Event

   • Annotation Source: Select Table

   • Chart: Choose your prepared table chart

2. Column Mapping:

   • Event Time Column: Select the column containing event dates

   • Title Column: Select the column with the title (optional but recommended)

   • Description Columns: Select the column (or multiple) that contain the description (optional)

3. Display Configuration:

   • Line Style: Choose solid, dashed, or dotted lines

   • Line Width: Adjust thickness of the event markers

   • Color: Choose a color for the event lines

Step 4: Apply and Review

1. Click Apply, OK in the annotation modal to save the annotation settings.

2. Click Update Chart to preview your annotation layer on the chart

3. Review how the annotations appear on your chart

4. Adjust display settings if needed

5. Click Save to finalize your chart with annotations

Best Practices

Design Guidelines

• Use contrasting colors: Ensure annotations are visible but don't overpower your main data

• Limit annotation density: Too many annotations can clutter your chart

• Keep labels concise: Use brief, clear descriptions that won't overlap

• Consider opacity: Semi-transparent annotations (0.3-0.7 opacity) often work best

Data Management

• Standardize date formats: Ensure consistent date formatting in your source tables

• Update annotations centrally: Changes to your source data and associated table chart will automatically update all charts using those annotations.

• Document your annotations: Include clear descriptions to help other team members understand the context

Performance Considerations

• Limit annotation count: Large numbers of annotations can slow chart rendering

• Optimize date ranges: Only include annotations relevant to your chart's time period

• Test with different data volumes: Verify performance with your typical data loads

Troubleshooting Common Issues

Annotations Not Displaying

• Check date formats: Ensure your dates match the format expected by UpMetrics

• Verify time zone settings: Confirm your annotation dates align with your chart's time zone

• Review column mapping: Double-check that you've selected the correct date columns

Overlapping Labels

• Reduce label length: Use shorter, more concise descriptions

• Adjust annotation density: Consider combining related events or intervals

• Modify display settings: Experiment with showing/hiding the label

Performance Issues

• Limit annotation scope: Focus on the most important annotations for your use case

• Optimize data queries: Ensure your source table queries are efficient

• Consider chart complexity: Complex charts with many layers may need simplified annotations

Advanced Tips

Managing Multiple Annotation Layers

You can add multiple annotation layers to a single chart to represent different types of context:

• Layer 1: Major organizational events (red)

• Layer 2: Marketing campaigns (blue)

• Layer 3: Product releases (green)

Dynamic Annotations

Since annotations are based on table charts, they automatically update when your source data changes. This makes it easy to:

• Add new events without modifying each chart individually

• Maintain consistent annotations across multiple dashboards

• Collaborate with team members who can update annotation data

Integration with Data Sources

Connect your annotation tables to the same data sources as your main metrics to ensure consistency and reduce manual maintenance.