package modules#

animator.py#

This module contains animators that join images into the desired animation format.

class enjoyn.animator.BaseAnimator(*, items: types.ConstrainedListValue[Any], output_path: pathlib.Path, preprocessor: Optional[Union[enjoyn.preprocessor.Preprocessor, Callable]] = None, imwrite_kwds: Optional[Dict[str, Any]] = None, scratch_directory: Optional[pathlib.Path] = None, show_output: bool = True)[source]#

Bases: pydantic.main.BaseModel, abc.ABC

The base animator containing most of the common inputs and methods used in other animators inheriting from this. Note, this should not to be used directly.

Parameters

  • items – The items to animate; can be file names, bytes, numpy arrays, or anything that can be read with imageio.imread. If the preprocessor is provided, then the items can be anything the preprocessor function accepts.

  • output_path – The path to save the output animation to.

  • preprocessor – The preprocessor to apply to each item. More info can be found within the enjoyn.Preprocessor() model’s docstring.

  • imwrite_kwds – Additional keywords to pass to imageio.imwrite.

  • scratch_directory – The base directory to create the temporary directory for intermediary files.

  • show_output – Whether to display the output inline; only available in an IPython environment.

compute(partition_size: Optional[int] = None, split_every: Optional[int] = None, client: Optional[Client] = None, scheduler: Optional[str] = None, show_progress: bool = True, **compute_kwds: Dict[str, Any]) → Union[IPython.core.display.Image, IPython.core.display.Video, pathlib.Path][source]#

Execute the plan to create the animation, partitioning items across workers, applying the preprocessor, if any, serializing the items into an incomplete animation, and progressively joining those animations into the final animation.

Parameters

  • partition_size – The number of items per partition to pass to workers.

  • split_every – The number of partitions per group while reducing.

  • client – If a distributed client is not provided, will use the local client, which has limited options.

  • scheduler – Whether to use threads or processes workers; if unspecified, defaults to processes if a preprocessor is provided, else threads.

  • show_progress – Whether to display the progress bar; if client is provided, the progress bar will not show.

  • **compute_kwds – Additional keywords to pass to dask.compute, or if client is provided, client.compute.

Returns

The path to the output animation.

classmethod from_directory(directory: Union[pathlib.Path, str], pattern: str = '*.*', limit: Optional[int] = None, **animator_kwds) → Self[source]#

Searches a directory for file names that match the pattern and uses them as items in the animator.

Parameters

  • directory – The directory to retrieve the file names.

  • pattern – The pattern to subset the file names within the directory.

  • limit – The maximum number of file names to use.

  • **animator_kwds – Additional keywords to pass to the animator.

Returns

An instantiated animator class.

plan(partition_size: Optional[int] = None, split_every: Optional[int] = None, visualize: bool = True, **compute_kwds: Dict[str, Any]) → dask.delayed.delayed[source]#

Assemble the plan to create the animation, partitioning items across workers, applying the preprocessor, if any, serializing the items into an incomplete animation, and progressively joining those animations into the final animation.

Parameters

  • partition_size – The number of items per partition to pass to workers.

  • split_every – The number of partitions per group while reducing.

  • visualize – Returns a visual of how the items are delegated if True which could be useful when using a Jupyter notebook; otherwise, returns a Delayed object.

  • **compute_kwds – Not used for anything in plan; exists so it’s straightforward to swap plan out for compute when ready.

Returns

A visualization if visualize=True, otherwise dask.delayed object.

class enjoyn.animator.GifAnimator(*, items: types.ConstrainedListValue[Any], output_path: pathlib.Path = PosixPath('enjoyn.gif'), preprocessor: Optional[Union[enjoyn.preprocessor.Preprocessor, Callable]] = None, imwrite_kwds: Optional[Dict[str, Any]] = None, scratch_directory: Optional[pathlib.Path] = None, show_output: bool = True, gifsicle_options: List[str] = ('--optimize=2', '--loopcount=0', '--no-warnings', '--no-conserve-memory'))[source]#

Bases: enjoyn.animator.BaseAnimator

Used for animating images into a GIF animation.

Parameters

