R all.equal 測試兩個對象是否(幾乎)相等

說明

all.equal(x, y)是一個比較的實用程序R對象x和y測試“接近平等”。如果不同，仍然進行一定程度的比較，並返回差異報告。不使用all.equal直接在if表達式——或者使用isTRUE(all.equal(....))或者identical如果合適的話。

用法

all.equal(target, current, ...)

## S3 method for class 'numeric'
all.equal(target, current,
          tolerance = sqrt(.Machine$double.eps), scale = NULL,
          countEQ = FALSE,
          formatFUN = function(err, what) format(err),
          ..., check.attributes = TRUE, giveErr = FALSE)

## S3 method for class 'list'
all.equal(target, current, ...,
          check.attributes = TRUE, use.names = TRUE)

## S3 method for class 'environment'
all.equal(target, current, all.names = TRUE,
          evaluate = TRUE, ...)

## S3 method for class 'function'
all.equal(target, current, check.environment=TRUE, ...)

## S3 method for class 'POSIXt'
all.equal(target, current, ..., tolerance = 1e-3, scale,
          check.tzone = TRUE)


attr.all.equal(target, current, ...,
               check.attributes = TRUE, check.names = TRUE)

參數

target	R對象。
current	其他R對象，與target.
...	不同方法的進一步論證，特別是以下兩種方法，用於數值比較：
tolerance	數字\ge 0。不報告小於tolerance 的差異。默認值接近 1.5e-8 。
scale	NULL 或數字 > 0，通常長度為 1 或 length(target) 。查看具體信息'。
countEQ	邏輯指示在計算平均(絕對或相對)差異時是否應計算 target == current 案例。默認值 FALSE 在 target 和 current 僅在少數地方不同的情況下可能會產生誤導；請參閱廣泛的示例。
formatFUN	兩個參數的 function， err ，相對、絕對或縮放誤差，以及 what ，指示錯誤類型的字符串；例如，可以用於以不同的方式格式化相對和絕對誤差。
check.attributes	邏輯指示是否應比較 target 和 current(名稱除外)的 attributes。
giveErr	logical 指示結果是否應包含數字錯誤作為 "err" 屬性。
use.names	邏輯指示 list 比較是否應按名稱(如果匹配)而不是整數索引報告不同的組件。請注意，它位於 ... 之後，因此必須使用其全名來指定。
all.names	邏輯傳遞給ls，指示環境中是否還應考慮“hidden”對象。
evaluate	對於 environment 方法：logical 指示是否“應強製承諾”，即通常評估形式函數參數以進行比較。如果為 false，則僅檢查兩個環境中對象的 names 是否相等。
check.environment	邏輯上要求函數的 environment() 也應該進行比較。在意外情況下，您可能需要設置check.environment=FALSE，例如比較兩個nls()擬合時。
check.tzone	邏輯指示是否應比較 target 和 current 的 "tzone" 屬性。
check.names	邏輯指示是否應比較 target 和 current 的 names(.)。

細節

all.equal 是一個通用函數，在 target 參數上調度方法。要查看可用的方法，請使用 methods("all.equal") ，但請注意，默認方法也會執行一些調度，例如對邏輯目標使用原始方法。

請記住，... 後麵的參數必須由(未縮寫的)名稱指定。不建議在 ... 中傳遞未命名參數，因為這些參數將匹配不同方法中的不同參數。

scale = NULL(默認值)的數值比較通常采用相對差異尺度，除非 target 值接近零或無窮大。具體來說，比例計算為 target 的平均絕對值。如果該比例是有限的並且超過 tolerance ，則表示相對於它的差異；否則，使用絕對差異。請注意，此比例和所有進一步的步驟僅針對 target 不是 NA 且不同於 current 的向量元素進行計算。如果countEQ 為真，則在確定“sample” 大小時將計算相等和NA 情況。

如果 scale 是數字(且為正數)，則在按 scale 縮放(除)後進行絕對比較。請注意，如果所有比例都接近 1(具體而言，在 1e-7 內)，則差異仍報告為絕對比例。

對於複數 target ，使用差值的模 ( Mod )：調用 all.equal.numeric ，因此參數 tolerance 和 scale 可用。

list 方法遞歸地比較 target 和 current 的組件，傳遞所有其他參數，隻要兩者都是 “list-like”，即滿足 is.vector 或 is.list 。

environment 方法通過 list 方法工作，並且也用於引用類(除非定義了特定的 all.equal 方法)。

