!nflect _📊^💬

Modulating Visualizations to Tell Stories with Data

!nflect is a web-based framework implementing inflections as a method to bridge the gap between data exploration and storytelling. By linking to specific views and annotations in visualizations, authors can embed insights from their data analysis within the narrative flow.

• See the 📜scrollytelling in action, if you read this as a regular readme file
• Check out the sample stories featuring 📊visualizations, 🖼️images and 🌎webpages.
• Fork this ⚙️repository to create your data story with inflected visualizations

Inf... what?

An inflection is a subtle modulation of a visualization's graphical attributes—such as zoom levels, highlights, or annotations—that guide a reader's attention and anchor interpretative insights.

Inflections can be referenced directly in a story, so that scrolling through the text triggers transitions of the visualization state accordingly—thereby strengthening the interplay between data analysis and narrative structure.

As an exercise in inception, we highlighted the inflections visible in these Vega-Lite charts on the left.

Overview

This repository contains everything you need to host data stories with inflected visualizations on a web server.

The two key components are:

• Markdown file containing the story's source text
• Vega-Lite specifications for interactive charts

Folder structure

If you take a closer look, you see three key folders:

• /img: Reference images and screenshots
• /src: Essential third-party libraries and font files
• /vis: Vega-Lite specs and datasets for each chart

Story files

The Markdown files contain the source texts for the stories. They are stored at the root level of the framework's file structure. You are currently reading the content of README.md, which is the default file loaded when no other story file is specified.

You can open a story file by adding its filename without the extension .md behind the URL's hash. For example, the story file visualizations.md is displayed by the !inflect framework when this URL is opened:

https://uclab-potsdam.github.io/inflect/#visualizations

Getting started

It takes three steps to create a data story with !nflect.

1. Create a visualization 📊

• Go to the Vega-Lite editor to create a basic chart
• Export the JSON spec (.json) and place it in /vis
• Copy your CSV/JSON dataset into /vis/data if needed

The framework currently supports bar charts, scatterplots, line charts, and pie charts.

2. Add inflections 💬

• Open the inflection editor by navigating your browser to: /vis/#spec_file (without the extension .json)
• Interact with the chart to define your inflections, e.g., zoom or adjust scales, highlight elements, or add lines or labels
• All these changes are encoded in the URL hash. You can copy that link at any time and paste it into your Markdown story

The editor includes a reset button to remove all inflections. You can also use the browser's back button to undo any changes.

3. Write data story 📄

• Create a Markdown file (e.g., my_story.md) and place it in the root directory
• Draft your narrative and embed links to inflected visualizations: check out [this view](vis/#spec_file?hash)
• Save and open your story in the browser with: /#my_story (without the extension .md)

As you scroll along the story text, the framework automatically modulates the visualizations in sync with the paragraphs.

The syntax is Markdown with three notable conventions:

1. Two consecutive empty lines create the vertical separation between sections
2. Markdown links are treated as inflection references, instructing the framework to update the embedded visualization. Regular HTML links bypass this mechanism and are rendered as simple text links, without the respective webpage being loaded into the iframe.
3. Inflected images can be included with Markdown links or images. You can hide them from the story text, by using image tags with the alt attribute set to img:
   ![img](img/#parameters...)

At a glance

This documentation image shows the main components and mechanisms at a glance. It contains:

• further detail on the file structure

• the software architecture...

• a cheat sheet on how to create a data story

• the structure of the URL hash that encodes the inflections

Credits

The !fnlect framework was developed by Theresa Eingartner and Marian Dörk in collaboration with Johanna Drucker.

The framework relies on the libraries D3.js, Vega & Vega-Lite, and Marked for their visualization, interaction, and parsing powers.

The story text is rendered in Atkinson Hyperlegible.