alike

Overview

alike compares objects on type, length, and attributes. Recursive structures are compared element by element. Language objects and functions are compared specially because the concept of a value within those is more complex (e.g., is the + in x + y just a value?).

We will defer discussion of attribute comparison to the attributes section.

Length Comparison

Objects must be the same length to be alike, unless the template (target) is zero length, in which case the object may be any length. Environments are an exception: we only require that all the elements present in target be present in current. Also, note that calls to ( are ignored in language objects, which may affect length computation.

Type Comparison

Type comparison is done on type (i.e. the typeof) with some adjustments to better align comparisons to “percieved” types as opposed to internal storage types.

alike(1L, 1)     # `1` is not technically integer, but we treat it as such

[1] TRUE

alike(1L, 1.1)   # 1.1 is not integer-like

[1] "`1.1` should be type \"integer-like\" (is \"double\")"

alike(1.1, 1L)   # integers can match numerics

[1] TRUE

stopifnot(length(x) == 1L && (is.integer(x) || is.numeric(x) && floor(x) == x))
stopifnot(alike(integer(1L), x))

Recursive Objects

alike will recurse through lists (and by extension data frames), pairlists, expressions, and environments and will check pairwise alikeness between the corresponding elements of the target and current objects.

Environments have slightly different comparison rules in two respects:

• only the elements present in the template are checked, so current may have additional items
• if the template is the global environment, then current must be too (this is because the global environment is often littered with many objects, and explicitly comparing it to another environment could be computationally expensive)

NULL elements within templates in recursive objects are considered undefined and as such act like wildcards:

## two NULLs match two length list
alike(list(NULL, NULL), list(1:10, letters))

[1] TRUE

## but not three length list
alike(list(NULL, NULL), list(1:10, letters, iris))

[1] "`length(list(1:10, letters, iris))` should be 2 (is 3)"

Note that top level NULLs do not act as wildcards:

alike(NULL, 1:10)                   # NULL only matches NULL

[1] "`1:10` should be `NULL` (is \"integer\")"

Treating NULL inconsistently depending on whether it is nested or not is a compromise designed to make alike a better fit for argument validation because arguments that are NULL by default are fairly common.

alike will check for self-referential loops in nested environments and prevent infinite recursion. If you somehow introduce a self-referential structure in a template without using environments then alike will get stuck in an infinite recursion loop.

We are currently considering adding new comparison modes for lists that would allow for checks more similar to environments (see #29).

Language Objects, Formulas, and Functions

Alikeness for these types of objects is a little harder to define. We have settled on somewhat arbitrary semantics, though hopefully they are intuitive. These may change in the future as we gain experience using alike with these types of objects. This is particularly true of functions.

Language objects are also compared recursively, but alikeness has a slightly different meaning for them:

alike(quote(sum(a, b)), quote(sum(x, y)))   # calls are consistent

[1] TRUE

alike(quote(sum(a, b)), quote(sum(x, x)))   # calls are inconsistent

[1] "`quote(sum(x, x))[[3]]` should not be `x`"

alike(quote(mean(a, b)), quote(sum(x, y)))  # functions are different

[1] "`quote(sum(x, y))[[1]]` should be a call to `mean` (is a call to `sum`)"

fun <- function(a, b, c) NULL
alike(quote(fun(p, q, p)), quote(fun(y, x, x)))

[1] "`quote(fun(y, x, x))[[4]]` should be `y` (is `x`)"

# `match.call` re-orders arguments
alike(quote(fun(p, q, p)), quote(fun(b=y, x, x)))

[1] TRUE

str(one.arg.tpl <- as.call(list(NULL, NULL)))

 language NULL(NULL)

alike(one.arg.tpl, quote(log(10)))

[1] TRUE

alike(one.arg.tpl, quote(sd(runif(20))))

[1] TRUE

alike(one.arg.tpl, quote(log(10, 10)))

[1] "`quote(log(10, 10))` should have 1 arguments (has 2)"

alike(y ~ x ^ 2, a ~ b ^ 2)

[1] TRUE

alike(y ~ x ^ 2, a ~ b ^ 3)

[1] "`(a ~ b^3)[[3]][[3]]` should have identical constant values"

alike(print, print.default)   # print can be the generic for print.default

[1] TRUE

alike(print.default, print)   # but not vice versa

[1] "`print` should have argument `digits` after argument `x`"

S4 and R5 (RC Objects)

S4 and RC objects are considered alike if current inherits from class(target). Since these objects embed structural information in their definitions alike relies on class alone to establish alikeness.

Pointer Objects

Objects of the following types are actually references to specific memory locations:

• External Pointers
• Weak References
• Byte codes

These are typically attached as attributes to other objects that contain the information required to establish alikeness (e.g. data.table, byte-compiled functions), so we only check their type.

Normal Attributes

Much of the structure of an object is determined by attributes. alike recursively compares object attributes and requires them to be alike, unless the attribute is a special attribute or an environment. Environments within attributes in the template must be matched by an environment, but nothing is checked about the environments to avoid expensive computations on objects that commonly include environments in their attributes (e.g. formulas); note this is different than the treatment of environments as actual objects.

Only attributes present in the template object are checked:

alike(structure(logical(1L), a=integer(3L)), structure(TRUE, a=1:3, b=letters))

[1] TRUE

alike(structure(TRUE, a=1:3, b=letters), structure(logical(1L), a=integer(3L)))

[1] "`structure(logical(1L), a = integer(3L))` should have attribute \"b\""

Attributes present in current but missing in target may be anything at all.

Special Attributes

alike(setNames(integer(), character()), 1:3)

[1] "`1:3` should have attribute \"names\""

alike(setNames(integer(), character()), c(a=1, b=2, c=3))

[1] TRUE

alike(setNames(integer(3), c("", "", "Z")), c(a=1, b=2, c=3))

[1] "`names(c(a = 1, b = 2, c = 3))[3]` should be \"Z\" (is \"c\")"

alike(setNames(integer(3), c("", "", "Z")), c(a=1, b=2, Z=3))

[1] TRUE

mx.tpl <- matrix(integer(), ncol=3)                # partially specified matrix
alike(mx.tpl, matrix(sample(1:12), nrow=4))

[1] TRUE

alike(mx.tpl, matrix(sample(1:12), nrow=3))        # wrong number of columns

[1] "`matrix(sample(1:12), nrow = 3)` should have 3 columns (has 4)"

str(mx.tpl)    # notice 0 for 1st dimension

 int[0 , 1:3] 

mx.tpl <- matrix(integer(), ncol=3, dimnames=list(row.id=NULL, c("R", "G", "")))
mx.cur <- matrix(sample(0:255, 12), ncol=3, dimnames=list(row.id=1:4, rgb=c("R", "G", "Blue")))
mx.cur2 <- matrix(sample(0:255, 12), ncol=3, dimnames=list(1:4, c("R", "G", "b")))

alike(mx.tpl, mx.cur)

[1] TRUE

alike(mx.tpl, mx.cur2)

[1] "`dimnames(mx.cur2)` should have attribute \"names\""

names(dimnames(mx.tpl))

[1] "row.id" ""      

tpl <- structure(TRUE, class=c("a", "b", "c"))
cur <- structure(TRUE, class=c("x", "a", "b", "c"))
cur2 <- structure(TRUE, class=c("a", "b", "c", "x"))

alike(tpl, cur)

[1] TRUE

alike(tpl, cur2)

[1] "`class(cur2)[2]` should be \"a\" (is \"b\")"

From The Ground Up

You can always create your own templates by manually building R structures:

int.scalar <- integer(1L)
int.mat.2.by.4 <- matrix(integer(), 2, 4)
# A df without column names
df.chr.num.num <- structure(
  list(character(), numeric(), numeric()), class="data.frame"
)

Abstracting Existing Structures

Alternatively, you can start with a known structure, and abstract away the instance-specific details. For example, suppose we are sending sample collectors out on the field to record information about iris flowers:

iris.tpl <- iris[0, ]
alike(iris.tpl, iris.sample.1)  # make sure they submit data correctly

Or equivalently:

iris.tpl <- abstract(iris)

abstract is an S3 generic defined by alike along with methods for common objects. abstract primarily sets the length of atomic vectors to zero:

abstract(list(c(a=1, b=2, c=3), letters))

[[1]]
named numeric(0)

[[2]]
character(0)

and also abstracts the dim, dimnames, and tsp attributes if present. Other attributes are left untouched unless a specific abstract method exists for a particular object that also modifies attributes. One example of such a method is abstract.lm, and it does some minor tweaking to the base abstractions to allow us to match models produced by lm:

df.dummy <- data.frame(x=runif(3), y=runif(3), z=runif(3))
mdl.tpl <- abstract(lm(y ~ x + z, df.dummy))
# TRUE, expecting bi-variate model
alike(mdl.tpl, lm(Sepal.Length ~ Sepal.Width + Petal.Width, iris))

[1] TRUE

alike(mdl.tpl, lm(Sepal.Length ~ Sepal.Width, iris))

[1] "`lm(Sepal.Length ~ Sepal.Width, iris)$terms[[3]]` should be a call to `+` (is \"symbol\")"

The error message is telling us that at index "terms" (i.e. lm(Sepal.Length ~ Sepal.Width, iris)$terms) alike was expecting a call to + instead of a symbol (i.e Sepal.Width + <somevar> instead of Sepal.Width). The message could certainly be more eloquent, but with a little context it should provide enough information to figure out the problem.

Sample Timings

We have gone to great lengths to make alike fast so that it can be included in other functions without concerns for what overhead:

type_and_len <- function(a, b)
  typeof(a) == typeof(b) && length(a) == length(b)  # for reference

bench_mark(times=1e4,
  identical(rivers, rivers),
  alike(rivers, rivers),
  type_and_len(rivers, rivers)
)

Mean eval time from 10000 iterations, in microseconds:
  identical(rivers, rivers)     ~  0.4
  alike(rivers, rivers)         ~  1.8
  type_and_len(rivers, rivers)  ~  1.1

While alike is slower than identical and the comparable bare bones R function, it is competitive with a bare bones R function that checks types and length. As objects grow more complex, identical will obviously pull ahead, though alike should be sufficiently fast for most applications:

bench_mark(times=1e4,
  identical(mtcars, mtcars),
  alike(mtcars, mtcars)
)

Mean eval time from 10000 iterations, in microseconds:
  identical(mtcars, mtcars)  ~  0.3
  alike(mtcars, mtcars)      ~  8.6

In the above example, we are comparing the data frames, their attributes, and the 11 columns individually.

Keep in mind that the complexity of the alike comparison is driven by the complexity of the template, not the object we are checking, so we can always manage the expense of the alike evaluation.

Comparisons that succeed will be substantially faster than comparisons that fail as the construction of error messages is non-trivial and we have prioritized optimization in the success case.

Language object comparison is relatively slow. We intend to optimize this some day.

Templates with large numbers of attributes (e.g. > 25) may scale non-linearly. We intend to optimize this some day, though in our experience objects with that many attributes are rare (note having multiple objects each with a handful attributes nested in recursive structures is not a problem).

Large objects will be slower to evaluate. Let us revisit the lm example, though this time we compare our template to itself to ensure that the comparisons succeed for alike, all.equal, and identical:

mdl.tpl <- abstract(lm(y ~ x + z, data.frame(x=runif(3), y=runif(3), z=runif(3))))
# compare mdl.tpl to itself to ensure success in all three scenarios
bench_mark(
  alike(mdl.tpl, mdl.tpl),
  all.equal(mdl.tpl, mdl.tpl),   # for reference
  identical(mdl.tpl, mdl.tpl)
)

Mean eval time from 1000 iterations, in microseconds:
  alike(mdl.tpl, mdl.tpl)      ~    91
  all.equal(mdl.tpl, mdl.tpl)  ~  1071
  identical(mdl.tpl, mdl.tpl)  ~     1

Even with template as large as lm results (check str(mdl.tpl)) we can evaluate alike thousands of times before the overhead becomes noticeable.

Pre-defining Templates

Some fairly innocuous R expressions carry substantial overhead. Consider:

df.tpl <- data.frame(a=integer(), b=numeric())
df.cur <- data.frame(a=1:10, b=1:10 + .1)

bench_mark(
  alike(df.tpl, df.cur),
  alike(data.frame(integer(), numeric()), df.cur)
)

Mean eval time from 1000 iterations, in microseconds:
  alike(df.tpl, df.cur)                     ~    5
  alike(data.frame(integer(), numeric())..  ~  193

data.frame is a particularly slow constructor, but in general you are best served by defining your templates (including calls to abstract) outside of your function so they are created on package load rather than every time your function is called.

alike as an S3 generic

alike is not currently an S3 generic, but will likely one in the future provided we can create an implementation with and acceptable performance profile.