Introduction

nbfigtulz tries to be a lightweight annotation to your already existing routines to render and display images in JupyterLab:

import nbfigtulz as ftl
import numpy as np
import matplotlib.pyplot as plt

@ftl.with_context
def make_fig(x, *, file_name):
  fig, ax = plt.subplots()
  ax.plot(x, np.sin(x))

  return ftl.save_fig(fig, file_name)

make_fig(np.linspace(0, 50, 500), file_name='test')

By annotating with nbfigtulz.figtools.with_context make_fig is wrapped with a context manager that temporally overwrites, e.g., matplotlib.rcParams. This configuration is then used by nbfigtulz.figtools.save_fig to save fig in the PNG and PGF format. (Note that our annotation also temporally sets the backend to "pgf", i.e., calling make_fig without the annotation might only generate a PNG file.) The return value of nbfigtulz.figtools.save_fig is a nbfigtulz.thumbnail.Thumbnail instance that is drawn to your notebook if its __repr__ overload is called. This thumbnail is clickable & downloadable, is inlined into the notebook and thus will be displayed without needing to re-run the notebook!

The implicitly used defaults such as the image size and resolution, or the root directory where the generated images are stored, can be changed globally in nbfigtulz.config.config:

ftl.config['img_dir'] = '/tmp/my_fancy_dump_location/'
flt.config['dpi'] = 150

Note that nbfigtulz will not try to create the image directory! It is your obligation to do this before nbfigtulz.figtools.save_fig is called for the first time.

If needed, thumbnails can be arranged in a grid by using nbfigtulz.figtools.img_grid. In the following example we generate 3 plots and arrange them in a 2x2 grid (the last cell is empty):

x = np.linspace(0, 50, 500)
ftl.grid([make_fig(x * i, f'test{i}') for i in range(1, 4)], n_columns=2)

Technically, nbfigtulz.figtools.img_grid generates a table in HTML where each image stays separately clickable and downloadable.

Installation

Releases are available as wheel packages for macOS, Windows and Linux on PyPI: pypi.org/project/nbfigtulz/. If you prefer to build from source visit our GitHub repository: github.com/avitase/nbfigtulz.

Examples

We provide a short notebook with a few examples on our GitHub page: example/notebook.ipynb.