gifsicle_options – A tuple of options to pass to gifsicle; see the [gifsicle manual](https://www.lcdf.org/gifsicle/man.html) for a full list of available options.

class enjoyn.animator.Mp4Animator(*, items: types.ConstrainedListValue[Any], output_path: pathlib.Path = PosixPath('enjoyn.mp4'), preprocessor: Optional[Union[enjoyn.preprocessor.Preprocessor, Callable]] = None, imwrite_kwds: Optional[Dict[str, Any]] = None, scratch_directory: Optional[pathlib.Path] = None, show_output: bool = True, ffmpeg_options: List[str] = ('-loglevel warning',))[source]#

Bases: enjoyn.animator.BaseAnimator

Used for animating images into a MP4 animation.

Parameters

ffmpeg_options – A tuple of options to pass to ffmpeg; see the [ffmpeg manual](https://ffmpeg.org/ffmpeg.html#Options) for a full list of available options.

preprocessor.py#

This module contains preprocessors that store functions to apply to each item of the animator.

class enjoyn.preprocessor.HoloViewsPreprocessor(*, func: Callable, args: Optional[List[Any]] = None, kwds: Optional[Dict[str, Any]] = None)[source]#

Bases: enjoyn.preprocessor.Preprocessor

Used to store a HoloViews function and its inputs.

apply_on(item: Any, validate_type: bool = True) → _io.BytesIO[source]#

Applies the func, along with its args and kwds, to the item; additionally, if a HoloViews type is returned, automatically save the plot to memory and close.

Parameters

  • item – The item to apply the function on.

  • validate_type – Whether to validate the preprocessed item is correct type.

Yields

The preprocessed item.

class enjoyn.preprocessor.MatplotlibPreprocessor(*, func: Callable, args: Optional[List[Any]] = None, kwds: Optional[Dict[str, Any]] = None)[source]#

Bases: enjoyn.preprocessor.Preprocessor

Used to store a matplotlib function and its inputs.

apply_on(item: Any, validate_type: bool = True) → _io.BytesIO[source]#

Applies the func, along with its args and kwds, to the item; additionally, if a matplotlib type is returned, automatically save the plot to memory and close.

Parameters

  • item – The item to apply the function on.

  • validate_type – Whether to validate the preprocessed item is correct type.

Yields

The preprocessed item.

class enjoyn.preprocessor.NullPreprocessor(*, func: Callable = <function NullPreprocessor.<lambda>>, args: Optional[List[Any]] = None, kwds: Optional[Dict[str, Any]] = None)[source]#

Bases: enjoyn.preprocessor.Preprocessor

Used to simplify internal code; does nothing.

apply_on(item: Any, validate_type: bool = True) → Union[pathlib.Path, str, _io.BytesIO, bytes, numpy.ndarray][source]#

Yields back the original item.

Parameters

  • item – The item to apply the function on.

  • validate_type – Whether to validate the preprocessed item is correct type.

Yields

The item.

class enjoyn.preprocessor.Preprocessor(*, func: Callable, args: Optional[List[Any]] = None, kwds: Optional[Dict[str, Any]] = None)[source]#

Bases: pydantic.main.BaseModel

Used to store a function and its inputs.

Parameters

  • func – The function to apply to each item of the animator; the function must accept the item to process as the first positional arg and must return either a Path, str, BytesIO, bytes, or np.ndarray type.

  • args – The additional arguments to pass to the function.

  • kwds – The additional keywords to pass to the function.

apply_on(item: Any, validate_type: bool = True) → Union[pathlib.Path, str, _io.BytesIO, bytes, numpy.ndarray][source]#

Applies the func, along with its args and kwds, to the item.

Parameters

  • item – The item to apply the function on.

  • validate_type – Whether to validate the preprocessed item is correct type.

Yields

The preprocessed item.

example.py#

This module contains examples that loads data and generates images.

class enjoyn.example.AirTemperatureExample(*, length: int = 2920, scratch_directory: Optional[pathlib.Path] = None, to_bytes_io: bool = False, **data)[source]#

Bases: enjoyn.example.Example

An example related to an xarray Dataset of air temperatures.

Parameters

  • length – The number of items in the data.

  • scratch_directory – The base directory to create the temporary directory for intermediary files.

load_data() → xarray.core.dataset.Dataset[source]#

Loads an xarray Dataset.

output_images() → List[Union[_io.BytesIO, pathlib.Path]][source]#

Outputs a list of images as BytesIO or Path.

plot_image(ds_sel: xarray.core.dataset.Dataset) → Union[_io.BytesIO, pathlib.Path][source]#

Plots an image from the data subset.

Parameters

data_subset – The subset dataset; should be shaped (x, y).

Returns

The output image as BytesIO or Path.

class enjoyn.example.Example(*, length: int = 1000, scratch_directory: Optional[pathlib.Path] = None, to_bytes_io: bool = False, **data)[source]#

Bases: pydantic.main.BaseModel

The base example class containing most of the common inputs and methods used in other examples inheriting from this. Note, this should not to be used directly.

Parameters

  • length – The number of items in the data.

  • scratch_directory – The base directory to create the temporary directory for intermediary files.

  • to_bytes_io – If True, save output to BytesIO; if False, save to disk.

cleanup_images()[source]#

Deletes the temporary directory.

size_of(file: Union[pathlib.Path, str])[source]#

Gets the size of a file in MBs.

time_run()[source]#

A context manager for tracking and printing the runtime.

Returns

The time it took to complete the run in seconds.

class enjoyn.example.RandomWalkExample(*, length: int = 1000, scratch_directory: Optional[pathlib.Path] = None, to_bytes_io: bool = False, **data)[source]#

Bases: enjoyn.example.Example

An example related to a numpy array of random coordinates.

Parameters

  • length – The number of items in the data.

  • scratch_directory – The base directory to create the temporary directory for intermediary files.

load_data() → numpy.ndarray[source]#

Loads a (self.length, 2) shaped array.

output_images() → List[Union[_io.BytesIO, pathlib.Path]][source]#

Outputs a list of images as BytesIO or Path.

plot_image(data_subset: numpy.ndarray) → Union[_io.BytesIO, pathlib.Path][source]#

Plots an image from the data subset.

Parameters

data_subset – The subset data array; should be shaped (n, 2).

Returns

The output image as BytesIO or Path.