transform_gate: Simplified geometric transformation of gates

In RGLab/flowCore: flowCore: Basic structures for flow cytometry data

Simplified geometric transformation of gates

Description

Perform geometric transformations of Gate-type filter objects

Usage

## Default S3 method:
transform_gate(
  obj,
  scale = NULL,
  deg = NULL,
  rot_center = NULL,
  dx = NULL,
  dy = NULL,
  center = NULL,
  ...
)

Arguments

obj	A Gate-type filter object (quadGate, rectangleGate, ellipsoidGate, or polygonGate)
scale	Either a numeric scalar (for uniform scaling in all dimensions) or numeric vector specifying the factor by which each dimension of the gate should be expanded (absolute value > 1) or contracted (absolute value < 1). Negative values will result in a reflection in that dimension. For rectangleGate and quadGate objects, this amounts to simply scaling the values of the 1-dimensional boundaries. For polygonGate objects, the values of scale will be used to determine scale factors in the direction of each of the 2 dimensions of the gate (scale_gate is not yet defined for higher-dimensional polytopeGate objects). Important: For ellipsoidGate objects, scale determines scale factors for the major and minor axes of the ellipse, in that order.
deg	An angle in degrees by which the gate should be rotated in the counter-clockwise direction.
rot_center	A separate 2-dimensional center of rotation for the gate, if desired. By default, this will be the center for ellipsoidGate objects or the centroid for polygonGate objects. The rot_center argument is currently only supported for polygonGate objects. It is also usually simpler to perform a rotation and a translation individually than to manually specify the composition as a rotation around a shifted center.
dx	Either a numeric scalar or numeric vector. If it is scalar, this is just the desired shift of the gate in its first dimension. If it is a vector, it specifies both dx and dy as (dx,dy). This provides an alternate syntax for shifting gates, as well as allowing shifts of ellipsoidGate objects in more than 2 dimensions.
dy	A numeric scalar specifying the desired shift of the gate in its second dimension.
center	A numeric vector specifying where the center or centroid should be moved (rather than specifiying dx and/or dy)
...	Assignments made to the slots of the particular Gate-type filter object in the form "<slot_name> = <value>"

Details

This method allows changes to the four filter types defined by simple geometric gates (quadGate, rectangleGate, ellipsoidGate, and polygonGate) using equally simple geometric transformations (shifting/translation, scaling/dilation, and rotation). The method also allows for directly re-setting the slots of each Gate-type object. Note that these methods are for manually altering the geometric definition of a gate. To easily transform the definition of a gate with an accompanyging scale transformation applied to its underlying data, see rescale_gate.

First, transform_gate will apply any direct alterations to the slots of the supplied Gate-type filter object. For example, if "mean = c(1,3)" is present in the argument list when transform_gate is called on a ellipsoidGate object, the first change applied will be to shift the mean slot to (1,3). The method will carry over the dimension names from the gate, so there is no need to provide column or row names with arguments such as mean or cov for ellipsoidGate or boundaries for polygonGate.

transform_gate then passes the geometric arguments (dx, dy, deg, rot_center, scale, and center) to the methods which perform each respective type of transformation: shift_gate, scale_gate, or rotate_gate. The order of operations is to first scale, then rotate, then shift. The default behavior of each operation follows that of its corresponding method but for the most part these are what the user would expect. A few quick notes:

• rotate_gate is not defined for rectangleGate or quadGate objects, due to their definition as having 1-dimensional boundaries.

• The default center for both rotation and scaling of a polygonGate is the centroid of the polygon. This results in the sort of scaling most users expect, with a uniform scale factor not distorting the shape of the original polygon.

Value

A Gate-type filter object of the same type as gate, with the geometric transformations applied

Examples

## Not run: 
# Scale the original gate non-uniformly, rotate it 15 degrees, and shift it
transformed_gate <- transform_gate(original_gate, scale = c(2,3), deg = 15, dx = 500, dy = -700)

# Scale the original gate (in this case an ellipsoidGate) after moving its center to (1500, 2000)
transformed_gate <- transform_gate(original_gate, scale = c(2,3), mean = c(1500, 2000))

## End(Not run)

RGLab/flowCore documentation built on Aug. 26, 2024, 8:52 a.m.