rearrr (version 0.3.4)

shear_3d: Shear values around an origin in 3 dimensions

Description

lifecycle::badge("experimental")

Shears points around an origin in 3-dimensional space. See applied shearing matrices under Details.

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

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 shearing around e.g. the centroid of each group.

Usage

shear_3d(
  data,
  x_col,
  y_col,
  z_col,
  x_shear = NULL,
  y_shear = NULL,
  z_shear = NULL,
  suffix = "_sheared",
  origin = NULL,
  origin_fn = NULL,
  keep_original = TRUE,
  shear_col_name = ".shear",
  origin_col_name = ".origin",
  overwrite = FALSE
)

Value

data.frame (tibble) with six new columns containing the sheared x-, y- and z-values and the shearing amounts and origin coordinates.

Arguments

data

data.frame or vector.

x_col, y_col, z_col

Name of x/y/z column in `data`. All must be specified.

x_shear, y_shear, z_shear

Shear factor for the x/y/z dimension (numeric). Decides the amount of shearing. Can be vectors with multiple shear factors.

N.B. Exactly 2 of the dimensions must have shear factors specified.

suffix

Suffix to add to the names of the generated columns.

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

origin

Coordinates of the origin to shear around. Vector with 3 elements (i.e. origin_x, origin_y, origin_z). 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()

keep_original

Whether to keep the original columns. (Logical)

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

shear_col_name

Name of new column with the shearing amounts. If NULL, no column is added.

Also adds a string version with the same name + "_str", making it easier to group by the shearing amounts when plotting multiple shears.

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

Applies one of the following transformation matrices, depending on which two shearing amounts are specified:

Given `x_shear` and `y_shear`:

[ \(1\)	, \(0\)	, x_shear	]
[ \(0\)	, \(1\)	, y_shear	]
[ \(0\)	, \(0\)	, \(1\)	]

Given `x_shear` and `z_shear`:

[ \(1\)	, x_shear	, \(0\)	]
[ \(0\)	, \(1\)	, \(0\)	]
[ \(0\)	, z_shear	, \(1\)	]

Given `y_shear` and `z_shear`:

[ \(1\)	, \(0\)	, \(0\)	]
[ y_shear	, \(1\)	, \(0\)	]
[ z_shear	, \(0\)	, \(1\)	]

See Also

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

Other shearing functions: shear_2d()

Examples

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

# Set seed
set.seed(1)

df_square <- square(runif(100)) %>%
  rename(x = .square_x,
         y = Value) %>%
  mutate(z = 1)

# Shear the x and z axes
# around the centroid
df_sheared <- shear_3d(
  data = df_square,
  x_col = "x",
  y_col = "y",
  z_col = "z",
  x_shear = 2,
  z_shear = 4,
  origin_fn = centroid
)

# Plot sheared data
# Black: original points
# Red: sheared points
if (has_ggplot){
  df_sheared %>%
    ggplot(aes(x = x, y = y)) +
    geom_point() +
    geom_point(aes(x = x_sheared, y = y_sheared, color = "red")) +
    theme_minimal()
}

if (FALSE) {
# Plot 3d with plotly
plotly::plot_ly(
  x = df_sheared$x_sheared,
  y = df_sheared$y_sheared,
  z = df_sheared$z_sheared,
  type = "scatter3d",
  mode = "markers",
  color = df_sheared$.shear_str
)
}

# Shear the y and z axes
# around the centroid
df_sheared <- shear_3d(
  data = df_square,
  x_col = "x",
  y_col = "y",
  z_col = "z",
  y_shear = 2,
  z_shear = 4,
  origin_fn = centroid
)

# Plot sheared data
# Black: original points
# Red: sheared points
if (has_ggplot){
  df_sheared %>%
    ggplot(aes(x = x, y = y)) +
    geom_point() +
    geom_point(aes(x = x_sheared, y = y_sheared, color = "red")) +
    theme_minimal()
}

if (FALSE) {
# Plot 3d with plotly
plotly::plot_ly(
  x = df_sheared$x_sheared,
  y = df_sheared$y_sheared,
  z = df_sheared$z_sheared,
  type = "scatter3d",
  mode = "markers",
  color = df_sheared$.shear_str
)
}

# Shear the y and z axes with multiple amounts at once
# around the centroid
df_sheared <- shear_3d(
  data = df_square,
  x_col = "x",
  y_col = "y",
  z_col = "z",
  y_shear = c(0, 2, 4),
  z_shear = c(0, 4, 6),
  origin_fn = centroid
)

# Plot sheared data
if (has_ggplot){
  df_sheared %>%
    ggplot(aes(x = x_sheared, y = y_sheared, color = .shear_str)) +
    geom_point() +
    theme_minimal()
}

if (FALSE) {
# Plot 3d with plotly
plotly::plot_ly(
  x = df_sheared$x_sheared,
  y = df_sheared$y_sheared,
  z = df_sheared$z_sheared,
  type = "scatter3d",
  mode = "markers",
  color = df_sheared$.shear_str
)
}