An expressive visual storytelling environment for presenting timelines on the web and in Power BI. Developed at Microsoft Research.
JavaScript CSS HTML
Switch branches/tags
Nothing to show
Clone or download
Latest commit 98f0fd5 Jan 19, 2018

README.md

Timeline Storyteller

"The Daily Routines of Famous Creative People": A Story made with Timeline Storyteller

Timeline Storyteller is an 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.

Timeline Design dimensions

To learn more about the research that informed this project, see timelinesrevisited.github.io, which includes a survey of timeline tools and more than 200 bespoke timelines.

See these examples of timelines and timeline stories made with Timeline Storyteller.

Project Team

Setup / Testing

  1. Clone the main branch of this repository: git clone https://github.com/Microsoft/timelinestoryteller.git

  2. Ensure that nodejs, npm, and yarn are installed.

  3. Open a terminal at the root of the repository and install node modules: yarn OR npm_install.

  4. Build public/app/timelinestoryteller.js: npm test

  5. Start the node server: npm start

  6. Open localhost:8000

The application source code can be found in the src/ directory.

Preparing your data

Timeline Storyteller currently supports datasets of events in CSV, JSON, or Google Spreadsheet format.

Each event is specified by the following attributes:

  • Required: start_date, date: YYYY, YYYY-MM-DD, or YYYY-MM-DD HH:MMZ (ISO 8601) formats are supported (Z necessary for specifying UTC, otherwise HH:MM will be time-zone dependent). BC dates are permitted, e.g., -27, -13800000000
  • Optional: end_date, 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 event in JSON:

{ "start_date":"1775", "end_date":"1783", "content_text":"American Revolutionary War: an armed struggle for secession from the British Empire by the Thirteen Colonies that would subsequently become the United States.", "facet":"North America", "category":"North America" },

Example event in CSV:

header row:

start_date,end_date,content_text,facet,category

example event row:

1775,1783,American Revolutionary War: an armed struggle for secession from the British Empire by the Thirteen Colonies that would subsequently become the United States.,North America,North America

Example CSV / Google Spreadsheet

Here is the The Daily Routines of Famous Creative People demo dataset used in Timeline Storyteller's demo in a Google Sheet.

  • 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.

Usage

Note that more detailed usage instructions are available at timelinestoryteller.com

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

  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. Edit the canvas

    • Click on events to annotate with their content_text label; resize and reposition labels; SHIFT + click to highlight events without showing label.

    • Annotate with captions and images; resize and reposition captions and images.

    • Filter events by category, facet, or segment. Filter by highlighting emphasizing matching events (de-emphasizing non-matching events).

    • You can also filter by hiding non-matching events.

  4. Record current canvas as a scene, which retains labels, captions, and images. Enter playback mode, navigate to previous / next recorded scene.

  5. Export current canvas as a PNG, SVG.

  6. Export the scenes as an animated GIF or as a JSON Blob (.cdc extension).

License

Timeline Storyteller

Copyright (c) Microsoft Corporation

All rights reserved.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

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 used in the user interface

All Icons CC BY 3.0, by name and author: