figpager

Matplotlib is a graphics library for Python that can save plots with various backends and single or multiple pages. FigPager is a wrapper class for those backends.

FigPager is similar to other third party Matplotlib packages that allow figure elements to be added such as a title block, border and logo. One example package is mpl-template.

The FigPager class reads layout specifications from an .ini file. FigPager handles drawing boxes, text, images and lines referenced in .ini files on a figure canvas. The class handles adding subplots, adding new pages in multipage backends and closing the figure.

Example output from tests\test_1.py

Install

Install using pip. figpager has been tested for Python 2.7, Python 3.7 and Python 3.8. See requirements.txt for dependencies.

pip install figpager

Usage

After install FigPager can be imported from figpager.

from figpager import FigPager

A FigPager instance is initialized with a paper size of A0-A10, B0-B10, letter, legal or ledger, the number of plot panels in a row as an integer and the number of plot panels as columns as an integer. 3 rows and 3 columns of panels for a figure of 3x3 is depicted below.

fp = FigPager(
        "letter",
        3,
        3,
    )

Additional keywords provide further functionality. See the code for all keywords.

fp = FigPager(
        "letter",
        3,
        2,
        layout="Report",
        outfile=.\out.pdf,
        orientation="portrait",
        height_ratios=[1, 1, 2],
        overwrite=True,
        transparent=True,
    )

with blocks are also supported with no need for fp.close()

with FigPager("letter", 3, 2, layout="Report", outfile=.\out.pdf,
        orientation="portrait", height_ratios=[1, 1, 2],
        overwrite=True, transparent=True) as fp:

Example layout .ini files can be found in the package under page_layout.

FigPager has options to add subplots. See the code for all keywords.

ax0 = fp.add_subplot()

FigPager also has add page options. In backends that don't support multipage a zero padded number is added as a suffix to the file name.

The example below specifies the number of rows and columns, the orientation and height ratios. See the code for all keywords.

fp.add_page(
                nrows=3, ncols=2, orientation="portrait", height_ratios=[1, 1, 2]
           )

FigPager options read from an .ini file can be updated via the instance's config. The syntax is config[section][subsection][option] = value.

fp.config['Text']['Document Title']['text']

Finally, FigPager instance can be closed following the example below.

fp.close()

See the test code under tests for example code.

Development / Testing

Submit issues and PRs through GitHub. Testing is done with tox. pytest, black and isort are run against code.

License

figpager is released under the MIT license. See LICENSE.md for details.