Skip to contents

Explain a Derived Trait

explain_trait.Rd

This function provides a human-readable English explanation of what a derived trait represents. It works with trait functions created by the trait factories prop(), ratio(), wmean(), total(), and wsum(), and works best with traits defined by built-in meta-properties.

Usage

explain_trait(
  trait_fn,
  use_ai = FALSE,
  custom_mp = NULL,
  provider = getOption("glydet.ai_provider", "deepseek"),
  model = getOption("glydet.ai_model", NULL),
  api_key = getOption("glydet.ai_api_key", NULL),
  base_url = getOption("glydet.ai_base_url", NULL)
)

Arguments

trait_fn

A derived trait function created by one of the trait factories.

use_ai

[Experimental] Whether to use a Large Language Model (LLM) to explain the trait. Default is FALSE. To use this feature, you need to install the ellmer package. DeepSeek is used by default for backward compatibility. Other ellmer providers can be selected with provider, model, and provider-specific API key configuration.

custom_mp

A named character vector of custom meta-properties. The names are the meta-property names, and the values are in the format "(type) description". Only used when use_ai = TRUE.

provider

AI provider passed to ellmer when use_ai = TRUE. One of "deepseek", "openai", "anthropic", "gemini", "openrouter", or "openai_compatible". "google_gemini" is accepted as an alias for "gemini". Defaults to getOption("glydet.ai_provider", "deepseek").

model

Model to use when use_ai = TRUE. Defaults to getOption("glydet.ai_model"), or "deepseek-chat" for DeepSeek and the provider default for other providers.

api_key

API key for the selected provider. If NULL, the provider specific environment variable is used. Defaults to getOption("glydet.ai_api_key").

base_url

Optional base URL for custom or OpenAI-compatible endpoints. Defaults to getOption("glydet.ai_base_url").

Value

A character string containing a concise English explanation of the trait.

Examples

# Explain built-in traits
explain_trait(traits_basic()$TM)
#> [1] "Proportion of high-mannose glycans among all glycans."
explain_trait(traits_basic()$GS)
#> [1] "Abundance-weighted mean of degree of sialylation per galactose among all glycans."

# Explain custom traits
explain_trait(prop(nFc > 0))
#> [1] "Proportion of core-fucosylated glycans among all glycans."
explain_trait(prop(nFc > 0, within = (Tp == "complex")))
#> [1] "Proportion of core-fucosylated glycans within complex glycans."
explain_trait(ratio(Tp == "complex", Tp == "hybrid"))
#> [1] "Ratio of complex glycans to hybrid glycans among all glycans."
explain_trait(wmean(nA, within = (Tp == "complex")))
#> [1] "Abundance-weighted mean of antenna count within complex glycans."
explain_trait(wmean(nS / nG, within = nA == 4 & nFc > 0))
#> [1] "Abundance-weighted mean of degree of sialylation per galactose within tetra-antennary glycans with core-fucosylation."

# Explain total and wsum traits
explain_trait(total(Tp == "complex"))
#> [1] "Total abundance of complex glycans."
explain_trait(wsum(nS))
#> [1] "Abundance-weighted sum of sialic acid count among all glycans."
explain_trait(wsum(nS, within = (Tp == "complex")))
#> [1] "Abundance-weighted sum of sialic acid count within complex glycans."