Type: Package
Title: Graphical Difference Testing
Version: 0.2-5
Author: Paul Murrell
Maintainer: Paul Murrell <paul@stat.auckland.ac.nz>
Description: Functions for performing graphical difference testing. Differences are generated between raster images. Comparisons can be performed between different package versions and between different R versions.
Imports: grDevices, utils, tools, parallel, magick, pdftools
Suggests: gridBezier, grImport, metapost, ssh, stevedore
URL: https://github.com/pmur002/, https://stattech.wordpress.fos.auckland.ac.nz/2020/01/06/2020-01-visual-testing-for-graphics-in-r/
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
NeedsCompilation: no
Packaged: 2023-03-08 23:06:29 UTC; pmur002
Repository: CRAN
Date/Publication: 2023-03-08 23:50:02 UTC

Names of Files Showing Differences

Description

List all files that show differences between control and test output (as red pixels).

Usage

diffFiles(x)

Arguments

x

A "gdiffComparison" object, as created by gdiff or gdiffCompare.

Value

A character vector of file names (with paths).

Author(s)

Paul Murrell

See Also

gdiff and gdiffCompare.

Examples

f1 <- function() plot(1)
f2 <- function() plot(2)

result <- gdiff(list(control=f1, test=f2), name="f",
                controlDir=file.path(tempdir(), "Control"),
                testDir=file.path(tempdir(), "Test"),
                compareDir=file.path(tempdir(), "Compare"))
result
diffFiles(result)

Generate and Compare Control and Test Output

Description

Generate a set of "control" graphical output files in one directory, a set of "test" graphical output files in another directory, and compare the two sets of output files (possibly generating "compare" graphical output of the differences in a third directory).

Usage

gdiff(x, ...)
## S3 method for class 'function'
gdiff(x, name=deparse(substitute(x)), ...)
## S3 method for class 'list'
gdiff(x, name, ...)

Arguments

x

Either a function, or a named list of functions (with names control and test).

name

A name to be used for output files.

...

Further arguments, currently including:

controlDir, testDir, compareDir

The names of the directories where output is produced.

clean

A logical indicating whether the output directories should be emptied. Can also be a list of logicals with names control, test, and compare.

compare

A logical indicating whether to perform the comparison step.

device

A specification of the graphics device to use for output; see gdiffDevice. Can also be a list of graphics devices.

session

A specification of the R session to use for output; see gdiffSession. Can also be a list of sessions with names control and test.

ncpu

How many cpus to employ when generating output.

Value

A "gdiffComparison" object, which is a list containing information about the output files generated and the differences detected.

Author(s)

Paul Murrell

See Also

gdiffExamples, gdiffPackage, gdiffOutput, and gdiffCompare.

Examples

f <- function() plot(1)

gdiff(f,
      controlDir=file.path(tempdir(), "Control"),
      testDir=file.path(tempdir(), "Test"),
      compareDir=file.path(tempdir(), "Compare"))

Compare Control and Test Output

Description

Compare a set of "control" graphical output files in one directory with a set of "test" graphical output files in another directory (possibly generating "compare" graphical output of the differences in a third directory).

Usage

gdiffCompare(controlDir, testDir, compareDir, ...)

Arguments

controlDir, testDir, compareDir

The names of the directories where output is produced.

...

Further arguments, not currently used.

Value

A "gdiffComparison" object, which is a list containing information about the output files generated and the differences detected.

Author(s)

Paul Murrell

See Also

gdiff, and gdiffOutput.

Define a Graphics Device for Generating Output

Description

Define the device to be used for generating graphical output files. There are several predefined graphical devices, e.g., pngDevice(), and further devices can be defined using gdiffDevice().

Usage

pngDevice(...)
pdfDevice(...)
postscriptDevice(...)
cairo_pdf_device(suffix=".cairo.pdf", ...)

gdiffDevice(name, suffix=name, open,
            close=function(dir, name) dev.off())

Arguments

name

A name for the device (used by default for naming output files).

suffix

A suffix to be used for output files.

open

A function that opens a graphics device; this should open the device in such a way that multiple pages of graphical output will produce multiple files.

close

A function that closes the graphics device.

...

Further arguments typically used within the function that opens the device.

Value

A "gdiffDevice" object, which may be used as the device argument to gdiff.

Author(s)

Paul Murrell

See Also

gdiff.

Examples

f <- function() plot(1)

gdiff(f, device=pdfDevice(),
      controlDir=file.path(tempdir(), "Control"),
      testDir=file.path(tempdir(), "Test"),
      compareDir=file.path(tempdir(), "Compare"))

Generate and Compare Control and Test Output for Function Examples

Description

Generate a set of "control" graphical output files in one directory, a set of "test" graphical output files in another directory, and compare the two sets of output files (possibly generating "compare" graphical output of the differences in a third directory).

Usage

gdiffExamples(fun, ...)
## S3 method for class 'function'
gdiffExamples(fun, name=NULL, ...)
## S3 method for class 'character'
gdiffExamples(fun, name=fun, ...)

Arguments

fun

Either a function or the name of a function.

name

A name to be used for output files.

...

Further arguments; see gdiff.

Value

A "gdiffComparison" object, which is a list containing information about the output files generated and the differences detected.

Author(s)

Paul Murrell

See Also

gdiff and gdiffPackage.

Examples


gdiffExamples(plot,
              controlDir=file.path(tempdir(), "Control"),
              testDir=file.path(tempdir(), "Test"),
              compareDir=file.path(tempdir(), "Compare"))

