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] [-w WORKERS] --start START_SHAPE [START_SHAPE ...]
           --target TARGET_SHAPE [TARGET_SHAPE ...] [--decimals {0,1,2,3,4,5}]
           [--iterations ITERATIONS] [--scale SCALE] [--seed SEED] [--shake SHAKE]
           [--keep-frames] [-o DIRECTORY] [--write-data] [--ease] [--ease-in] [--ease-out]
           [--forward-only] [--freeze NUM_FRAMES]

options#

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

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

  • -w WORKERS, --workers WORKERS - The number of workers. Default 2. Pass 0 to use as many as possible. (default: 2)

Shape Configuration (required)#

Specify the start and target shapes.

  • --start START_SHAPE, --start-shape START_SHAPE - The starting shape(s). A valid starting shape could be any of ['bunny', 'cat', 'dino', 'dog', 'gorilla', '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 TARGET_SHAPE, --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', 'club', 'diamond', 'dots', 'down_parab', 'figure_eight', 'h_lines', 'heart', 'high_lines', 'left_parab', 'rectangle', 'right_parab', 'rings', 'scatter', 'slant_down', 'slant_up', 'spade', 'spiral', '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.

  • -o DIRECTORY, --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.

  • --ease - Whether to slow down the transition near the start and end of the transformation. This is a shortcut for –ease-in –ease-out. This only affects the frames selected, not the algorithm.

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

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

  • --forward-only - By default, this module will create an animation that plays first forward (applying the transformation) and then rewinds, 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)

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 distributing the work to as many worker processes as possible:

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

  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 easing in and out for the animation:

    $ data-morph --start-shape sheep --target-shape v_lines --ease