# Annotated Time Series

> A line chart with labeled event markers, so viewers can connect metric movements to campaigns, releases, and incidents.

A line chart with labeled event markers, so viewers can connect metric movements to campaigns, releases, and incidents. Events come from a third field input: map a column that holds the event name on event dates and is null everywhere else (for example, a calculated field or a left join from an events table).

<!-- TODO: add a screenshot of the rendered chart here -->

```aml
CustomChartDef annotated_time_series {
  label: 'Annotated Time Series'
  description: "A line chart with labeled event markers, so viewers can connect metric movements to campaigns, releases, and incidents."
  fields {
    field date {
      type: 'dimension'
      label: 'Date'
      data_type: 'date'
    }
    field value {
      type: 'measure'
      label: 'Value'
    }
    field event_label {
      type: 'dimension'
      label: 'Event Label (null on non-event dates)'
      data_type: 'string'
    }
  }
  options {
    option line_color {
      type: 'color-picker'
      label: 'Line Color'
      default_value: '#255dd4'
    }
    option event_color {
      type: 'color-picker'
      label: 'Event Marker Color'
      default_value: '#e5484d'
    }
  }
  template: @vgl
  {
    "data": {"values": @{values}},
    "layer": [
      {
        "mark": {"type": "line", "tooltip": true, "color": @{options.line_color.value}},
        "encoding": {
          "x": {
            "field": @{fields.date.name},
            "type": "temporal",
            "title": null,
            "axis": {
              "labelOverlap": true,
              "domain": false,
              "ticks": false,
              "grid": false,
              "labelPadding": 8
            }
          },
          "y": {
            "field": @{fields.value.name},
            "type": "quantitative",
            "title": null,
            "axis": {
              "format": @{fields.value.format},
              "formatType": "holisticsFormat",
              "domain": false,
              "tickColor": "#E5E7EB",
              "grid": true,
              "gridColor": "#F3F4F6",
              "gridOpacity": 1
            }
          },
          "tooltip": [
            {"field": @{fields.date.name}, "type": "temporal", "title": "Date"},
            {"field": @{fields.value.name}, "type": "quantitative", "title": "Value", "format": @{fields.value.format}, "formatType": "holisticsFormat"}
          ]
        }
      },
      {
        "transform": [
          {"filter": "datum['@{fields.event_label.name}'] != null && datum['@{fields.event_label.name}'] != ''"}
        ],
        "layer": [
          {
            "mark": {"type": "rule", "strokeDash": [4, 4], "color": @{options.event_color.value}},
            "encoding": {
              "x": {"field": @{fields.date.name}, "type": "temporal"},
              "tooltip": [
                {"field": @{fields.event_label.name}, "type": "nominal", "title": "Event"},
                {"field": @{fields.date.name}, "type": "temporal", "title": "Date"}
              ]
            }
          },
          {
            "mark": {
              "type": "text",
              "angle": 270,
              "align": "left",
              "baseline": "bottom",
              "dx": 4,
              "color": @{options.event_color.value}
            },
            "encoding": {
              "x": {"field": @{fields.date.name}, "type": "temporal"},
              "text": {"field": @{fields.event_label.name}}
            }
          }
        ]
      }
    ],
    "config": {
      "background": null,
      "view": {
        "stroke": null
      },
      "axis": {
        "labelFontSize": 12,
        "titleFontSize": 12,
        "labelFontWeight": 400,
        "titleFontWeight": 500
      },
      "legend": {
        "labelFontSize": 12,
        "titleFontSize": 12,
        "labelFontWeight": 400,
        "symbolStrokeWidth": 0
      },
      "bar": {
        "cornerRadius": 2
      }
    }
  }
  ;;
}
```

<!-- TODO: add the View on GitHub footer link once the template lands in
     https://github.com/holistics/custom-chart-library -->