Giotto Image Tools
1. Overview
Giotto uses giottoLargeImage to represent images and
raster information. This is an S4 class built based on the
terra SpatRaster.
An older class called giottoImage based on the
magick package also exists, but is currently being phased out.
Ideally, giottoLargeImages will also be renamed to
giottoImage afterwards, simplifying the naming scheme.
The object structure of giottoLargeImage
giottoLargeImage
\- name (object name)
\- raster_object (terra raster object)
\- extent (current spatial extent)
\- overall_extent (spatial extent of original image - experimental)
\- scale_factor (pixels per coordinate unit - experimental)
\- resolution (coordinate units covered per pixel)
\- max_intensity (approximate maximum intensity value)
\- min_intensity (approximate minimum intensity value)
\- max_window (value to set as maximum intensity in color scaling)
\- colors (vector of color mappings provided as hex codes)
\- is_int (whether values are integers)
\- file_path (filepath to the image)
\- OS_platform (operating system)2. Sampling
Spatial images are often extremely large files. The high detail
(resolution), large spatial region captured, and precision of recorded
values (bitdepth) often results in files in the 10s of gigabytes. This
makes the full size images difficult to work with. One way to get around
this is to perform regular sampling of the image, touching only the
values of the original image that are needed generate a downscaled
representation. This is implemented in terra as
spatSample().
When plotting, Giotto optimizes the speed of this sampling
by striking a balance between terra::crop() and
terra::spatSample() to try to prevent sampling from
unnecessary regions, but also avoid large crop operations on the
fullsize image, which can be very costly. This is done through
plot_auto_largeImage_resample()
giottoLargeImages can also be resampled to other image
formats (magick and EBImage) in addition to
data.table and array using
GiottoClass:::.spatraster_sample_values()
These two functions are experimental and they will be exported using more common function names in the future.
3 Color scaling
distGiottoImage() can be used to look at the values
present within a giottoLargeImage. It is often the case
that the values recorded within an image do not map to the full set of
values allowed by its bitdepth. Giotto plots images by guessing
the bitdepth based on the estimated maximum value detected. This mapping
may not always be optimal.
library(GiottoClass)
gimg <- GiottoData::loadSubObjectMini("giottoLargeImage", idx = 2)
gimg <- GiottoClass:::.update_giotto_image(gimg) # update older images that are missing slots
plot(gimg)
distGiottoImage(giottoLargeImage = gimg)
Since there are few values beyond 70, try setting
max_window to 70 in so that the color mapping better
represents the available information.
gimg@max_window <- 70
plot(gimg)
# plot(gimg, max_intensity = 150) # can be used without setting the slotThe colormap to use for an image can also be edited. The default for
a greyscale image is a monochrome black to white. Other color scales can
be supplied. For monochrome colorscales:
getMonochromeColors()
gimg@colors <- getMonochromeColors("green")
plot(gimg)
viridis_colors <- hcl.colors(256, palette = "viridis")
plot(gimg, col = viridis_colors) # can be used without setting the slot
TODOs:
- provide accessors for these slots
- make ggplot-based plotting also obey these settings
## R version 4.4.2 (2024-10-31)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 22.04.5 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so; LAPACK version 3.10.0
##
## locale:
## [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
## [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
## [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
## [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
##
## time zone: UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] GiottoClass_0.4.5
##
## loaded via a namespace (and not attached):
## [1] sass_0.4.9 SparseArray_1.6.0
## [3] gtools_3.9.5 lattice_0.22-6
## [5] digest_0.6.37 magrittr_2.0.3
## [7] evaluate_1.0.1 grid_4.4.2
## [9] fastmap_1.2.0 jsonlite_1.8.9
## [11] Matrix_1.7-1 backports_1.5.0
## [13] GenomeInfoDb_1.42.1 GiottoData_0.2.16
## [15] httr_1.4.7 SingleCellExperiment_1.28.1
## [17] UCSC.utils_1.2.0 codetools_0.2-20
## [19] textshaping_0.4.1 jquerylib_0.1.4
## [21] abind_1.4-8 cli_3.6.3
## [23] rlang_1.1.4 crayon_1.5.3
## [25] XVector_0.46.0 Biobase_2.66.0
## [27] cachem_1.1.0 DelayedArray_0.32.0
## [29] yaml_2.3.10 S4Arrays_1.6.0
## [31] tools_4.4.2 GiottoUtils_0.2.2
## [33] checkmate_2.3.2 SpatialExperiment_1.16.0
## [35] GenomeInfoDbData_1.2.13 SummarizedExperiment_1.36.0
## [37] BiocGenerics_0.52.0 R6_2.5.1
## [39] magick_2.8.5 matrixStats_1.4.1
## [41] stats4_4.4.2 lifecycle_1.0.4
## [43] zlibbioc_1.52.0 S4Vectors_0.44.0
## [45] fs_1.6.5 htmlwidgets_1.6.4
## [47] IRanges_2.40.1 ragg_1.3.3
## [49] desc_1.4.3 pkgdown_2.1.1
## [51] terra_1.8-5 bslib_0.8.0
## [53] data.table_1.16.4 Rcpp_1.0.13-1
## [55] systemfonts_1.1.0 xfun_0.49
## [57] GenomicRanges_1.58.0 MatrixGenerics_1.18.0
## [59] knitr_1.49 rjson_0.2.23
## [61] htmltools_0.5.8.1 rmarkdown_2.29
## [63] compiler_4.4.2