open-atmos-jupyter-utils

Features

open-atmos-jupyter-utils is a Python package providing Jupyter notebook utility routines for:

• presenting matplotlib plots as either SVG vector graphics or animated GIFs, embedding them within the notebooks, and rendering correctly in GitHub's Rich Jupyter Notebook diffs
• save-as buttons below each figure (triggering Google-Drive downloads on Colab)
• execution of unmodified notebook code for automated testing (e.g., within pytest fixtures)
• pip-installation of external packages on Colab safeguarded against alterations of Google-shipped packages

Functions and Examples

• show_plot() - a drop-in replacement for matplotlib.pyplot.show() that displays figures inline as SVG vector graphics. The function also provides a download widget that allows users to download the figure as PDF or SVG. On Google Colab, the widget triggers a Google Drive download. Example:
  
• show_anim(plot_func: typing.Callable, frame_range: typing.Iterable) - a replacement for matplotlib.animation.FuncAnimation that displays inline animations in GIF format (which is compatible with GitHub rendering). It also provides a download widget to save the animation as a GIF file, with Colab support for Google Drive download. Example:
  
• show_gif(gif_file: TemporaryFile) - intended for displaying embedded GIF files as above, but for animations generated with packages other than matplotlib (e.g., PyVista)
  
• notebook_vars(notebook: pathlib.Path, plot: bool) - a function that executes notebook code and returns a dictionary of variables present in the notebook. This is particularly useful for setting up automated tests using pytest fixtures without any modification to the original notebooks. The plot flag controls if show_plot() calls within the notebook should be run or not. Example:
  
• pip_install_on_colab('package_a', 'package_b', ...) - a function that automates the installation of Python packages in Colab environments via pip (and ldconfig for system libraries). This ensures smooth setup for notebooks running on Colab.

Usage

For installation use:

pip install open-atmos-jupyter-utils

Then import inside Python project

import open_atmos_jupyter_utils as oaju

Documentation

Public API docs are maintained at: https://open-atmos.github.io/jupyter-utils/

Use Cases

open-atmos-jupyter-utils has been developed for and used in numerous Jupyter notebooks in PySDM, PyMPDATA and PyPartMC projects.