Skip to contents

Create giotto polygons object

Source: R/create.R
createGiottoPolygon.Rd

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 class 'character'
createGiottoPolygon(x, ...)

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

# S4 method for class '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 class '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, a terra SpatRaster, or some other data class readable by terra::rast()

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

giottoPolygon

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

# ------- 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)

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))