Generate Output Files from Function Examples

Description

Generate a set of graphical output files by running the examples from the help page for a function.

Usage

gdiffExamplesOutput(fun, dir, ...)
## S3 method for class 'function'
gdiffExamplesOutput(fun, dir, name=NULL, ...)
## S3 method for class 'character'
gdiffExamplesOutput(fun, dir, name=fun, ...)

Arguments

fun

Either a function or the name of a function.

dir

The name of a directory in which to create output files.

name

A name to be used for output files.

...

Further arguments; see gdiffOutput.

Value

A character vector containing the names (and paths) of all output files that were generated.

Author(s)

Paul Murrell

See Also

gdiffOutput and gdiffPackageOutput.

Examples


gdiffExamplesOutput(plot, dir=file.path(tempdir(), "Control"))

Generate Graphical Output

Description

Generate a set of graphical output files.

Usage

gdiffOutput(x, dir, ...)
## S3 method for class 'function'
gdiffOutput(x, dir, name=deparse(substitute(x)), ...)

Arguments

x

A function.

dir

The name of a directory in which to create output files.

name

A name to be used for output files.

...

Further arguments, currently including:

clean

A logical indicating whether the output directories should be emptied. Can also be a list of logicals with names control, test, and compare.

device

A specification of the graphics device to use for output; see gdiffDevice. Can also be a list of graphics devices.

session

A specification of the R session to use for output; see gdiffSession. Can also be a list of sessions with names control and test.

ncpu

How many cpus to employ when generating output.

Value

A character vector containing the names (and paths) of all output files that were generated.

Author(s)

Paul Murrell

See Also

gdiffExamplesOutput, gdiffPackageOutput, and gdiff.

Examples

f <- function() plot(1)

gdiffOutput(f, dir=file.path(tempdir(), "Control"))

Generate and Compare Control and Test Output for a Package

Description

Generate a set of "control" graphical output files in one directory, a set of "test" graphical output files in another directory, and compare the two sets of output files (possibly generating "compare" graphical output of the differences in a third directory).

Usage

gdiffPackage(pkg, ...)

Arguments

pkg

The name of a package.

...

Further arguments; see gdiff.

Value

A "gdiffComparison" object, which is a list containing information about the output files generated and the differences detected.

Author(s)

Paul Murrell

See Also

gdiff and gdiffExamples.

Generate Output Files from Function Package

Description

Generate a set of graphical output files by running the examples from the help page for a function.

Usage

gdiffPackageOutput(pkg, dir, ...)

Arguments

pkg

The name of a package.

dir

The name of a directory in which to create output files.

...

Further arguments; see gdiffOutput.

Value

A character vector containing the names (and paths) of all output files that were generated.

Author(s)

Paul Murrell

See Also

gdiffOutput and gdiffExamplesOutput.

Define an R Session for Generating Output

Description

Define the R session to be used for generating graphical output files. There are several predefined sessions, e.g., currentSession(), and further sessions can be defined using gdiffSession().

Usage

currentSession(libPaths=NULL)
localSession(libPaths=NULL,
             Rpath=file.path(R.home("bin"), "Rscript"),
             ...)
remoteSession(remote, ...)
## S3 method for class 'character'
remoteSession(remote, libPaths=NULL, Rpath="Rscript", ...)
## S3 method for class 'cluster'
remoteSession(remote, libPaths=NULL, user=NULL, ...)
dockerSession(image, volumes=NULL, env=NULL, network="bridge",
              libPaths=NULL, Rpath="Rscript", ...)

gdiffSession(class, ...)
gdiffGenerateOutput(codeFun, dir, device, clean, ncpu)

Arguments

libPaths

One or more paths to installed R packages.

Rpath

A path to an Rscript binary.

remote

Either the name of a host or a cluster object (as produced by parallel::makeCluster()).

user

A user name.

image

The name of a Docker image.

volumes

A character vector of volumes to mount on the container (of the form /path/on/host:/path/on/container/).

env

A character vector of environment variable settings for the container (of the form VAR=value).

network

A character vector describing the network connection for the container.

class

A unique class for a new type of R session.

...

Further arguments for future methods.

codeFun, dir, device, clean, ncpu

Arguments passed to generateOutput methods that can be passed on to gdiffGenerateOutput.

Details

When defining a new session, gdiffSession() is just used to establish a new class. The important thing to do is to provide a generateOutput method for that class. Typically, this method will call gdiffGenerateOutput().

Value

A "gdiffSession" object, which may be used as the session argument to gdiff.

Author(s)

Paul Murrell

See Also

gdiff.

Examples

f <- function() plot(1)

gdiff(f, session=currentSession(),
      controlDir=file.path(tempdir(), "Control"),
      testDir=file.path(tempdir(), "Test"),
      compareDir=file.path(tempdir(), "Compare"))

Compare Two PDF Files

Description

Check whether two PDF files have the same content, ignoring some details like creation time and modification time.

Usage

samePDF(file1, file2)

Arguments

file1, file2

Names of PDF files to compare.

Details

This function will compare any two files, byte by byte, but if a file is a PDF file that was generated by R, it will discard the file header, which may contain differences that do not matter, such as the creation date.

Value

A logical value.

Author(s)

Paul Murrell

Examples

f1 <- tempfile(fileext=".pdf")
f2 <- tempfile(fileext=".pdf")
pdf(f1)
plot(1)
dev.off()
pdf(f2)
plot(2)
dev.off()
samePDF(f1, f1)
samePDF(f1, f2)