# fpCompare

## Reliable comparison of floating point numbers

Comparisons of floating point numbers are problematic due to errors
associated with the binary representation of decimal numbers. Computer
scientists and programmers are aware of these problems and yet people
still use numerical methods which fail to account for floating point
errors (this pitfall is the first to be highlighted in Circle 1 of Burns
(2012) [The R
Inferno](https://www.burns-stat.com/pages/Tutor/R_inferno.pdf)).

To avoid these and other numerical rounding issues, R’s help file for
relational operators (*e.g.*,
[`?'>'`](https://rdrr.io/r/base/Comparison.html)) suggests using
`identical` and `all.equal` when making numerical comparisons:

``` r

x1 <- 0.5 - 0.3
x2 <- 0.3 - 0.1
x1 == x2                           ## FALSE on most machines
identical(all.equal(x1, x2), TRUE) ## TRUE everywhere
```

Inspired by [R FAQ
7.31](https://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-doesn_0027t-R-think-these-numbers-are-equal_003f)
and [this Stack Overflow
answer](https://stackoverflow.com/a/2769618/1380598), this package
provides new relational operators useful for performing floating point
number comparisons with a set tolerance:

| **`fpCompare`**[^1] | **`base`** |
|---------------------|------------|
| `%>=%`              | `>=`       |
| `%>>%`              | `>`        |
| `%<=%`              | `<=`       |
| `%<<%`              | `<`        |
| `%==%`              | `==`       |
| `%!=%`              | `!=`       |

These functions use the `base` relational operators to make comparisons,
but incorporate a tolerance value (`fpCompare.tolerance`) similar to
`all.equal`. The default `fpCompare.tolerance` value is
`.Machine$double.eps^0.5`, set via `options`. This is the same default
used in `all.equal` for numeric comparisons.

``` r

## set tolerance value
tol <- .Machine$double.eps^0.5     ## default value
options(fpCompare.tolerance = tol)

## perform comparisons
x1 <- 0.5 - 0.3
x2 <- 0.3 - 0.1
x1 == x2         ## FALSE on most machines
x1 %==% x2       ## TRUE everywhere
```

## Installation

### From CRAN

``` r

install.packages("fpCompare")
```

### From GitHub

``` r

# install.packages("pak")
pak::pak("PredictiveEcology/fpCompare")
```

## Bug Reports

<https://github.com/PredictiveEcology/fpCompare/issues>

## Code of Conduct

Please note that the `fpCompare` project is released with a [Contributor
Code of
Conduct](https://fpcompare.predictiveecology.org/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

[^1]: The `%<<%` and `%>>%` symbols are used instead of `%<%` and `%>%`
    to avoid a conflict with `magrittr`’s pipe operator (`%>%`).

# Package index

## All functions

- [`` `%>=%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  [`` `%>>%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  [`` `%<=%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  [`` `%<<%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  [`` `%==%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  [`` `%!=%` ``](https://fpcompare.predictiveecology.org/reference/relational-operators.md)
  : Relational operators with tolerance

# Articles

### All vignettes

- [fpCompare: reliable comparison of floating point
  numbers](https://fpcompare.predictiveecology.org/articles/fpCompare.md):