A Guide to Using Compare Functions in review

Source: vignettes/compare-tools.Rmd

This vignette provides detailed documentation and usage examples for the compare functions in the review package: compareFigures() and compareTables(). These functions facilitate a visual comparison of different versions of outputs (e.g., figures and tables).

Table of Contents

  • Use cases:
    • Comparing versions of the same file
    • Comparing two different files
  • compareFigures(): Generates a document showing two versions of a list of figures (PDF or PNG).
  • compareTables(): Generates a document showing two versions of a list of tables (TeX).

Use cases

compareFigures() and compareTables() can generate two types of comparisons:

  • Comparisons of two versions of the same file (leveraging version control).
  • Comparisons of two different files.

Both functions have a .path_previous argument. If left empty, a document will be generated comparing the current version of the figure/table to the most recent version. If the user provides a file path to the .path_previous argument, then the document will show a comparison of the two figures/tables.

Additionally, users can generate these comparisons on either a single file or a directory of files. If a directory is given, the document will contain all relevant figures/tables in that directory.

Setup

For the sections below, the following project structure is used. Figures are stored in deliv/figure, and tables are stored in deliv/table.

project/
│
├── deliv/
│   ├── figure/
|       ├── example-pdf1.pdf
|       ├── example-pdf2.pdf
|       ├── example-pdf3.pdf
|       └── example-png1.png
│   ├── table/
│       ├── example-table-1.tex
│       └── example-table-long-1.tex

compareFigures()

The compareFigures() function generates an HTML page with a visual comparison between two versions of a file. If a directory is provided, all version-controlled figures will be included in the HTML page.

Usage

Compare versions of a single file 
compareFigures(.path_current = "deliv/figure/example-pdf1.pdf")

Output:

Output of compareFigures(): Left box shows the version of the file currently checked into the repository. Right box shows version of the figure on disk.
Output of compareFigures(): Left box shows the version of the file currently checked into the repository. Right box shows version of the figure on disk.
Compare two local figures 
compareFigures(
  .path_current = "deliv/figure/example-pdf3.pdf",
  .path_previous = "deliv/figure/example-pdf2.pdf"
)

Output:

Output of compareFigures(): Left box shows the current version of deliv/figure/example-pdf2.pdf. Right box shows the current version of deliv/figure/example-pdf3.pdf. When multi-page figures are being compared, users are able to scroll through all pages in the PDF.
Output of compareFigures(): Left box shows the current version of deliv/figure/example-pdf2.pdf. Right box shows the current version of deliv/figure/example-pdf3.pdf. When multi-page figures are being compared, users are able to scroll through all pages in the PDF.

compareTables()

The compareTables() function generates an HTML page with a visual comparison between two versions of a table. If a directory is provided, all version-controlled tables will be included in the HTML page.

Usage

Compare versions of a single table 
compareTables(.path_current = "deliv/table/example-table-1.tex")

Output:

Output of compareTables(): Left box shows the version of the file currently checked into the repository. Right box shows version of the table on disk.
Output of compareTables(): Left box shows the version of the file currently checked into the repository. Right box shows version of the table on disk.
Compare two local tables

Similar to compareFigures(), users can compare two different tables with the following code:

compareTables(
  .path_current = "deliv/table/example-table-1.tex",
  .path_previous = "deliv/table/example-table-long-1.tex"
)

Additional Notes

  • Customization: Users can customize the display of comparisons by adjusting the .side_by_side parameter as needed.
  • Supported Formats: compareFigures() supports PDF and PNG formats, while compareTables() supports TeX files only.