Fork me on GitHub

A palette of timeline representations, scales, and layouts.

Timeline Storyteller is an open-source expressive visual storytelling environment for presenting timelines in the browser or in Microsoft Power BI.

Use it to present different aspects of timeline data using a palette of timeline representations, scales, and layouts, as well as controls for filtering, highlighting, and annotation.

Click to view in full resolution in a new tab

Examples

Here is an interactive story produced with the Timeline Storyteller custom visual for Power BI, a story about the champions of the US Open golf tournament. For another interactive story produced with the Timeline Storyteller for Power BI, see this story about the history of artificial intelligence.

Example gallery


For more inspiration, see our gallery of timelines spanning the timeline design space as well as videos of timeline stories.

Also watch these videos of Timeline Storyteller in the 2017 Microsoft Data Insights Summit keynote and during the summit's BI Power Hour.

Preparing your data

Timeline Storyteller for the web currently supports datasets of events in CSV, JSON, or Google Spreadsheet format, while Timeline Storyteller for Power BI supports datasets of events in any format that Power BI can ingest; please see this tutorial for loading data into Timeline Storyteller for Power BI.

Each event is specified by the following attributes:

  • Required: start_date, a date formatted as YYYY, YYYY-MM-DD, or YYYY-MM-DD HH:MMZ (Z necessary for specifying UTC, otherwise HH:MM will be time-zone dependent). BC dates are permitted, e.g., -27, -13800000000.
  • Optional: end_date, a date using same format as start_date.
  • Optional: category, a string corresponding to the category of the event (which Timeline Storyteller encodes as colour).
  • Optional: facet, a string corresponding to another category of the event (which Timeline Storyteller uses to create a faceted timeline layout; category and facet can be identical if desired).
  • Optional: content_text, a string description of the event (which Timeline Storyteller exposes as event annotations).

Example events in JSON:

Example 1:

{
  "start_date":"1775",
  "end_date":"1783",
  "content_text":"American Revolutionary War.",
  "facet":"North America",
  "category":"North America"
},
              
Example 2 (small-scale timeline):

{
  "facet":"Hugo, Victor",
  "category":"other",
  "start_date":"2015-07-10 11:00Z",
  "end_date":"2015-07-10 11:59Z",
  "content_text":"Taking an ice bath on the roof"
},
              
Example 3 (epoch scale timeline):

{
  "content_text":"Human ancestors walk upright",
  "start_date":"-4200000",
  "end_date":""
},
              

Example CSV / Google Spreadsheet:

The "The Daily Routines of Famous Creative People" demo dataset used in Timeline Storyteller:

Loading Google Spreadsheets
  • Refer to the URL of a spreadsheet, such as: https://docs.google.com/spreadsheets
    /d/1x8N7Z9RUrA9Jmc38Rvw1VkHslp8rgV2Ws3h_5iM-I8M/pubhtml
  • Ensure that the spreadsheet is published (open the Google Spreadsheet 'File' menu, select 'Publish to the Web').
  • Ensure that start_date and end_date columns are formatted as text and not as dates (e.g., '1926-06-29).
  • Required: Spreadsheet URL
  • Optional: Worksheet title (i.e., tab name) for this dataset: dailyroutines
  • Enter the spreadsheet URL and worksheet title into Timeline Storyteller's load dialog.

How to use Timeline Storyteller

To use Timeline Storyteller for Power BI, watch this tutorial.

To use Timeline Storyteller in the browser, follow these steps:

  1. Load timeline data (demo dataset, JSON, CSV, Google Spreadsheet) or saved timeline story (a JSON Blob with extension .cdc; see step 5).

    Load timeline data (demo dataset, JSON, CSV, Google Spreadsheet) or saved timeline story
    • A note about privacy: Your data remains on your machine and is not shared with Microsoft unless you export the content you create and provide your email address. If you share your content with Microsoft, we will use it for research and to improve our products and services. We may also include it in a future research publication.
  2. Select a combination of representation, scale, and layout from the menu at the top of the screen; only some combinations are valid; see our guidance on selecting appropriate combinations for your story. Mouseover these options to view a tooltip that describes how they might be useful.
  3. Select a combination of representation, scale, and layout from the menu at the top of the screen
  4. Edit the canvas:
    • Click on events to annotate with their content_text label; resize and reposition these labels; SHIFT + click to highlight events without showing label.
    • Click on events to annotate with their content_text label; resize and reposition these labels; SHIFT + click to highlight events without showing label
    • Annotate the canvas with captions and images; resize and reposition captions and images.
    • Annotate the canvas with captions and images; resize and reposition captions and images.
    • Filter events by category, facet, or segment. Filter by highlighting matching events (de-emphasizing non-matching events).
    • Filter events by category, facet, or segment. Filter by highlighting matching events (de-emphasizing non-matching events).
    • You can also filter by hiding non-matching events:
    • Filter events by category, facet, or segment. Filter by hiding non-matching events.
  5. Record current canvas as a scene, which retains labels, captions, and images; enter playback mode, navigate to previous / next recorded scene
  6. Record current canvas as a scene, which retains labels, captions, and images
  7. Export the current canvas as a PNG or SVG, or export the series of scenes as an animated GIF or as a JSON Blob (.cdc extension). By providing an email address you agree that Microsoft may contact you to request feedback and for user research. You may withdraw this consent at any time. You can also opt out and not share your content with Microsoft.
  8. Export current canvas as a PNG or SVG, or export the series of scenes as an animated GIF or as a JSON Blob

Source code

Timeline Storyteller was developed at Microsoft Research and deployed as an Azure web app.

This is an open source project released under a MIT license. Contribute to this project by submitting issues and pull requests at github.com/Microsoft/timelinestoryteller.

Acknowledgements

To learn more about the Microsoft Research project that informed the design of Timeline Storyteller, see timelinesrevisited.github.io, which includes a survey of timeline tools and more than 200 bespoke timelines.

Citing us

If you use Timeline Storyteller to make a timeline for a research paper, you can cite us in two ways. You can cite the tool itself:


@misc{TimelineStoryteller,
author = {Matthew Brehmer and Bongshin Lee and Nathalie Henry Riche and Darren Edge and Christopher White and Kate Lytvynets and David Tittsworth},
title = {Microsoft Timeline Storyteller},
year = {2017},
note = {\url{https://timelinestoryteller.com}}
}

Or you can cite our recent journal paper about the timeline design space:


@article{Brehmer2016,
author = {Matthew Brehmer and Bongshin Lee and Benjamin Bach and Nathalie Henry Riche and Tamara Munzner},
title = {Timelines Revisited: A Design Space and Considerations for Expressive Storytelling},
journal = {IEEE Transactions on Visualization and Computer Graphics (TVCG)},
year = {2017},
volume = {23},
issue = {9},
pages = {2151--2164},
doi = {10.1109/TVCG.2016.2614803},
ISSN = {1077-2626}
}

Demo dataset provenance:

Noun Project icons (CC BY 3.0) used in the user interface: