Quick Start Guide#


Data Morph can be installed from PyPI using pip:

$ pip install data-morph-ai

Alternatively, Data Morph can be installed with conda by specifying the conda-forge channel:

$ conda install -c conda-forge data-morph-ai


Once installed, Data Morph can be used on the command line or as an importable Python package.

Command line usage#

Run data-morph on the command line:

$ data-morph --start-shape panda --target-shape star

This produces the following animation in the newly-created morphed_data directory within your current working directory:

Morphing the panda dataset into the star shape.

Morphing the panda Dataset into the star Shape.#

You can smooth the transition with the --ramp-in and --ramp-out flags. The --freeze flag allows you to start the animation with the specified number of frames of the initial shape:

$ data-morph --start-shape panda --target-shape star --freeze 50 --ramp-in --ramp-out

Here is the resulting animation:

Morphing the panda dataset into the star shape with easing.

Morphing the panda Dataset into the star Shape with easing.#

See all available CLI options by passing in --help or consulting the CLI Reference:

$ data-morph --help

Python usage#

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(
    in_notebook=False,  # whether you are running in a Jupyter Notebook

result = morpher.morph(


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.

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

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