pdf_utils

class HierarchicalPlotPDF(out_pdf_path: Path | str | None, individual_plot_directory: Path | str | None = None)

A context manager for saving multiple plots to a PDF file, with a hierarchical outline.

Example

>>> with HierarchicalPlotPDF('out.pdf') as pdf:
...     plt.plot([1, 2, 3])
...     pdf.savefig('plot1')
...     plt.scatter([1, 2, 3], [4, 5, 6])
...     pdf.savefig('scatters/scatter1')
...     plt.scatter([2, 3, 4], [5, 6, 7])
...     pdf.savefig('scatters/scatter2')

Will save three plots to a PDF file out.pdf, with the following outline:

• plot1

• scatters

  • scatter1

  • scatter2

__enter__() → HierarchicalPlotPDF

Enter the context manager.

Create a temporary directory if individual_plot_directory is None.

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the context manager.

Save the individual plots to a PDF file, and clean up the temporary directory.

__init__(out_pdf_path: Path | str | None, individual_plot_directory: Path | str | None = None) → None

Create a new HierarchicalPlotPDF context manager.

Parameters:

• out_pdf_path – The path to the output PDF file. If None is specified, there no pdf with all plots will be compiled.

• individual_plot_directory – The path to the directory to save the individual plots to. If not specified, a temporary directory next to the out_pdf_path will be used.

savefig(path: str, **savefig_kwargs) → None

Save the current figure to a PDF file, at the specified path relative to the individual_plot_directory.

Parameters:

• path – The path to save the figure to, relative to the individual_plot_directory.

• savefig_kwargs – Additional keyword arguments to pass to matplotlib.pyplot.savefig().

add_bookmark_dict(bookmark_dict: dict, in_pdf_path: str, out_pdf_path: str = None) → None

Add bookmarks to a PDF file, as specified by a dictionary.

Parameters:

• bookmark_dict –

  A (possibly nested) dictionary specifying the bookmarks to add to the PDF. The keys are the titles of the bookmarks, and the values are either integers (page numbers) or tuples of (int, dict), where the first element is the page number and the second element is a dictionary specifying the sub-bookmarks. Example:

  {
      'Chapter 1': 1,
      'Chapter 2': 2,
      'Chapter 3': (3, {
          'Section 3.1': 3,
          'Section 3.2': 4,
          'Section 3.3': (5, {
              'Subsection 3.3.1': 5,
              'Subsection 3.3.2': 6,
          }),
      }),
  }
  

• in_pdf_path – The path to the input PDF file.

• out_pdf_path – The path to the output PDF file. If not specified, the input PDF file will be overwritten.

directory_to_pdf_with_outline(directory: str, out_pdf_path: str = None, order: str = 'time') → str

Convert a (possibly nested) directory containing pdfs (e.g. matplotlib plots) to a single PDF file, with an outline based on the directory structure.

Parameters:

• directory – The path to the directory to convert to a PDF file.

• out_pdf_path – The path to the output PDF file. If not specified, the output will be saved next to the input directory.

• order – The order to sort the files and directories in. Can be either “time” or “name”. Defaults to “time”.

Returns:

The path to the output PDF file.

Return type:

str