concept_scale_factors.RdWith scale factors we refer to numeric values that are used to multiply with the original x- and y-coordinates of the object's observations, in order to align them with an image or to bring them into a coordinates system measured in SI units (or both).
Both, S4 class SpatialData and HistoImage contain a slot named @scale_factors.
In both cases it is a named list. If the SPATA2 object contains images, coordinates
of data points or spatial reference features are automatically aligned with the resolution
of the image that is in use, the active image. The required
image scale factor lives in the @scale_factors slot of the HistoImage object which
serves as the container of the respective image.
Furthermore, SPATA2 allows to work with SI units. To transform coordinates from
pixel units to SI units as pixel scale factor is required. Primarily, these
scale factors live in the @scale_factors slot of each registered HistoImage, too.
If the SPATA2 object does not contain images, a pixel scale factor can be stored
in slot @scale_factors of the SpatialData object.
(Generally speaking, whenever scale factors are required the system checks whether
there is an image to which anything must be scaled. If so, the scale factors are
taken from the @scale_factors slot of the HistoImage object. If not, the scale factors
are looked up in the @scale_factors slot of the SpatialData object.)
SPATA2 objects allow to store multiple images simultaneously and
as they might differ in resolutions, different scale factors are required to scale
the coordinates of the observations appropriately, such that image and coordinates
align perfectly. This is what happens in the background when you extract or plot
the observations in the light of the resolution of a fictional example image lowres_image.
First, the original data.frame is obtained.
coords_df <- getCoordsDf(object, as_is = TRUE)
Second, the image scale factor of image 'lowres_image' is extracted.
csf <- getScaleFactor(object, img_name = "lowres_image", fct_name = "image")
Third, the variables are transformed to x and y.
coords_df$x <- coords_df$x_orig * csf
coords_df$y <- coords_df$y_orig * csf
The same process is applied to any sort of spatial data upon extraction, e.g.
getSpatAnnOutlineDf().
If the object does not contain an image, e.g. for MERFISH or Xenium,
there are no images and thus slot @images of the SpatialData object is empty.
Furthermore, since there is nothing to align, there is no image scale factor.
In that case x and y variables of the data.frame will be equal
to x_orig and y_orig.
The pixel scale factor is used to transform the coordinates from pixel to SI units. It is a numeric value that comes with an attribute which indicates the SI unit to which the pixel value is scaled (e.g. mm / px). It is applied after the coordinates have been scaled to the image resolution.
coords_df <- getCoordsDf(object)
psf <- getPixelScaleFactor(object)
coords_df$x_si <- coords_df$x * psf
coords_df$y_si <- coords_df$y * psf
Note: Methods that do not include an image, often provide the coordinates already
in SI units. MERFISH coordinates, for instance, are already in micrometer units.
The pixel scale factor therefore is 1um/px.
(The name pixel scale factor has evolved historically, since SPATA2 was developed
with the Visium platform in mind. It does not fit perfectly for platforms such as
MERFISH or Xenium experiments since they do not provide an image. But
the SI unit system of SPATA2 works stable and we don't want to touch it. Therefore,
the name remains.)