CLI Reference#

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.

usage: data-morph [-h] [--version] --start-shape START_SHAPE [START_SHAPE ...]
	--target-shape TARGET_SHAPE [TARGET_SHAPE ...]  [--decimals {0,1,2,3,4,5}]
	[--iterations ITERATIONS]  [--scale SCALE] [--seed SEED] [--shake SHAKE]
	[--keep-frames] [--output-dir DIRECTORY] [--write-data]  [--forward-only]
	[--freeze NUM_FRAMES] [--ramp-in]  [--ramp-out]

Named Arguments#

--version

show program’s version number and exit

Shape Configuration (required)#

Specify the start and target shapes.

--start-shape

The starting shape(s). A valid starting shape could be any of [‘bunny’, ‘cat’, ‘dino’, ‘dog’, ‘music’, ‘panda’, ‘Python’, ‘SDS’, ‘sheep’] or a path to a CSV file, in which case it should have two columns ‘x’ and ‘y’. See the documentation for visualizations of the built-in datasets.

--target-shape

The shape(s) to convert to. If multiple shapes are provided, the starting shape will be converted to each target shape separately. Valid target shapes are ‘bullseye’, ‘circle’, ‘diamond’, ‘dots’, ‘down_parab’, ‘h_lines’, ‘heart’, ‘high_lines’, ‘left_parab’, ‘rectangle’, ‘right_parab’, ‘rings’, ‘scatter’, ‘slant_down’, ‘slant_up’, ‘star’, ‘up_parab’, ‘v_lines’, ‘wide_lines’, ‘x’. Use ‘all’ to convert to all target shapes in a single run. See the documentation for visualizations of the available target shapes.

Morph Configuration#

Configure the morphing process.

--decimals

Possible choices: 0, 1, 2, 3, 4, 5

The number of decimal places to preserve equality. Defaults to 2.

Default: 2

--iterations

The number of iterations to run. Defaults to 100,000. Datasets with more observations may require more iterations.

Default: 100000

--scale

Scale the data on both x and y by dividing by a scale factor. For example, --scale 10 divides all x and y values by 10. Datasets with large values will morph faster after scaling down.

--seed

Provide a seed for reproducible results.

--shake

The standard deviation for the random movement applied in each direction, which will be sampled from a normal distribution with a mean of zero. Note that morphing initially sets the shake to 1, and then decreases the shake value over time toward the minimum value defined here, which defaults to 0.3. Datasets with large values may benefit from scaling (see --scale) or increasing this towards 1, along with increasing the number of iterations (see --iterations).

Default: 0.3

Output File Configuration#

Customize where files are written to and which types of files are kept.

--keep-frames

Whether to keep individual frame images in the output directory. If you don’t pass this, the frames will be deleted after the GIF file is created.

Default: False

--output-dir

Path to a directory for writing output files. Defaults to morphed_data.

Default: “morphed_data”

--write-data

Whether to write CSV files to the output directory with the data for each frame.

Default: False

Animation Configuration#

Customize aspects of the animation.

--forward-only

By default, this module will create an animation that plays first forward (applying the transformation) and then unwinds, playing backward to undo the transformation. Pass this argument to only play the animation in the forward direction before looping.

Default: False

--freeze

Number of frames to freeze at the first and final frame of the transition in the animation. This only affects the frames selected, not the algorithm. Defaults to 0.

Default: 0

--ramp-in

Whether to slowly start the transition from input to target in the animation. This only affects the frames selected, not the algorithm.

Default: False

--ramp-out

Whether to slow down the transition from input to target towards the end of the animation. This only affects the frames selected, not the algorithm.

Default: False

Examples#

  1. Morph the panda shape into a star:

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

  2. Morph the panda shape into all available target shapes:

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

  3. Morph the cat, dog, and panda shapes into the circle and slant_down shapes:

    $ data-morph --start-shape cat dog panda --target-shape circle slant_down

  4. Morph the dog shape into upward-slanting lines over 50,000 iterations with seed 1:

    $ data-morph --start-shape dog --target-shape slant_up --iterations 50000 --seed 1

  5. Morph the cat shape into a circle, preserving summary statistics to 3 decimal places:

    $ data-morph --start-shape cat --target-shape circle --decimals 3

  6. Morph the music shape into a bullseye, specifying the output directory:

    $ data-morph --start-shape music --target-shape bullseye --output-dir path/to/dir

  7. Morph the sheep shape into vertical lines, slowly ramping in and out for the animation:

    $ data-morph --start-shape sheep --target-shape v_lines --ramp-in --ramp-out