Quick Start Guide#

Installation#

Data Morph can be installed with pip:

$ pip install data-morph-ai

Usage#

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

See all available CLI options by passing in --help:

$ 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(
    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)

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.

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