subset_handling_functions {segmetric}

Subset handling functions

Description

These functions are intended to be used in new metric extensions. They handle subset_sf data (inherited from sf class) stored in segmetric objects.

• sm_list() lists subsets already computed and stored in a segmetric object.

• sm_exists() verifies if a subset_id exists in a segmetric object.

• sm_subset() evaluates and stores a subset_sf object.

• sm_indirect() finds the subset_id of a given subset_sf object stored in a segmetric object.

• sm_segmetric() returns the segmetric object that stores a given subset object (either a ref_sf, a seg_sf, or a subset_sf).

• sm_get() retrieves a subset_sf object stored in a segmetric object.

• sm_inset() operator equivalent to inner join but returns only objects from s1, or its corresponding row in s2 if parameter return_index is TRUE.

• sm_group_by(): Apply a function to groups of subset_sf.

Usage

sm_list(m)

sm_exists(m, subset_id)

sm_subset(m, subset_id, expr = NULL)

sm_indirect(s)

sm_segmetric(s)

sm_get(m, subset_id)

sm_ref(m)

sm_seg(m)

sm_inset(s1, s2, return_index = FALSE)

## S3 method for class 'ref_sf'
sm_inset(s1, s2, return_index = FALSE)

## S3 method for class 'seg_sf'
sm_inset(s1, s2, return_index = FALSE)

## S3 method for class 'subset_sf'
sm_inset(s1, s2, return_index = FALSE)

sm_group_by(s, by, fn, ...)

Arguments

m

A segmetric object.

subset_id

A character value informing a subset name.

expr

A valid piece of code in R inside curly braces. This code is evaluated to generate a subset.

s, s1, s2

Either a ref_sf, a seg_sf, or a subset_sf object.

return_index

A logical value indicating if the corresponding rows in s1 should be returned instead of the actual corresponding values of s2.

by

A character value with the column to group.

fn

A function to apply on each group.

...

For sm_group_by(), extra parameter to pass to fn function.

Value

• sm_list(): Return a character vector with all names of subsets stored in the segmetric object.

• sm_exists(): Return a logical value indicating if a given subset name is stored in the segmetric object.

• sm_subset(): Return a subset_sf object.

• sm_indirect(): Return the subset name of a given subset_sf object stored in a segmetric object.

• sm_segmetric(): Return a segmetric object that stores a given subset_sf object.

• sm_get(): Return a subset_sf object stored in a segmetric object.

• sm_inset(): Return either a subset_sf object or an integer vector with the index of corresponding rows of s2 object.

• sm_group_by(): Return a subset_sf object.

Examples

# load sample datasets
data("sample_ref_sf", package = "segmetric")
data("sample_seg_sf", package = "segmetric")

# create segmetric object
m <- sm_read(ref_sf = sample_ref_sf, seg_sf = sample_seg_sf)

# lists only 'ref_sf' and 'seg_sf'
sm_list(m)

# computes 'Y_tilde' subset and stores it as 'test_subset' subset id
# sm_ytilde(m) also stores a subset under 'Y_tilde' id
s <- sm_subset(m, "test_subset", sm_ytilde(m))

# lists 'ref_sf', 'seg_sf', 'test_subset', and 'Y_tilde'
sm_list(m)

# which segmetric object stores `s` subset?
m2 <- sm_segmetric(s)

# m is identical to m2
identical(m, m2)

# which name `s` subset is stored in `m` segmetric object?
sm_indirect(s)

# retrieve 'test_subset' data from `m` object
s2 <- sm_get(m, 'test_subset')

# s is identical to s2
identical(s, s2)