ESG Project Dictionary

EsgDict is an R6 class for project-specific ESG controlled vocabulary data. It stores vocabulary tables, optional request tables, normalized query indices, and source metadata used by local option discovery and legality checks.

esgdict() is a small constructor around EsgDict$new().

esgdict(project = "CMIP6")

esgdict_set_default(dict)

esgdict_get_default(project = "CMIP6")

Arguments

project: ESG project identifier, such as "CMIP6" or "CMIP6PLUS".
dict: An EsgDict object used as the package-level default dictionary for its project.

Value

esgdict() returns a new EsgDict object. esgdict_set_default() returns dict, invisibly. esgdict_get_default() returns the current package-level default dictionary for project, or NULL.

Supported projects

The dictionary currently supports "CMIP6", "CMIP6PLUS", "INPUT4MIP", "OBS4REF", "CORDEX-CMIP6", "CMIP7", and "EMD". CMIP6 dictionaries include both controlled vocabularies and CMOR request-table data. Other projects use vocabulary data only until a project-specific request source is registered.

Source downloads in examples

Building a dictionary may download upstream vocabulary/request sources when the parsed dictionary cache and raw source cache are missing. Most examples load a small installed CMIP6 example dictionary and run without network access. The example that calls $build() is wrapped in \dontrun{} so package checks do not depend on GitHub or upstream CV availability.

Author

Hongyuan Jia

Methods

Method `new()`

Create a new ESG project dictionary.

The new dictionary is empty. Use $build() to fetch and parse upstream sources, or $load() to restore a saved dictionary JSON file.

Usage

EsgDict$new(project = "CMIP6")

Arguments

project: ESG project identifier, such as "CMIP6" or "CMIP6PLUS".

Returns

An EsgDict object.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$status()

Method `project()`

Return the normalized ESG project identifier.

Usage

EsgDict$project()

Returns

A single string.

Examples

dict <- EsgDict$new(project = "CMIP6PLUS")
dict$project()

Method `profile()`

Return the internal dictionary profile.

The profile determines how project-specific vocabulary sources are parsed and normalized.

Usage

EsgDict$profile()

Returns

A single string.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$profile()

Method `version()`

Return vocabulary and request-source versions.

Empty or partially loaded dictionaries return NULL.

Usage

EsgDict$version()

Returns

A named list with vocab and request elements, or NULL.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$version()

Method `sources()`

Return upstream source metadata.

Source metadata records repository, tag/ref, commit, and local source directory information for the data used to build the dictionary.

Usage

EsgDict$sources()

Returns

A named list, or NULL for an empty dictionary.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$sources()

Method `timestamp()`

Return source vocabulary timestamps.

Timestamps are extracted from source vocabulary metadata when available.

Usage

EsgDict$timestamp()

Returns

A named list of timestamps, or NULL.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$timestamp()

Method `built_time()`

Return the time when this dictionary was built.

Usage

EsgDict$built_time()

Returns

A POSIXct value, or NULL.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$built_time()

Method `status()`

Return the dictionary lifecycle status.

Status values are:

"empty": no vocabulary/request payload is loaded.
"partial": some required payload is missing.
"built": the dictionary was built in this R session.
"loaded": the dictionary was restored from disk.

Usage

EsgDict$status()

Returns

A single string.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$status()

Method `has_data()`

Check whether the dictionary contains usable data.

A dictionary has usable data after a complete $build() or $load().

Usage

EsgDict$has_data()

Returns

TRUE or FALSE.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$has_data()

Method `is_empty()`

Check whether the dictionary is empty.

Usage

EsgDict$is_empty()

Returns

TRUE or FALSE.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$is_empty()

Method `build()`

Build the dictionary from upstream source data.

$build() resolves the configured project vocabulary source, downloads or reuses raw source files as needed, parses them into normalized tables, and builds query indices for option discovery and validation. If the dictionary already has data and force = FALSE, the object is returned unchanged.

Usage

EsgDict$build(
  token = NULL,
  force = FALSE,
  cv_tag = NULL,
  request_tag = NULL,
  dreq_tag = NULL,
  use_cache = TRUE,
  source_dir = dict__source_dir(project = private$m_project)
)

