ct_create_hs: Create or add hierarchical subject (hs) values in image...

In ct: Camera Trap Data Management and Multi-Method Ecological Analysis

Create or add hierarchical subject (hs) values in image metadata

Description

Adds hierarchical subject metadata to image files. Hierarchical subjects follow a parent|child structure, allowing for organized taxonomic or categorical classification of images.

Usage

ct_create_hs(
  path,
  value = NULL,
  overwrite = FALSE,
  recursive = FALSE,
  intern = TRUE,
  quiet = TRUE,
  ...
)

Arguments

path	A character string specifying the full path to an image file or directory. If a directory is provided, hierarchical subjects will be added to all supported image files in that directory.
value	A named character vector specifying hierarchical subjects to add. Names represent parent categories, values represent child categories. Simple format: c("Species" = "Vulture", "Location" = "Africa") creates "Species|Vulture" and "Location|Africa". Multiple values format: c("Species" = "Mammal, Bird", "Count" = "2, 3") creates "Species|Mammal", "Species|Bird", "Count|2", and "Count|3". All parents must have equal number of comma-separated values.
overwrite	Logical. If TRUE, replaces existing hierarchical subjects. If FALSE (default), adds to existing subjects. Default: FALSE.
recursive	Logical. If TRUE and path is a directory, searches for images recursively in subdirectories. Default: FALSE.
intern	Logical. If TRUE, returns output as a character vector. Default: TRUE.
quiet	Logical. If TRUE, suppresses command output. Default: TRUE.
...	Additional arguments passed to system2().

Details

Two input formats are supported:

1. Simple format: One child per parent, e.g., c("Species" = "Vulture")

2. Multiple values format: Multiple children per parent using comma-separated values, e.g., c("Species" = "Mammal, Bird, Reptile"). When using this format, all parents must have the same number of comma-separated values.

The function validates that all values have parent categories (names) and preserves existing hierarchical subjects unless overwrite = TRUE. Duplicate parent|child combinations are automatically removed.

When processing directories, the function applies hierarchical subjects to all supported image files found. Use recursive = TRUE to include subdirectories.

When using comma-separated values, the function splits each value string and creates separate hierarchical subjects for each position across all parents.

Value

Invisibly returns TRUE on success. Called primarily for side effects (modifying image metadata).

See Also

• ct_get_hs() to retrieve hierarchical subjects

• ct_remove_hs() to remove hierarchical subjects

• ct_read_metadata() to read image metadata

Examples

## Not run: 
# Path to example image
image_path <- file.path(system.file("img", package = "ct"), "large.jpeg")

# Simple format: single child per parent
ct_create_hs(path = image_path, value = c("Species" = "Vulture"))
ct_get_hs(path = image_path) # Returns: "Species|Vulture"

# Simple format: multiple parents, one child each
ct_create_hs(
  path = image_path,
  value = c("Species" = "Vulture",
            "Location" = "Africa",
            "Status" = "Endangered")
)
ct_get_hs(path = image_path, into_tibble = TRUE)

# Multiple values format: recording multiple observations
ct_create_hs(
  path = image_path,
  value = c(
    "Species" = "Gyps_africanus, Kobus_kob",
    "Sex" = "Male, Female",
    "Count" = "3, 2"
  ),
  overwrite = TRUE
)
ct_get_hs(path = image_path)

# Parse Hierarchical Subject to tibble
ct_get_hs(path = image_path, into_tibble = TRUE)

# Overwrite existing hierarchical subjects
ct_create_hs(
  path = image_path,
  value = c("Species" = "Eagle"),
  overwrite = TRUE
)

## End(Not run)

ct documentation built on Oct. 22, 2026, 1:07 a.m.