API#

Data Morph allows you to morph an input dataset of 2D points into select shapes, while preserving the summary statistics to a given number of decimal points through simulated annealing. It is intended to be used as a teaching tool to illustrate the importance of data visualization (see `Data Morph in the classroom`_ for ideas).

Notes

This code has been altered by Stefanie Molin to work for other input datasets by parameterizing the target shapes with information from the input shape. The original code works for a specific dataset called the “Datasaurus” and was created for the paper Same Stats, Different Graphs: Generating Datasets with Varied Appearance and Identical Statistics through Simulated Annealing by Justin Matejka and George Fitzmaurice (ACM CHI 2017).

The paper and video can be found on the Autodesk Research website. The version of the code placed on GitHub at jmatejka/same-stats-different-graphs, served as the starting point for the Data Morph codebase, which is on GitHub at stefmolin/data-morph.

Read more about the creation of Data Morph in this article and this slide deck.

Modules

`data_morph.bounds`	Classes for representing 1D and 2D bounds.
`data_morph.data`	Module for data operations like loading and calculating summary statistics.
`data_morph.morpher`	Module containing data morphing logic.
`data_morph.plotting`	Utility functions for plotting and animating.
`data_morph.shapes`	Classes for specific shapes that data can be morphed into.

Examples

The DataMorpher class performs the morphing from a Dataset to a Shape. Any DataFrame with numeric columns x and y can be a Dataset. Use the DataLoader to create the Dataset from a file or use a built-in dataset:

from data_morph.data.loader import DataLoader

dataset = DataLoader.load_dataset('panda')

For morphing purposes, all target shapes are placed/sized based on aspects of the Dataset. All shapes are accessible via the ShapeFactory:

from data_morph.shapes.factory import ShapeFactory

shape_factory = ShapeFactory(dataset)
target_shape = shape_factory.generate_shape('star')

With the Dataset and Shape created, here is a minimal example of morphing:

from data_morph.morpher import DataMorpher

morpher = DataMorpher(
    decimals=2,
    in_notebook=False,  # whether you are running in a Jupyter Notebook
    output_dir='data_morph/output',
)

result = morpher.morph(
    start_shape=dataset,
    target_shape=target_shape,
    freeze_for=50,
    ramp_in=True,
    ramp_out=True,
)

Note

The result variable in the above code block is a DataFrame of the data after completing the specified iterations of the simulated annealing process. The DataMorpher.morph() method is also saving plots to visualize the output periodically and make an animation; these end up in data_morph/output, which we set as DataMorpher.output_dir.

This produces the following animation in the directory specified as output_dir above:

Morphing the panda dataset into the star shape. — Morphing the panda `Dataset` into the star `Shape`.#

In this example, we morphed the built-in panda Dataset into the star Shape. Be sure to try out the other built-in options:

The DataLoader.AVAILABLE_DATASETS attribute contains a list of available datasets, which are also visualized in the DataLoader documentation.
The ShapeFactory.AVAILABLE_SHAPES attribute contains a list of available shapes, which are also visualized in the ShapeFactory documentation.

For further customization, the Custom Datasets tutorial discusses how to generate custom input datasets.

Note

There is also a CLI option for morphing.

Citations

If you use this software, please cite both Data Morph (DOI: 10.5281/zenodo.7834197) and “Same Stats, Different Graphs: Generating Datasets with Varied Appearance and Identical Statistics through Simulated Annealing” by Justin Matejka and George Fitzmaurice (ACM CHI 2017).