Arguments

token: Optional GitHub token used for source resolution and downloads.
force: If TRUE, rebuild even when the dictionary already has data and bypass the parsed dictionary cache.
cv_tag: Optional vocabulary source tag or ref. When NULL, the project default ref or latest tagged source is used.
request_tag: Optional request-table source tag. Used by projects that define a request source, currently CMIP6.
dreq_tag: Deprecated alias for request_tag.
use_cache: If TRUE, use the parsed dictionary cache when available. Raw source files may still be reused from source_dir.
source_dir: Directory used to read and write raw source files. The default is the package store source directory for this project.

Returns

The modified EsgDict object itself.

Examples

\dontrun{
    dict <- EsgDict$new(project = "CMIP6")
    dict$build()
    dict$has_data()
}

Method `get()`

Return raw dictionary payload data.

$get("vocab") returns the full vocabulary payload list. $get("request") and $get("dreq") return the request table when available. Any other value is interpreted as a vocabulary field name, such as "experiment_id" or "source_id".

Usage

EsgDict$get(type)

Arguments

type: Data type to retrieve. Use "vocab", "request", "dreq", or a project vocabulary field name.

Returns

A copy of the requested data.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$get("experiment_id")
dict$get("request")

Method `capabilities()`

Return available dictionary capabilities.

Capabilities describe whether vocabulary data, request data, and relation indices are currently available.

Usage

EsgDict$capabilities()

Returns

A named list with vocab, request, and relations.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$capabilities()

Method `relation_fields()`

Return supported relation-index fields.

Relation fields describe which field combinations can be used for constrained option discovery and cross-field legality checks.

Usage

EsgDict$relation_fields()

Returns

A named list of character vectors.

Examples

dict <- EsgDict$new(project = "CMIP6")
dict$relation_fields()

Method `fields()`

Return normalized dictionary field names.

Empty dictionaries return character().

Usage

EsgDict$fields()

Returns

A character vector.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$fields()

Method `indices()`

Return normalized dictionary indices.

$indices() returns all available indices. $indices(type) returns a single index table, such as "values", "variable", "activity_experiment", or "activity_source".

Usage

EsgDict$indices(type = NULL)

Arguments

type: Optional index name.

Returns

A named list of indices, or a data.table::data.table() when type is supplied.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
names(dict$indices())
dict$indices("values")

Method `options()`

Discover valid values for a dictionary field.

Constraints supplied through ... are used when a matching relation index exists. For example, CMIP6 experiment_id options can be constrained by activity_id.

Usage

EsgDict$options(field, ...)

Arguments

field: ESG dictionary field name or supported alias.
...: Optional field constraints.

Returns

A data.table::data.table() with available values and metadata. The ignored_constraints attribute records constraints that could not be applied.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$options("experiment_id", activity_id = "CMIP")

Method `check()`

Check dictionary values and relationships.

$check() validates supplied values against dictionary value indices and, when possible, validates cross-field combinations using relation indices.

Usage

EsgDict$check(
  ...,
  error = FALSE,
  suggest = TRUE,
  n_suggestions = 5L,
  relationship = c("any", "all_pairs")
)

Arguments

...: ESG dictionary field values.
error: If TRUE, throw an error when invalid values or relationships are found.
suggest: If TRUE, include near-match suggestions for invalid values.
n_suggestions: Maximum number of suggestions for each invalid value.
relationship: Relationship validation mode. "any" validates ESGF-query style OR semantics. "all_pairs" requires every supplied combination inside each relation index to exist.

Returns

An esgdict_check_result data.table::data.table().

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$check(activity_id = "CMIP", experiment_id = "historical")
dict$check(variable_id = "tas", table_id = "Amon")

Method `save()`

Save the dictionary to JSON.

If path = NULL, the dictionary is saved in the package store and registered in the store manifest. If path is supplied, only that JSON file is written.

Usage

EsgDict$save(path = NULL, allow_empty = FALSE)

Arguments

path: Optional JSON file path. If NULL, use the package store.
allow_empty: If TRUE, allow saving an empty dictionary.

