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]
           [--with-median] [--keep-frames] [-o DIRECTORY] [--write-data] [--classic] [--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).
--with-median - Whether to require the median to be preserved. Note that this will be a little slower.

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.

--classic - Whether to plot the original visualization, which consists of a scatter plot and the summary statistics. Otherwise, marginal plots will be included in addition to the classic plot.
--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#

Morph the panda shape into a star:

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

Morph the panda shape into all available target shapes distributing the work to as many worker processes as possible:
```
$ data-morph --start panda --target all --workers 0
```
Morph the cat, dog, and panda shapes into the circle and slant_down shapes:
```
$ data-morph --start cat dog panda --target circle slant_down
```
Morph the dog shape into upward-slanting lines over 50,000 iterations with seed 1:
```
$ data-morph --start dog --target slant_up --iterations 50000 --seed 1
```
Morph the cat shape into a circle, preserving summary statistics to 3 decimal places:
```
$ data-morph --start cat --target circle --decimals 3
```

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

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

Morph the sheep shape into vertical lines, slowly easing in and out for the animation:
```
$ data-morph --start sheep --target v_lines --ease
```