Create giotto polygons object — createGiottoPolygon • GiottoClass

Create a giottoPolygon object that is used to represent spatial annotations and polygons. Inputs can be from a structured data.frame object where three of the columns should correspond to x/y vertices and the polygon ID and additional columns are set as attributes, a spatial file such as wkt, .shp, or .GeoJSON, or a mask file (e.g. segmentation results).
The character method is for file reading and will dispatch to specific methods based on what kind of data the file was.

Usage

# S4 method for character
createGiottoPolygon(x, ...)

# S4 method for SpatVector
createGiottoPolygon(x, name = "cell", calc_centroids = FALSE, verbose = TRUE)

# S4 method for SpatRaster
createGiottoPolygon(
  x,
  name = "cell",
  mask_method = c("guess", "single", "multiple"),
  remove_background_polygon = FALSE,
  background_algo = c("range"),
  fill_holes = TRUE,
  poly_IDs = NULL,
  ID_fmt = "cell_",
  flip_vertical = TRUE,
  shift_vertical_step = TRUE,
  flip_horizontal = TRUE,
  shift_horizontal_step = TRUE,
  remove_unvalid_polygons = TRUE,
  calc_centroids = FALSE,
  verbose = TRUE
)

# S4 method for data.frame
createGiottoPolygon(
  x,
  name = "cell",
  calc_centroids = FALSE,
  skip_eval_dfr = FALSE,
  copy_dt = TRUE,
  verbose = TRUE
)

createGiottoPolygonsFromMask(
  maskfile,
  mask_method = c("guess", "single", "multiple"),
  name = "cell",
  remove_background_polygon = FALSE,
  background_algo = c("range"),
  fill_holes = TRUE,
  poly_IDs = NULL,
  ID_fmt = "cell_",
  flip_vertical = TRUE,
  shift_vertical_step = TRUE,
  flip_horizontal = TRUE,
  shift_horizontal_step = TRUE,
  calc_centroids = FALSE,
  remove_unvalid_polygons = TRUE,
  verbose = FALSE
)

createGiottoPolygonsFromDfr(
  segmdfr,
  name = "cell",
  calc_centroids = FALSE,
  verbose = TRUE,
  skip_eval_dfr = FALSE,
  copy_dt = TRUE
)

createGiottoPolygonsFromGeoJSON(
  GeoJSON,
  name = "cell",
  calc_centroids = FALSE,
  verbose = TRUE
)

Arguments

x: input. Filepath to a .GeoJSON or a mask image file. Can also be a data.frame with vertex 'x', 'y', and 'poly_ID' information.
...: additional params to pass. For character method, params pass to SpatRaster or SpatVector methods, depending on whether x was a filepath to a maskfile or a spatial file (ex: wkt, shp, GeoJSON) respectively.
name: name for the giottoPolygon object created
calc_centroids: (default FALSE) calculate centroids for polygons
verbose: be verbose
mask_method: how the mask file defines individual segmentation annotations. See mask_method section
remove_background_polygon: try to remove background polygon (default: FALSE)
background_algo: algorithm to remove background polygon
fill_holes: fill holes within created polygons
poly_IDs: character vector. Default = NULL. Custom unique names for each polygon in the mask file.
ID_fmt: character. Only applied if poly_IDs = NULL. Naming scheme for poly_IDs. Default = "cell_". See ID_fmt section.
flip_vertical: flip mask figure in a vertical manner
shift_vertical_step: shift vertical (boolean or numerical)
flip_horizontal: flip mask figure in a horizontal manner
shift_horizontal_step: shift horizontal (boolean or numerical)
remove_unvalid_polygons: remove unvalid polygons (default: TRUE)
skip_eval_dfr: (default FALSE) skip evaluation of provided dataframe
copy_dt: (default TRUE) if segmdfr is provided as dt, this determines whether a copy is made
maskfile: path to mask file
segmdfr: data.frame-like object with polygon coordinate information (x, y, poly_ID) with x and y being vertex information for the polygon referenced by poly_ID. See details for how columns are selected for coordinate and ID information.
GeoJSON: path to .GeoJSON file

Value

a giotto polygon object

Details

When determining which column within tabular data is intended to provide polygon information, Giotto first checks the column names for 'x', 'y', and 'poly_ID'. If any of these are discovered, they are directly selected. If this is not discovered then Giotto checks the data type of the columns and selects the first 'character' type column to be 'poly_ID' and the first two 'numeric' columns as 'x' and 'y' respectively. If this is also unsuccessful then poly_ID defaults to the 3rd column. 'x' and 'y' then default to the 1st and 2nd columns.

mask_method

One of "single", "multiple", or "guess".

