rearrr (version 0.3.4)

apply_transformation_matrix: Apply transformation matrix to a set of columns

Description

lifecycle::badge("experimental")

Perform matrix multiplication with a transformation matrix and a set of data.frame columns.

The data points in `data` are moved prior to the transformation, to bring the origin to 0 in all dimensions. After the transformation, the inverse move is applied to bring the origin back to its original position. See `Details` section.

The columns in `data` are transposed, making the operation (without the origin movement): $$mat · data[, cols]^T$$

The origin can be supplied as coordinates or as a function that returns coordinates. The latter can be useful when supplying a grouped data.frame and transforming around e.g. the centroid of each group.

Usage

apply_transformation_matrix(
  data,
  mat,
  cols,
  origin = NULL,
  origin_fn = NULL,
  suffix = "_transformed",
  keep_original = TRUE,
  origin_col_name = ".origin",
  overwrite = FALSE
)

Value

data.frame (tibble) with the new, transformed columns and the origin coordinates.

Arguments

data

data.frame or vector.

mat

Transformation matrix. Must have the same number of columns as `cols`.

cols

Columns to mutate values of. Must be specified when `data` is a data.frame.

origin

Coordinates of the origin. Vector with the same number of elements as `cols` (i.e. origin_x, origin_y, ...). Ignored when `origin_fn` is not NULL.

origin_fn

Function for finding the origin coordinates.

Input: Each column will be passed as a vector in the order of `cols`.

Output: A vector with one scalar per dimension.

Can be created with create_origin_fn() if you want to apply the same function to each dimension.

E.g. `create_origin_fn(median)` would find the median of each column.

Built-in functions are centroid(), most_centered(), and midrange()

suffix

Suffix to add to the names of the generated columns.

Use an empty string (i.e. "") to overwrite the original columns.

keep_original

Whether to keep the original columns. (Logical)

Some columns may have been overwritten, in which case only the newest versions are returned.

origin_col_name

Name of new column with the origin coordinates. If NULL, no column is added.

overwrite

Whether to allow overwriting of existing columns. (Logical)

Author

Ludvig Renbo Olsen,

Details

Example with 2 columns (x, y) and a 2x2 transformation matrix:

• Move origin to (0, 0):x = x - origin_xy = y - origin_y

• Convert to transposed matrix:data_mat = rbind(x, y)

• Matrix multiplication:transformed = mat %*% data_mat

• Move origin to original position (after extraction from transformed):x = x + origin_xy = y + origin_y

See Also

Other mutate functions: cluster_groups(), dim_values(), expand_distances(), expand_distances_each(), flip_values(), roll_values(), rotate_2d(), rotate_3d(), shear_2d(), shear_3d(), swirl_2d(), swirl_3d()

Examples

# Attach packages
library(rearrr)
library(dplyr)
has_ggplot <- require(ggplot2)  # Attach if installed

# Set seed
set.seed(3)

# Create a data frame
df <- data.frame(
  "x" = 1:12,
  "y" = 13:24,
  "z" = runif(12),
  "g" = c(
    1, 1, 1, 1, 2, 2,
    2, 2, 3, 3, 3, 3
  )
)

# Apply identity matrix
mat <- matrix(c(1, 0, 0, 0, 1, 0, 0, 0, 1), nrow = 3)
apply_transformation_matrix(
  data = df,
  mat = mat,
  cols = c("x", "y", "z"),
  origin = c(0, 0, 0)
)

# Apply rotation matrix
# 90 degrees around z-axis
# Origin is the most centered point
mat <- matrix(c(0, 1, 0, -1, 0, 0, 0, 0, 1), nrow = 3)
res <- apply_transformation_matrix(
  data = df,
  mat = mat,
  cols = c("x", "y", "z"),
  origin_fn = most_centered
)

# Plot the rotation
# z wasn't changed so we plot x and y
if (has_ggplot){
  res %>%
    ggplot(aes(x = x, y = y)) +
    geom_point() +
    geom_point(aes(x = x_transformed, y = y_transformed)) +
    theme_minimal()
}

# Apply rotation matrix to grouped data frame
# Around centroids
# Same matrix as before
res <- apply_transformation_matrix(
  data = dplyr::group_by(df, g),
  mat = mat,
  cols = c("x", "y", "z"),
  origin_fn = centroid
)

# Plot the rotation
if (has_ggplot){
  res %>%
    ggplot(aes(x = x, y = y, color = g)) +
    geom_point() +
    geom_point(aes(x = x_transformed, y = y_transformed)) +
    theme_minimal()
}