apply_transformation_matrix: Apply transformation matrix to a set of columns

In rearrr: Rearranging Data

Apply transformation matrix to a set of columns

Description

\Sexpr[results=rd, stage=render]{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
)

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)

Details

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

• Move origin to (0, 0):

  x = x - origin_x

  y = 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_x

  y = y + origin_y

Value

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

Author(s)

Ludvig Renbo Olsen, [e-mail]

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()
}

rearrr documentation built on April 4, 2025, 1:07 a.m.