Relate observations to an image annotation

Relates observations in an external data.frame to the spatial position and extent of an image annotation.

relateToImageAnnotation(
  object,
  id,
  input_df,
  input_id_var = NULL,
  distance = NA_integer_,
  binwidth = NA_integer_,
  n_bins_circle = NA_integer_,
  n_bins_angle = 12,
  calc_dist_to = "border",
  unit = "px",
  inc_outline = TRUE,
  verbose = NULL,
  ...
)

Arguments

object

An object of class spata2.

id

Character value. The ID of the image annotation of interest.

input_df

Data.frame with at least three columns.

  • x: numeric. Position of observations on x-axis.

  • y: numeric. Position of observations on y-axis.

input_id_var

Character value or NULL. If character, denotes the variable in input_df that uniquely identifies each observation. If NULL, a variable named inp_id is created using the prefix *'ID'+ and the rownumber.

distance, binwidth, n_bins_circle

If exactly two of the three arguments are not NA_integer_ but valid input as is documented in imageAnnotationScreening() the output contains binning results.

n_bins_angle

Numeric value. Number of bins that are created by angle. (See details for more.)

calc_dist_to

Character. One of 'border' (the default), 'center' or 'none'. If 'border', the distance of every observation to its closest point on the image annotation border is calculated. If 'center' the distance of every observation to the center of the image annotation is computed, as is returned by getImgAnnCenter(). If 'none', distance calculation is skipped.

unit

Character. The unit in which to calculate the distance.

inc_outline

Logical value. If TRUE, the function include_tissue_outline() is used to remove observations that do not fall on the tissue section of the image annotation. See examples and documentation of include_tissue_outline() for more information.

verbose

Logical. If set to TRUE informative messages regarding the computational progress will be printed.

(Warning messages will always be printed.)

...

Used to absorb deprecated arguments or functions.

Value

The input data.frame with additional columns:

  • angle : numeric. The angle between the observation point and the center of the image annotation.

  • bins_angle : factor. Groups created based on the variable angle. Number of levels depends on input for argument n_bins_angle.

  • bins_circle : factor. Groups created based on the variable dist_to_ia. Number of levels dpeends on input for arguments distance, binwidth and/or n_bins_circle.

  • dist_to_ia : numeric. Distance to the image annotation.

  • dist_unit : character. The unit in which distance was measured.

Additionally, if inc_outline is TRUE, the output variables of the function include_tissue_outline() are added.