Logical: and, cap, cup, comp, cuvee, cuwed, exist,
forall, fork, isin, nexist, ni, notin,
diff --git a/docs/reference/v.html b/docs/reference/v.html
index d55b59d..84cf75c 100644
--- a/docs/reference/v.html
+++ b/docs/reference/v.html
@@ -20,7 +20,7 @@
common
- 1.0.8
+ 1.0.9
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index df61e18..d2a09e9 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -27,6 +27,9 @@
https://common.r-sassy.org/news/index.html
+
+ https://common.r-sassy.org/reference/changed.html
+
https://common.r-sassy.org/reference/common.html
diff --git a/man/changed.Rd b/man/changed.Rd
new file mode 100644
index 0000000..0c537f3
--- /dev/null
+++ b/man/changed.Rd
@@ -0,0 +1,113 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/other_functions.R
+\name{changed}
+\alias{changed}
+\title{Identify changed values}
+\usage{
+changed(x, reverse = FALSE, simplify = FALSE)
+}
+\arguments{
+\item{x}{A vector of values in which to identify changed values.
+Also accepts a data frame. In the case of a data frame, the function
+will use all columns. Input data can be any data type.}
+
+\item{reverse}{Reverse the direction of the scan to identify the last
+value in a group instead of the first.}
+
+\item{simplify}{If the input data to the function is a data frame,
+the simplify option will return a single vector of indicator values
+instead of a data frame of indicator values.}
+}
+\value{
+A vector of TRUE or FALSE values indicating the grouping boundaries
+of the vector or data frame.
+}
+\description{
+The \code{changed} function identifies changes in a vector or
+data frame. The function is used to locate grouping boundaries. It will
+return a TRUE each time the current value is different from the previous
+value. The \code{changed} function is similar to the Base R \code{duplicated}
+function, except \code{changed} the function will return TRUE even if
+the changed value is not unique.
+}
+\details{
+For a data frame,
+by default, the function will return another data frame with an equal
+number of change indicator columns. The column names
+will be the original column names, with a ".changed" suffix.
+
+To collapse
+the multiple change indicators into one vector, use the "simplify" option.
+In this case, the returned vector will essentially be an "or" operation
+across all columns.
+}
+\examples{
+# Create sample vector
+v1 <- c(1, 1, 1, 2, 2, 3, 3, 3, 1, 1)
+
+# Identify changed values
+res1 <- changed(v1)
+
+# View results
+res1
+# [1] TRUE FALSE FALSE TRUE FALSE TRUE FALSE FALSE TRUE FALSE
+
+# Create sample data frame
+v2 <- c("A", "A", "A", "A", "A", "A", "B", "B", "B", "B")
+dat <- data.frame(v1, v2)
+
+# View original data frame
+dat
+# v1 v2
+# 1 1 A
+# 2 1 A
+# 3 1 A
+# 4 2 A
+# 5 2 A
+# 6 3 A
+# 7 3 B
+# 8 3 B
+# 9 1 B
+# 10 1 B
+
+# Get changed values for each column
+res2 <- changed(dat)
+
+# View results
+res2
+# v1.changed v2.changed
+# 1 TRUE TRUE
+# 2 FALSE FALSE
+# 3 FALSE FALSE
+# 4 TRUE FALSE
+# 5 FALSE FALSE
+# 6 TRUE FALSE
+# 7 FALSE TRUE
+# 8 FALSE FALSE
+# 9 TRUE FALSE
+# 10 FALSE FALSE
+
+# Get changed values for all columns
+res3 <- changed(dat, simplify = TRUE)
+
+# View results
+res3
+# [1] TRUE FALSE FALSE TRUE FALSE TRUE TRUE FALSE TRUE FALSE
+
+# Get last items in each group instead of first
+res4 <- changed(dat, reverse = TRUE)
+
+# View results
+res4
+# v1.changed v2.changed
+# 1 FALSE FALSE
+# 2 FALSE FALSE
+# 3 TRUE FALSE
+# 4 FALSE FALSE
+# 5 TRUE FALSE
+# 6 FALSE TRUE
+# 7 FALSE FALSE
+# 8 TRUE FALSE
+# 9 FALSE FALSE
+# 10 TRUE TRUE
+}
diff --git a/tests/testthat/test-other_functions.R b/tests/testthat/test-other_functions.R
index 7a74f24..94a6b82 100644
--- a/tests/testthat/test-other_functions.R
+++ b/tests/testthat/test-other_functions.R
@@ -304,7 +304,192 @@ test_that("other8: roundup() function works on dataframes.", {
expect_equal(res$Sepal.Width[1], 4)
+})
+
+test_that("other9: changedv() function works as expected.", {
+
+ v1 <- c(1, 1, 1, 2, 2, 3, 3, 3, 1, 1)
+
+ res <- changedv(v1)
+
+ res
+
+ expect_equal(res, c(TRUE, FALSE, FALSE, TRUE, FALSE,
+ TRUE, FALSE, FALSE, TRUE, FALSE))
+
+ res2 <- duplicated(v1)
+
+ expect_equal(all(res != res2), FALSE)
+
+})
+
+
+test_that("other10: compint() works as expected.", {
+
+ v1 <- c(1, 1, 2, NA, 3, 3, NA)
+ v2 <- c(1, 2, 2, NA, NA, 3, 1)
+
+
+ res <- compint(v1, v2)
+
+ res
+
+ expect_equal(res, c(TRUE, FALSE, TRUE, TRUE, FALSE, TRUE, FALSE))
+})
+
+
+test_that("other11: changedv() reversed works as expected.", {
+
+ v1 <- c(1, 1, 1, 2, 2, 3, 3, 3, 1, 1)
+
+ res <- changedv(v1, reverse = TRUE)
+
+ res
+ expect_equal(res, c(F, F, TRUE, FALSE, T,
+ F, FALSE, TRUE, FALSE, T))
})
+
+test_that("other12: changedv() with NA works as expected.", {
+
+ v1 <- c(1, 1, 1, 2, 2, 3, NA, 3, 1, 1)
+
+ res <- changedv(v1)
+
+ res
+
+ expect_equal(res, c(TRUE, FALSE, FALSE, TRUE, FALSE,
+ TRUE, TRUE, TRUE, TRUE, FALSE))
+
+
+
+})
+
+
+test_that("other13: changed() function with df works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c(1, 1, 1, 2, 2, 3, 3, 3, 1, 1)
+
+ df <- data.frame(v1, v2)
+
+ res <- changed(df)
+
+ res
+
+ expect_equal(res$v1.changed, c(TRUE, FALSE, FALSE, FALSE, FALSE,
+ TRUE, FALSE, FALSE, FALSE, FALSE))
+
+ expect_equal(res$v2.changed, c(TRUE, FALSE, FALSE, TRUE, FALSE,
+ TRUE, FALSE, FALSE, TRUE, FALSE))
+
+})
+
+
+test_that("other14: collapsedf() function works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c(1, 1, 1, 2, 2, 2, 3, 3, 1, 1)
+ v3 <- c(1, 1, 2, 2, 2, 2, 2, 2, 2, 2)
+
+ v1 <- changedv(v1)
+ v2 <- changedv(v2)
+ v3 <- changedv(v3)
+
+ df <- data.frame(v1, v2, v3)
+
+ res <- collapsedf(df)
+
+
+ expect_equal(res, c(T, F, T, T, F, T, T, F, T, F))
+})
+
+test_that("other15: changed() function with simplify works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c(1, 1, 1, 2, 2, 2, 3, 3, 1, 1)
+ v3 <- c(1, 1, 2, 2, 2, 2, 2, 2, 2, 2)
+
+ df <- data.frame(v1, v2, v3)
+
+ res <- changed(df, simplify = TRUE)
+
+ res
+
+ expect_equal(res, c(T, F, T, T, F, T, T, F, T, F))
+
+})
+
+test_that("other16: changed() function with df character works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c("A", "A", "A", "B", "B", "C", "C", "C", "A", "A")
+
+ df <- data.frame(v1, v2)
+
+ res <- changed(df)
+
+ res
+
+ expect_equal(res$v1.changed, c(TRUE, FALSE, FALSE, FALSE, FALSE,
+ TRUE, FALSE, FALSE, FALSE, FALSE))
+
+ expect_equal(res$v2.changed, c(TRUE, FALSE, FALSE, TRUE, FALSE,
+ TRUE, FALSE, FALSE, TRUE, FALSE))
+
+})
+
+
+test_that("other17: changed() function with simplify works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c("A", "A", "A", "B", "B", "C", "C", "C", "A", "A")
+ v3 <- c(1.1, 1.1, 2.1, 2.1, 2.1, 2.1, 2.1, 2.1, 2.1, 2.1)
+
+ df <- data.frame(v1, v2, v3)
+
+ res <- changed(df, simplify = TRUE)
+
+ res
+
+ expect_equal(res, c(T, F, T, T, F, T, F, F, T, F))
+
+})
+
+
+test_that("other18: changed() function with reverse works as expected.", {
+
+ v1 <- c(1, 1, 1, 1, 1, 3, 3, 3, 3, 3)
+ v2 <- c("A", "A", "A", "B", "B", "C", "C", "C", "A", "A")
+ v3 <- c(as.Date("2023-01-01"), as.Date("2023-01-01"),
+ as.Date("2023-01-02"), as.Date("2023-01-02"), as.Date("2023-01-02"),
+ as.Date("2023-01-02"), as.Date("2023-01-02"), as.Date("2023-01-02"),
+ as.Date("2023-01-02"), as.Date("2023-01-02"))
+
+ df <- data.frame(v1, v2, v3)
+
+ res <- changed(df$v2, reverse = TRUE)
+
+ res
+
+ expect_equal(res, c(F, F, T, F, T, F, F, T, F, T))
+
+ res <- changed(df, reverse = TRUE)
+
+ res
+
+ expect_equal(res$v1.changed[1], FALSE)
+ expect_equal(res$v1.changed[10], TRUE)
+ expect_equal(res$v3.changed[1], FALSE)
+ expect_equal(res$v3.changed[2], TRUE)
+ expect_equal(res$v3.changed[10], TRUE)
+
+ res1 <- changed(df, reverse = TRUE, simplify = TRUE)
+
+ expect_equal(res1, c(F, T, T, F, T, F, F, T, F, T))
+
+})
+
+
diff --git a/tests/testthat/test-override_functions.R b/tests/testthat/test-override_functions.R
index 8eda416..964c0eb 100644
--- a/tests/testthat/test-override_functions.R
+++ b/tests/testthat/test-override_functions.R
@@ -175,3 +175,23 @@ test_that("override3: Sort retains df attributes", {
expect_equal(length(res), 3)
})
+
+
+test_that("override4: Sort of two factors works as expected.", {
+
+ prtsp <- prt
+
+ prtsp$enrollment[4] <- NA
+ prtsp$sex[2] <- NA
+ prtsp$sex <- factor(prtsp$sex, levels = c("girls", "boys"))
+ prtsp$enrollment <- factor(prtsp$enrollment, levels = c("yes", "no"))
+
+
+ res <- sort(prtsp, by = c("sex", "enrollment"))
+
+ res
+
+ expect_equal(unique(as.character(res$sex)), c("girls", "boys", NA))
+ expect_equal(unique(as.character(res$enrollment)), c("yes", "no", NA))
+
+})
diff --git a/vignettes/common.Rmd b/vignettes/common.Rmd
index 52b218d..64e6c71 100644
--- a/vignettes/common.Rmd
+++ b/vignettes/common.Rmd
@@ -34,6 +34,7 @@ one data frame to another.
- [**subsc()**](#supsc): A function to get UTF-8 subscript characters.
- [**symbol()**](#symbol): A function to lookup UTF-8 symbols.
- [**spaces()**](#spaces): A function to create a string of blank spaces.
+- [**changed()**](#changed): A function to identify changed values in a vector or data frame.
@@ -526,8 +527,8 @@ is similar to the `supsc()` and `subsc()` functions in
that it looks up a UTF-8 character. Instead of providing a direct 1 to 1
translation, however, it looks up the UTF-8 character based on a keyword.
-For example, the 'reg' keyword looks up the registered trademark symbol. The
-'ne' keyword looks up the symbol for not equals. These keyword names
+For example, the 'regkeyword looks up the registered trademark symbol. The
+'nekeyword looks up the symbol for not equals. These keyword names
follow HTML conventions. The function supports keywords for trademarks,
currencies, mathematical symbols, logical symbols, Greek letters, and
more. See the `symbol()` documentation for a complete list
@@ -556,3 +557,111 @@ str
# [1] "Left Right"
```
+[top](#top)
+
+## Identify changed values {#changed}
+Base R has a `duplicated()` function that is sometimes used to identify grouping boundaries
+in a vector. But this function also performs a `unique()` operation on
+the vector, such that not all boundaries return a TRUE value.
+Observe the following:
+```
+# Create sample vector
+v1 <- c(1, 1, 1, 2, 2, 3, 3, 3, 1, 1)
+
+# Identify duplicated values
+res1 <- !duplicated(v1)
+
+# View duplicated results
+res1
+# [1] TRUE FALSE FALSE TRUE FALSE TRUE FALSE FALSE FALSE FALSE
+
+```
+Notice that the "1" at position nine does not return TRUE.
+
+Now lets run the same vector through the `changed()` function:
+```
+# Identify changed values
+res2 <- changed(v1)
+
+# View changed results
+res2
+# [1] TRUE FALSE FALSE TRUE FALSE TRUE FALSE FALSE TRUE FALSE
+
+```
+This time, the `changed()` function identified each time the vector changed
+value, whether or not the value had appeared previously.
+
+This function can also be used on data frames:
+```
+# Create sample data frame
+v2 <- c("A", "A", "A", "A", "A", "A", "B", "B", "B", "B")
+dat <- data.frame(v1, v2)
+
+# View original data frame
+dat
+# v1 v2
+# 1 1 A
+# 2 1 A
+# 3 1 A
+# 4 2 A
+# 5 2 A
+# 6 3 A
+# 7 3 B
+# 8 3 B
+# 9 1 B
+# 10 1 B
+
+# Get changed values for each column
+res3 <- changed(dat)
+
+# View results
+res3
+# v1.changed v2.changed
+# 1 TRUE TRUE
+# 2 FALSE FALSE
+# 3 FALSE FALSE
+# 4 TRUE FALSE
+# 5 FALSE FALSE
+# 6 TRUE FALSE
+# 7 FALSE TRUE
+# 8 FALSE FALSE
+# 9 TRUE FALSE
+# 10 FALSE FALSE
+```
+If you wish to return a single indicator vector for the combination of
+all columns, use the "simplify" option.
+```
+# Get changed values for each column
+res4 <- changed(dat, simplify = TRUE)
+
+# View results
+res4
+# [1] TRUE FALSE FALSE TRUE FALSE TRUE TRUE FALSE TRUE FALSE
+```
+The above vector returns a TRUE when either the "v1" or "v2" value
+changes.
+
+The "reverse" option identifies the last items in a group instead of the
+first:
+```
+# Find last items in each group
+res3 <- changed(dat, reverse = TRUE)
+
+# View results
+res3
+# v1.changed v2.changed
+# 1 FALSE FALSE
+# 2 FALSE FALSE
+# 3 TRUE FALSE
+# 4 FALSE FALSE
+# 5 TRUE FALSE
+# 6 FALSE TRUE
+# 7 FALSE FALSE
+# 8 TRUE FALSE
+# 9 FALSE FALSE
+# 10 TRUE TRUE
+
+```
+
+
+[top](#top)