日期時間對象的方法使用 all.equal.numeric 將時間(以 "POSIXct" 表示形式)與默認的 tolerance 0.001 秒進行比較，忽略 scale 。除非 check.tzone = FALSE ，否則報告 target 和 current 之間的時區不匹配。

attr.all.equal 用於比較 attributes ，返回 NULL 或 character 向量。

值

TRUE (NULL for attr.all.equal )或 mode "character" 的向量說明 target 和 current 之間的差異。

例子

all.equal(pi, 355/113)
# not precise enough (default tol) > relative error

quarts <- 1/4 + 1:10 # exact
d45 <- pi*quarts ; one <- rep(1, 10)
tan(d45) == one  # mostly FALSE, as typically exact; embarrassingly,
tanpi(quarts) == one # (is always FALSE (Fedora 34; gcc 11.2.1))
stopifnot(all.equal(
          tan(d45), one)) # TRUE, but not if we are picky:
all.equal(tan(d45), one, tolerance = 0)  # to see difference
all.equal(tan(d45), one, tolerance = 0, scale = 1)# "absolute diff.."
all.equal(tan(d45), one, tolerance = 0, scale = 1+(-2:2)/1e9) # "absolute"
all.equal(tan(d45), one, tolerance = 0, scale = 1+(-2:2)/1e6) # "scaled"

## advanced: equality of environments
ae <- all.equal(as.environment("package:stats"),
                asNamespace("stats"))
stopifnot(is.character(ae), length(ae) > 10,
          ## were incorrectly "considered equal" in R <= 3.1.1
          all.equal(asNamespace("stats"), asNamespace("stats")))

## A situation where  'countEQ = TRUE' makes sense:
x1 <- x2 <- (1:100)/10;  x2[2] <- 1.1*x1[2]
## 99 out of 100 pairs (x1[i], x2[i]) are equal:
plot(x1,x2, main = "all.equal.numeric() -- not counting equal parts")
all.equal(x1,x2) ## "Mean relative difference: 0.1"
mtext(paste("all.equal(x1,x2) :", all.equal(x1,x2)), line= -2)
##' extract the 'Mean relative difference' as number:
all.eqNum <- function(...) as.numeric(sub(".*:", '', all.equal(...)))
set.seed(17)
## When x2 is jittered, typically all pairs (x1[i],x2[i]) do differ:
summary(r <- replicate(100, all.eqNum(x1, x2*(1+rnorm(x1)*1e-7))))
mtext(paste("mean(all.equal(x1, x2*(1 + eps_k))) {100 x} Mean rel.diff.=",
            signif(mean(r), 3)), line = -4, adj=0)
## With argument  countEQ=TRUE, get "the same" (w/o need for jittering):
mtext(paste("all.equal(x1,x2, countEQ=TRUE) :",
          signif(all.eqNum(x1,x2, countEQ=TRUE), 3)), line= -6, col=2)

## Using giveErr=TRUE :
x1. <- x1 * (1+ 1e-9*rnorm(x1))
str(all.equal(x1, x1., giveErr=TRUE))
## logi TRUE
## - attr(*,  "err")= num 8.66e-10
## - attr(*, "what")= chr "relative"

## Used with stopifnot(), still *showing* diff:
all.equalShow <- function (...) {
   r <- all.equal(..., giveErr=TRUE)
   cat(attr(r,"what"), "err:", attr(r,"err"), "\n")
   c(r) # can drop attributes, as not used anymore
}
# checks, showing error in any case:
stopifnot(all.equalShow(x1, x1.)) # -> relative err: 8.66002e-10
tryCatch(error=identity, stopifnot(all.equalShow(x1, 2*x1))) -> eAe
cat(eaMsg <- conditionMessage(eAe), "\n")
stopifnot(inherits(eAe, "error"), # stopifnot() giving smart msg:
          grepl("are not equal", eaMsg, fixed=TRUE))

## comparison of date-time objects
now <- Sys.time()
stopifnot(
all.equal(now, now + 1e-4)  # TRUE (default tolerance = 0.001 seconds)
)
all.equal(now, now + 0.2)
all.equal(now, as.POSIXlt(now, "UTC"))
stopifnot(
all.equal(now, as.POSIXlt(now, "UTC"), check.tzone = FALSE)  # TRUE
)

參考

Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer (for =).

也可以看看

identical 、 isTRUE 、 == 和 all 用於精確相等測試。