Skip to contents

Get or set quallmer object metadata

qlm_meta.Rd

Get or set metadata from qlm_coded, qlm_codebook, qlm_comparison, and qlm_validation objects. Metadata is organized into three types: user, object, and system. Only user metadata can be modified.

Usage

qlm_meta(x, field = NULL, type = c("user", "object", "system", "all"))

qlm_meta(x, field = NULL) <- value

Arguments

x

A quallmer object (qlm_coded, qlm_codebook, qlm_comparison, or qlm_validation).

field

Optional character string specifying a single metadata field to extract or set. If NULL (default), qlm_meta() returns all metadata of the specified type, and qlm_meta<-() expects value to be a named list.

type

Character string specifying the type of metadata to extract:

"user"

User-specified descriptive information (default). These fields are modifiable via qlm_meta<-(): name (run label) and notes (documentation).

"object"

Parameters defining how coding was executed. Read-only fields include: batch, call, chat_args, execution_args, parent, n_units, input_type.

"system"

Automatically captured environment information. Read-only fields include: timestamp, ellmer_version, quallmer_version, R_version.

"all"

Returns a named list combining all three types.

value

For qlm_meta<-(), the new value for the metadata field, or a named list of user metadata fields.

Value

qlm_meta() returns the requested metadata (a named list or single value). qlm_meta<-() returns the modified object (invisibly).

Details

Metadata is stratified into three types following the quanteda convention:

User metadata (type = "user", default): User-specified descriptive information that can be modified via qlm_meta<-(). Fields: name, notes.

Object metadata (type = "object"): Parameters and intrinsic properties set at object creation time. Read-only. Fields vary by object type but typically include: batch, call, chat_args, execution_args, parent, n_units, input_type.

System metadata (type = "system"): Automatically captured environment and version information. Read-only. Fields: timestamp, ellmer_version, quallmer_version, R_version.

For qlm_codebook objects, user metadata includes name and instructions (the codebook instructions text), both of which can be modified.

Modification via qlm_meta<-() (assignment):

Only user metadata can be modified. For qlm_coded, qlm_comparison, and qlm_validation objects, modifiable fields are name and notes. For qlm_codebook objects, modifiable fields are name and instructions.

Object and system metadata are read-only and set at creation time. Attempting to modify these will produce an informative error.

See also

  • accessors for an overview of the accessor function system

  • codebook() for extracting the codebook component

  • inputs() for extracting input data

Examples

# Load example objects
examples <- readRDS(system.file("extdata", "example_objects.rds", package = "quallmer"))
coded <- examples$example_coded_sentiment

# User metadata (default)
qlm_meta(coded)
#> $name
#> [1] "example_sentiment"
#> 
#> $notes
#> NULL
#> 
qlm_meta(coded, "name")
#> [1] "example_sentiment"

# Object metadata
qlm_meta(coded, type = "object")
#> $batch
#> [1] FALSE
#> 
#> $call
#> qlm_code(x = texts, codebook = data_codebook_sentiment, model = "openai/gpt-4.1", 
#>     name = "example_sentiment")
#> 
#> $chat_args
#> $chat_args$name
#> [1] "openai/gpt-4.1"
#> 
#> 
#> $execution_args
#> list()
#> 
#> $parent
#> NULL
#> 
#> $n_units
#> [1] 5
#> 
#> $input_type
#> [1] "text"
#> 
qlm_meta(coded, "call", type = "object")
#> qlm_code(x = texts, codebook = data_codebook_sentiment, model = "openai/gpt-4.1", 
#>     name = "example_sentiment")
qlm_meta(coded, "n_units", type = "object")
#> [1] 5

# System metadata
qlm_meta(coded, type = "system")
#> $timestamp
#> [1] "2026-02-05 01:29:17 UTC"
#> 
#> $ellmer_version
#> [1] "0.4.0"
#> 
#> $quallmer_version
#> [1] "0.2.0"
#> 
#> $R_version
#> [1] "4.5.2"
#> 
qlm_meta(coded, "timestamp", type = "system")
#> [1] "2026-02-05 01:29:17 UTC"

# All metadata
qlm_meta(coded, type = "all")
#> $user
#> $user$name
#> [1] "example_sentiment"
#> 
#> $user$notes
#> NULL
#> 
#> 
#> $object
#> $object$batch
#> [1] FALSE
#> 
#> $object$call
#> qlm_code(x = texts, codebook = data_codebook_sentiment, model = "openai/gpt-4.1", 
#>     name = "example_sentiment")
#> 
#> $object$chat_args
#> $object$chat_args$name
#> [1] "openai/gpt-4.1"
#> 
#> 
#> $object$execution_args
#> list()
#> 
#> $object$parent
#> NULL
#> 
#> $object$n_units
#> [1] 5
#> 
#> $object$input_type
#> [1] "text"
#> 
#> 
#> $system
#> $system$timestamp
#> [1] "2026-02-05 01:29:17 UTC"
#> 
#> $system$ellmer_version
#> [1] "0.4.0"
#> 
#> $system$quallmer_version
#> [1] "0.2.0"
#> 
#> $system$R_version
#> [1] "4.5.2"
#> 
#> 

# Modify user metadata
qlm_meta(coded, "name") <- "updated_run"
qlm_meta(coded, "notes") <- "Analysis notes"

# Set multiple fields at once
qlm_meta(coded) <- list(name = "final_run", notes = "Final analysis")

if (FALSE) { # \dontrun{
# This will error - object and system metadata are read-only
qlm_meta(coded, "timestamp") <- Sys.time()
} # }