CLI Reference#

data-morph - CLI interface#

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.

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]

options#

  • -h, --help - show this help message and exit

  • --version - show program’s version number and exit

Shape Configuration (required)#

Specify the start and target shapes.

  • --start-shape START_SHAPE - The starting shape(s). A valid starting shape could be any of ['bunny', 'cat', 'dino', 'dog', 'music', 'panda', 'pi', 'Python', 'SDS', 'sheep', 'soccer'] 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. (default: None)

  • --target-shape 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. (default: None)

Morph Configuration#

Configure the morphing process.

  • --decimals DECIMALS - The number of decimal places to preserve equality. Defaults to 2. (default: 2)

  • --iterations ITERATIONS - The number of iterations to run. Defaults to 100,000. Datasets with more observations may require more iterations. (default: 100000)

  • --scale 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. (default: None)

  • --seed SEED - Provide a seed for reproducible results. (default: None)

  • --shake 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).

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.

  • --output-dir DIRECTORY - 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.

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.

  • --freeze NUM_FRAMES - 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.

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

Source code available at https://github.com/stefmolin/data-morph. CLI reference and examples are at https://stefaniemolin.com/data-morph/stable/cli.html.

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
On this page
Show Source