Returns

The normalized output path.

Examples

dict_path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(dict_path))

path <- tempfile(fileext = ".json")
dict$save(path)
file.exists(path)

Method `load()`

Load a dictionary from JSON.

If path = NULL, the latest stored dictionary for this project is located through the package store manifest.

Usage

EsgDict$load(path = NULL)

Arguments

path: Optional JSON file path. If NULL, load the latest stored dictionary for this project.

Returns

The modified EsgDict object itself.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
restored <- EsgDict$new(project = "CMIP6")
suppressMessages(restored$load(path))
restored$has_data()

Method `print()`

Print a dictionary summary.

Usage

EsgDict$print()

Returns

The EsgDict object itself, invisibly.

Examples

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
dict$print()

Examples

example_path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- esgdict(project = "CMIP6")
suppressMessages(dict$load(example_path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$project()
#> [1] "CMIP6"

esgdict_set_default(dict)
identical(esgdict_get_default("CMIP6"), dict)
#> [1] TRUE
esgdict_option("experiment_id", activity_id = "CMIP")
#>            field      value         description pattern source
#>           <char>     <char>              <char>  <char> <char>
#> 1: experiment_id historical CMIP historical run    <NA>  vocab
esgdict_check(activity = "CMIP", experiment = "historical")
#>            field      value  valid   type        rule source constraint_fields
#>           <char>     <char> <lgcl> <char>      <char> <char>            <list>
#> 1:   activity_id       CMIP   TRUE  value field_value  vocab                  
#> 2: experiment_id historical   TRUE  value field_value  vocab                  
#>    message suggestions compatible_values
#>     <char>      <list>            <list>
#> 1:    <NA>                              
#> 2:    <NA>                              

## ------------------------------------------------
## Method `EsgDict$new`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$status()
#> [1] "empty"

## ------------------------------------------------
## Method `EsgDict$project`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6PLUS")
dict$project()
#> [1] "CMIP6PLUS"

## ------------------------------------------------
## Method `EsgDict$profile`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$profile()
#> [1] "cmip6"

## ------------------------------------------------
## Method `EsgDict$version`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$version()
#> $vocab
#> [1] ‘6.2.0’
#> 
#> $request
#> [1] ‘1.0.0’
#> 

## ------------------------------------------------
## Method `EsgDict$sources`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$sources()
#> $vocab
#> $vocab$repo
#> [1] "WCRP-CMIP/CMIP6_CVs"
#> 
#> $vocab$tag
#> [1] "test-cv"
#> 
#> $vocab$commit
#> [1] "example-vocab"
#> 
#> $vocab$source_dir
#> [1] "example"
#> 
#> 
#> $request
#> $request$repo
#> [1] "PCMDI/cmip6-cmor-tables"
#> 
#> $request$tag
#> [1] "test-request"
#> 
#> $request$commit
#> [1] "example-request"
#> 
#> $request$source_dir
#> [1] "example"
#> 
#> 

## ------------------------------------------------
## Method `EsgDict$timestamp`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$timestamp()
#> $vocab
#> [1] "2025-01-01 UTC"
#> 
#> $drs
#> [1] "2025-01-01 UTC"
#> 
#> $activity_id
#> [1] "2025-01-01 UTC"
#> 
#> $experiment_id
#> [1] "2025-01-01 UTC"
#> 
#> $frequency
#> [1] "2025-01-01 UTC"
#> 
#> $grid_label
#> [1] "2025-01-01 UTC"
#> 
#> $institution_id
#> [1] "2025-01-01 UTC"
#> 
#> $nominal_resolution
#> [1] "2025-01-01 UTC"
#> 
#> $realm
#> [1] "2025-01-01 UTC"
#> 
#> $required_global_attributes
#> [1] "2025-01-01 UTC"
#> 
#> $source_id
#> [1] "2025-01-01 UTC"
#> 
#> $source_type
#> [1] "2025-01-01 UTC"
#> 
#> $sub_experiment_id
#> [1] "2025-01-01 UTC"
#> 
#> $table_id
#> [1] "2025-01-01 UTC"
#> 

## ------------------------------------------------
## Method `EsgDict$built_time`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$built_time()
#> [1] "2025-01-04 UTC"

## ------------------------------------------------
## Method `EsgDict$status`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$status()
#> [1] "empty"

## ------------------------------------------------
## Method `EsgDict$has_data`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$has_data()
#> [1] FALSE

## ------------------------------------------------
## Method `EsgDict$is_empty`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$is_empty()
#> [1] TRUE

## ------------------------------------------------
## Method `EsgDict$build`
## ------------------------------------------------

if (FALSE) { # \dontrun{
    dict <- EsgDict$new(project = "CMIP6")
    dict$build()
    dict$has_data()
} # }

## ------------------------------------------------
## Method `EsgDict$get`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$get("experiment_id")
#>    experiment_id             experiment              description  tier
#>           <char>                 <char>                   <char> <int>
#> 1:    historical all-forcing simulation      CMIP historical run     1
#> 2:        ssp585      high-end scenario ScenarioMIP SSP5-8.5 run     1
#>    start_year end_year min_number_yrs_per_sim required_model_components
#>         <int>    <int>                  <int>                    <list>
#> 1:       1850     2014                    165                     AOGCM
#> 2:       2015     2100                     86                     AOGCM
#>    parent_experiment_id sub_experiment_id activity_id parent_activity_id
#>                  <list>            <list>      <list>             <list>
#> 1:            piControl              none        CMIP               CMIP
#> 2:           historical              none ScenarioMIP               CMIP
#>    additional_allowed_model_components
#>                                 <list>
#> 1:                                    
#> 2:                                    
dict$get("request")
#>    variable table_id modeling_realm      standard_name
#>      <char>   <char>         <char>             <char>
#> 1:      tas     Amon          atmos    air_temperature
#> 2:      tas      day          atmos    air_temperature
#> 3:    sftlf       fx           land land_area_fraction
#>                                       long_name  units cell_methods
#>                                          <char> <char>       <char>
#> 1:                 Near-Surface Air Temperature      K   time: mean
#> 2:                 Near-Surface Air Temperature      K   time: mean
#> 3: Percentage of the grid cell occupied by land      %   area: mean
#>      cell_measures comment              dimensions out_name   type positive
#>             <char>  <char>                  <char>   <char> <char>   <char>
#> 1: area: areacella    <NA> longitude latitude time      tas   real     <NA>
#> 2: area: areacella    <NA> longitude latitude time      tas   real     <NA>
#> 3: area: areacella    <NA>      longitude latitude    sftlf   real     <NA>
#>    valid_min valid_max ok_min_mean_abs ok_max_mean_abs frequency
#>       <char>    <char>          <char>          <char>    <char>
#> 1:      <NA>      <NA>            <NA>            <NA>       mon
#> 2:      <NA>      <NA>            <NA>            <NA>       day
#> 3:         0       100            <NA>            <NA>        fx

## ------------------------------------------------
## Method `EsgDict$capabilities`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$capabilities()
#> $vocab
#> [1] TRUE
#> 
#> $request
#> [1] TRUE
#> 
#> $relations
#> [1] "variable"            "activity_experiment" "activity_source"    
#> 

## ------------------------------------------------
## Method `EsgDict$relation_fields`
## ------------------------------------------------

dict <- EsgDict$new(project = "CMIP6")
dict$relation_fields()
#> $variable
#> [1] "variable_id" "table_id"    "frequency"   "realm"      
#> 
#> $activity_experiment
#> [1] "activity_id"       "experiment_id"     "sub_experiment_id"
#> 
#> $activity_source
#> [1] "activity_id"    "source_id"      "institution_id"
#> 

## ------------------------------------------------
## Method `EsgDict$fields`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$fields()
#>  [1] "activity_id"        "experiment_id"      "frequency"         
#>  [4] "grid_label"         "institution_id"     "mip_era"           
#>  [7] "nominal_resolution" "project"            "realm"             
#> [10] "source_id"          "source_type"        "sub_experiment_id" 
#> [13] "table_id"           "variable_id"        "variant_label"     

## ------------------------------------------------
## Method `EsgDict$indices`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
names(dict$indices())
#> [1] "values"              "variable"            "activity_experiment"
#> [4] "activity_source"    
dict$indices("values")
#>                  field               value
#>                 <char>              <char>
#>  1:            project               CMIP6
#>  2:            mip_era               CMIP6
#>  3:      variant_label                <NA>
#>  4:        activity_id                CMIP
#>  5:        activity_id         ScenarioMIP
#>  6:      experiment_id          historical
#>  7:      experiment_id              ssp585
#>  8:          frequency                 day
#>  9:          frequency                  fx
#> 10:          frequency                 mon
#> 11:         grid_label                  gn
#> 12:         grid_label                  gr
#> 13:     institution_id EC-Earth-Consortium
#> 14:     institution_id               CCCma
#> 15: nominal_resolution              100 km
#> 16: nominal_resolution              250 km
#> 17:              realm               atmos
#> 18:              realm                land
#> 19:          source_id           EC-Earth3
#> 20:          source_id             CanESM5
#> 21:        source_type               AOGCM
#> 22:  sub_experiment_id                none
#> 23:  sub_experiment_id               s1960
#> 24:           table_id                Amon
#> 25:           table_id                 day
#> 26:           table_id                  fx
#> 27:        variable_id                 tas
#> 28:        variable_id               sftlf
#>                  field               value
#>                 <char>              <char>
#>                                                       description
#>                                                            <char>
#>  1:                                                 CMIP6 project
#>  2:                                                 CMIP6 project
#>  3: CMIP6 realization-initialization-physics-forcing member label
#>  4:                                                 CMIP activity
#>  5:                                          ScenarioMIP activity
#>  6:                                           CMIP historical run
#>  7:                                      ScenarioMIP SSP5-8.5 run
#>  8:                                                    daily mean
#>  9:                                                   fixed field
#> 10:                                                  monthly mean
#> 11:                                                   native grid
#> 12:                                                     regridded
#> 13:                                           EC-Earth Consortium
#> 14:                                                         CCCma
#> 15:                                                          <NA>
#> 16:                                                          <NA>
#> 17:                                                    atmosphere
#> 18:                                                          land
#> 19:                                            EC-Earth version 3
#> 20:                                 Canadian Earth System Model 5
#> 21:                                                 coupled model
#> 22:                                             no sub experiment
#> 23:                                               start year 1960
#> 24:                                                          <NA>
#> 25:                                                          <NA>
#> 26:                                                          <NA>
#> 27:                                                          <NA>
#> 28:                                                          <NA>
#>                                                       description
#>                                                            <char>
#>                    pattern   source
#>                     <char>   <char>
#>  1:                   <NA> constant
#>  2:                   <NA> constant
#>  3: ^r\\d+i\\d+p\\d+f\\d+$  pattern
#>  4:                   <NA>    vocab
#>  5:                   <NA>    vocab
#>  6:                   <NA>    vocab
#>  7:                   <NA>    vocab
#>  8:                   <NA>    vocab
#>  9:                   <NA>    vocab
#> 10:                   <NA>    vocab
#> 11:                   <NA>    vocab
#> 12:                   <NA>    vocab
#> 13:                   <NA>    vocab
#> 14:                   <NA>    vocab
#> 15:                   <NA>    vocab
#> 16:                   <NA>    vocab
#> 17:                   <NA>    vocab
#> 18:                   <NA>    vocab
#> 19:                   <NA>    vocab
#> 20:                   <NA>    vocab
#> 21:                   <NA>    vocab
#> 22:                   <NA>    vocab
#> 23:                   <NA>    vocab
#> 24:                   <NA>    vocab
#> 25:                   <NA>    vocab
#> 26:                   <NA>    vocab
#> 27:                   <NA>  request
#> 28:                   <NA>  request
#>                    pattern   source
#>                     <char>   <char>

## ------------------------------------------------
## Method `EsgDict$options`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$options("experiment_id", activity_id = "CMIP")
#>            field      value         description pattern source
#>           <char>     <char>              <char>  <char> <char>
#> 1: experiment_id historical CMIP historical run    <NA>  vocab

## ------------------------------------------------
## Method `EsgDict$check`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$check(activity_id = "CMIP", experiment_id = "historical")
#>            field      value  valid   type        rule source constraint_fields
#>           <char>     <char> <lgcl> <char>      <char> <char>            <list>
#> 1:   activity_id       CMIP   TRUE  value field_value  vocab                  
#> 2: experiment_id historical   TRUE  value field_value  vocab                  
#>    message suggestions compatible_values
#>     <char>      <list>            <list>
#> 1:    <NA>                              
#> 2:    <NA>                              
dict$check(variable_id = "tas", table_id = "Amon")
#>          field  value  valid   type        rule  source constraint_fields
#>         <char> <char> <lgcl> <char>      <char>  <char>            <list>
#> 1: variable_id    tas   TRUE  value field_value request                  
#> 2:    table_id   Amon   TRUE  value field_value   vocab                  
#>    message suggestions compatible_values
#>     <char>      <list>            <list>
#> 1:    <NA>                              
#> 2:    <NA>                              

## ------------------------------------------------
## Method `EsgDict$save`
## ------------------------------------------------

dict_path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(dict_path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms

path <- tempfile(fileext = ".json")
dict$save(path)
#> [1] "/tmp/RtmpN1b3Lp/file1ad160846f84.json"
file.exists(path)
#> [1] TRUE

## ------------------------------------------------
## Method `EsgDict$load`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
restored <- EsgDict$new(project = "CMIP6")
suppressMessages(restored$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
restored$has_data()
#> [1] TRUE

## ------------------------------------------------
## Method `EsgDict$print`
## ------------------------------------------------

path <- system.file("extdata", "examples", "cmip6-dict.json", package = "epwshiftr")
dict <- EsgDict$new(project = "CMIP6")
suppressMessages(dict$load(path))
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms
dict$print()
#> ══ ESG Dictionary ══════════════════════════════════════════════════════════════
#> • Project: "CMIP6"
#> • Profile: "cmip6"
#> • Status: "loaded"
#> • Built at: 2025-01-04 UTC
#> 
#> ── Vocabulary ──────────────────────────────────────────────────────────────────
#> • Vocab Version: `6.2.0`
#> • Vocab Contents [13 types]:
#>   • drs [6 items]
#>   • activity_id [2 items]
#>   • experiment_id [2 items]
#>   • frequency [3 items]
#>   • grid_label [2 items]
#>   • institution_id [2 items]
#>   • nominal_resolution [2 items]
#>   • realm [2 items]
#>   • required_global_attributes [3 items]
#>   • source_id [2 items]
#>   • source_type [1 items]
#>   • sub_experiment_id [2 items]
#>   • table_id [3 items]
#> 
#> ── Request ─────────────────────────────────────────────────────────────────────
#> • Request Version: `1.0.0`
#> • Request Contents: 3 Variables from 3 Tables and 2 Realms

Arguments

Value

Supported projects

Source downloads in examples

See also

Author

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method project()

Usage

Returns

Examples

Method profile()

Usage

Returns

Examples

Method version()

Usage

Returns

Examples

Method sources()

Usage

Returns

Examples

Method timestamp()

Usage

Returns

Examples

Method built_time()

Usage

Returns

Examples

Method status()

Usage

Returns

Examples

Method has_data()

Usage

Returns

Examples

Method is_empty()

Usage

Returns

Examples

Method build()

Usage

Arguments

Returns

Examples

Method get()

Usage

Arguments

Returns

Examples

Method capabilities()

Usage

Returns

Examples

Method relation_fields()

Usage

Returns

Examples

Method fields()

Usage

Returns

Examples

Method indices()

Usage

Arguments

Returns

Examples

Method options()

Usage

Arguments

Method `new()`

Method `project()`

Method `profile()`

Method `version()`

Method `sources()`

Method `timestamp()`

Method `built_time()`

Method `status()`

Method `has_data()`

Method `is_empty()`

Method `build()`

Method `get()`

Method `capabilities()`

Method `relation_fields()`

Method `fields()`

Method `indices()`

Method `options()`

Method `check()`

Method `save()`

Method `load()`

Method `print()`