morpher#

Module containing data morphing logic.

Classes

DataMorpher(*, decimals, in_notebook[, ...])

Class for morphing a dataset into a target shape, preserving summary statistics.

class data_morph.morpher.DataMorpher(*, decimals: int, in_notebook: bool, output_dir: str | Path | None = None, write_images: bool = True, write_data: bool = False, seed: int | None = None, num_frames: int = 100, keep_frames: bool = False, forward_only_animation: bool = False)[source]#

Bases: object

Class for morphing a dataset into a target shape, preserving summary statistics.

Parameters:
  • decimals (int) – The number of decimals to which summary statistics should be the preserved.

  • in_notebook (bool) – Whether this is running in a notebook.

  • output_dir (str or pathlib.Path, optional) – The directory to write output files (CSV, PNG, GIF).

  • write_images (bool, default True) – Whether to write image files to output_dir. This must be True for animation.

  • write_data (bool, default False) – Whether to write data files to output_dir.

  • seed (int, optional) – Provide an integer seed to the random number generator.

  • num_frames (int, default 100) – The number of frames to record out of the morphing process.

  • keep_frames (bool, default False) – Whether to keep image files written to output_dir after stitching the GIF animation.

  • forward_only_animation (bool, default False) – Whether to generate the animation in the forward direction only. By default, the animation will play forward and then reverse.

decimals#

The number of decimals to which summary statistics should be the preserved.

Type:

int

forward_only_animation#

Whether to generate the animation in the forward direction only. By default, the animation will play forward and then reverse. This has no effect unless write_images is True.

Type:

bool

keep_frames#

Whether to keep image files written to output_dir after stitching the GIF animation. This has no effect unless write_images is True.

Type:

bool

morph(start_shape: Dataset, target_shape: Shape, *, iterations: int = 100000, max_temp: Number = 0.4, min_temp: Number = 0, min_shake: Number = 0.3, max_shake: Number = 1, allowed_dist: Number = 2, ramp_in: bool = False, ramp_out: bool = False, freeze_for: int = 0) DataFrame[source]#

Morph a dataset into a target shape by perturbing it with simulated annealing.

Parameters:
  • start_shape (Dataset) – The dataset for the starting shape.

  • target_shape (Shape) – The shape we want to morph into.

  • iterations (int) – The number of iterations to run simulated annealing for.

  • max_temp (numbers.Number) – The maximum temperature for simulated annealing (starting temperature).

  • min_temp (numbers.Number) – The minimum temperature for simulated annealing (ending temperature).

  • min_shake (numbers.Number) – The standard deviation of random movement applied in each direction, sampled from a normal distribution with a mean of zero. Value will start at max_shake and move toward min_shake.

  • max_shake (numbers.Number) – The standard deviation of random movement applied in each direction, sampled from a normal distribution with a mean of zero. Value will start at max_shake and move toward min_shake.

  • allowed_dist (numbers.Number) – The farthest apart the perturbed points can be from the target shape.

  • ramp_in (bool, default False) – Whether to more slowly transition in the beginning. This only affects the frames, not the algorithm.

  • ramp_out (bool, default False) – Whether to slow down the transition at the end. This only affects the frames, not the algorithm.

  • freeze_for (int, default 0) – The number of frames to freeze at the beginning and end. This only affects the frames, not the algorithm. Must be in the interval [0, 50].

Returns:

The morphed data.

Return type:

pandas.DataFrame

See also

DataLoader

The initial state for the morphing process is a Dataset. Available built-in options can be found here.

ShapeFactory

The target state for the morphing process is a Shape. Options for the target can be found here.

Notes

This method saves data to disk at output_dir, which includes frames and/or animation (see write_images and keep_frames) and, depending on write_data, CSV files for each frame.

num_frames#

The number of frames to capture. Must be > 0 and <= 100.

Type:

int

output_dir#

The directory to write output files (CSV, PNG, GIF).

Type:

pathlib.Path

write_data#

Whether to write data files to output_dir.

Type:

bool

write_images#

Whether to write image files to output_dir.

Type:

bool