Convert from pixels to European units of length — transform_pixel_to_dist

Transforms pixel values to European units of length (e.g. '2mm', '400.50um') depending one the original size of spatial -omic methods and the resolution of the current image.

transform_pixel_to_dist_si(
  input,
  unit,
  object = NULL,
  image_dims = NULL,
  round = FALSE,
  ...
)

transform_pixels_to_dist_si(
  input,
  unit,
  object = NULL,
  image_dims = NULL,
  method = NULL,
  round = FALSE,
  ...
)

Arguments

input: Distance as pixel input. See details for more information.
unit: Character value. The desired SI unit of length. Use validUnitsOfLengthSI() to obtain all valid input options.
object: A valid SPATA2 object or NULL. If specified the distance scaling is adjusted to the current resolution of the image inside the object. If NULL, image_dims and method must be specified.
round: Numeric value or FALSE. If numeric, given to digits of base::round(). Rounds transformed values before they are returned.
as_numeric: Logical value. If TRUE, forces the output to be numeric. This means that the unit is not not suffixed.

Value

Transformed input. Vector of the same length as input and of class units.

Details

Several functions in SPATA2 have arguments that take distance input. To specifically refer to a distance the unit must be specified. There are three ways to create valid input for these arguments.

1. In pixel:

There are two valid input options to specify the distance in pixel:

numeric: Single numeric values, e.g. arg_input <- c(2, 3.554, 69, 100.67). If no unit is specified the input will be interpreted as pixels.
character: Suffixed with 'px', e.g. arg_input <- c('2px', '3.554px', '69px', '100.67px')

Note: The unit pixel (px) is used for distances as well as for areas. If pixel refers to a distance the pixel side length is meant. If pixel refers to an area the number of pixels is meant.

2. According to the Systeme international d`unites (SI):

Specifying distances in SI units e.g. arg_input <- c('2mm', '4mm') etc. requires the input to be a character as the unit must be provided as suffix. Between the numeric value and the unit must be no empty space! Valid suffixes can be obtained using the function validUnitsOfLengthSI().

3. As vectors of class unit:

Behind the scenes SPATA2 works with the units package. Input is converted into vectors of class units. Therefore, input can be directly provided this way: arg_input <- units::set_unit(x = c(2,4), value = 'mm') Note that pixel is not a valid unit in the units package. If you want to specify the input in pixel you have to use input option 1. In pixel.

Note

transform_pixel_to_dist_si() transforms only single values. transform_pixels_to_dist_si() transforms vectors of lengths one or more.