"single" assumes that the provided mask image is binary, with only polygon vs background being distinct values. With this kind of image, the expected generated polygons is a single multipart polygon. "single" takes this multipart polygon and breaks it apart into individual singlepart polygons. An initial simple numeric index as the 'nth' polygon found in the mask image will be applied as an ID (see ID_fmt section).
"multiple" assumes that the provided mask image has distinct intensity values to specify the IDs of individual polygons. An initial numeric ID is applied as the intensity value of the pixels that made up the annotation for that polygon in the mask image (see ID_fmt section).
"guess" examines the values in the image to pick the most likely appropriate method out of "single" or "multiple".

ID_fmt

Defaults to applying the input as a prefix (using paste0()) to the numerical ID values detected by mask_method. (ie: ID_fmt = "cell_" produces cell_1, cell_2, cell_3, ...)
If a "%" character is detected in the input then the input will be treated as a sprintf() fmt param input instead. (ie: ID_fmt = "cell_%03d" produces cell_001, cell_002, cell_003, ...)

Examples

# %%%%%%%%% `createGiottoPolygon()` examples %%%%%%%%% #
# ------- create from a mask image ------- #
m <- system.file("extdata/toy_mask_multi.tif", package = "GiottoClass")
plot(terra::rast(m), col = grDevices::hcl.colors(7))

gp <- createGiottoPolygon(
    m,
    flip_vertical = FALSE, flip_horizontal = FALSE,
    shift_horizontal_step = FALSE, shift_vertical_step = FALSE,
    ID_fmt = "id_test_%03d",
    name = "test"
)
plot(gp, col = grDevices::hcl.colors(7))


# ------- create from an shp file ------- #
shp <- system.file("extdata/toy_poly.shp", package = "GiottoClass")
# vector inputs do not have params for flipping and shifting
gp2 <- createGiottoPolygon(shp, name = "test")
#> Selecting attribute "poly_ID" as poly_ID
plot(gp2, col = grDevices::hcl.colors(7))


# ------- create from data.frame-like ------- #
shp <- system.file("extdata/toy_poly.shp", package = "GiottoClass")
gpoly <- createGiottoPolygon(shp, name = "test")
#> Selecting attribute "poly_ID" as poly_ID
plot(gpoly)

gpoly_dt <- data.table::as.data.table(gpoly, geom = "XY")
needed_cols_dt <- gpoly_dt[, .(geom, part, x, y, hole, poly_ID)]
force(needed_cols_dt)
#> Key: <geom>
#>       geom  part        x        y  hole poly_ID
#>      <int> <num>    <num>    <num> <num>  <char>
#>   1:     1     1 7.000000 5.000000     0       a
#>   2:     1     1 7.000000 5.000000     0       a
#>   3:     1     1 6.937166 4.502620     0       a
#>   4:     1     1 6.752613 4.036493     0       a
#>   5:     1     1 6.457937 3.630906     0       a
#>  ---                                            
#> 183:     7     1 7.071654 9.688656     0       g
#> 184:     7     1 7.457937 9.369094     0       g
#> 185:     7     1 7.752613 8.963507     0       g
#> 186:     7     1 7.937166 8.497380     0       g
#> 187:     7     1 8.000000 8.000000     0       g

out <- createGiottoPolygon(needed_cols_dt,
    name = "test"
)
#>   Selecting col "poly_ID" as poly_ID column
#>   Selecting cols "x" and "y" as x and y respectively
plot(out)

# %%%%%%%%% `createGiottoPolygonsFromMask()` examples %%%%%%%%% #
mask_multi <- system.file("extdata/toy_mask_multi.tif",
    package = "GiottoClass"
)
mask_single <- system.file("extdata/toy_mask_single.tif",
    package = "GiottoClass"
)
plot(terra::rast(mask_multi), col = grDevices::hcl.colors(7))

plot(terra::rast(mask_single))


gpoly1 <- createGiottoPolygonsFromMask(
    mask_multi,
    flip_vertical = FALSE, flip_horizontal = FALSE,
    shift_horizontal_step = FALSE, shift_vertical_step = FALSE,
    ID_fmt = "id_test_%03d",
    name = "multi_test"
)
plot(gpoly1, col = grDevices::hcl.colors(7))


gpoly2 <- createGiottoPolygonsFromMask(
    mask_single,
    flip_vertical = FALSE, flip_horizontal = FALSE,
    shift_horizontal_step = FALSE, shift_vertical_step = FALSE,
    ID_fmt = "id_test_%03d",
    name = "single_test"
)
#>   Selecting col "part" as poly_ID column
#>   Selecting cols "x" and "y" as x and y respectively
plot(gpoly2, col = grDevices::hcl.colors(5))