ESGF Query results for Dataset type

EsgResultDataset is a class that represents query results for Dataset type from ESGF search RESTful API.

In general, there is no need to create an EsgResultDataset manually. Usually, it is created by calling EsgQuery$collect().

Author

Hongyuan Jia

Super class

epwshiftr::EsgResult -> EsgResultDataset

Methods

Public methods

• EsgResultDataset$to_data_table()

• EsgResultDataset$has_opendap()

• EsgResultDataset$has_download()

• EsgResultDataset$collect()

• EsgResultDataset$expand_replicas()

• EsgResultDataset$print()

• EsgResultDataset$clone()

Inherited methods

• epwshiftr::EsgResult$count()
• epwshiftr::EsgResult$filter()
• epwshiftr::EsgResult$initialize()
• epwshiftr::EsgResult$load()
• epwshiftr::EsgResult$query_url()
• epwshiftr::EsgResult$reachable()
• epwshiftr::EsgResult$save()
• epwshiftr::EsgResult$selection()
• epwshiftr::EsgResult$slice()
• epwshiftr::EsgResult$to_dt()

---

Method to_data_table()

Convert the results into a data.table

Usage

EsgResultDataset$to_data_table(fields = NULL, formatted = FALSE)

Arguments

fields

A non-empty character vector indicating the fields to put into the data.table. If NULL, all fields in the query result will be used. Default: NULL.

formatted

Whether to use formatted values for special fields, including url and size. Default: FALSE.

Returns

A data.table.

---

Method has_opendap()

Check if there are OPeNDAP support for the datasets

Usage

EsgResultDataset$has_opendap()

Returns

A logical vector.

---

Method has_download()

Check if there are HTTPServer download URL for the datasets

Usage

EsgResultDataset$has_download()

Returns

A logical vector.

---

Method collect()

Collect file or aggregation information for current datasets

$collect() sends a query with type=File or **type=aggregation (based on the specified type) for current datasets and returns an EsgResultFile or EsgResultAggregation object, respectively.

The following fields are always included in the results:

• For File query: activity_id, checksum, checksum_type, data_node, dataset_id, id, instance_id, institution_id, master_id, replica, size, title, tracking_id, url, version.

• For Aggregation query: activity_id, data_node, dataset_id, id, instance_id, institution_id, master_id, replica, size, title, url, version.

Usage

EsgResultDataset$collect(
  which = NULL,
  fields = NULL,
  all = FALSE,
  limit = 100L,
  type = "File",
  index_node = NULL,
  progress = getOption("epwshiftr.progress", interactive()),
  ...
)

Arguments

which

A character vector giving the value of dataset ID or an integer vector giving the indices of the dataset. If NULL, all datasets will be sent. Empty dataset results return empty child results without sending another ESGF query. Default: NULL.

fields

A character vector indicating the value of fields parameter when sending the query. If NULL, all available fields will be included. Default: NULL.

all

A flag. Whether to collect all results. Default: FALSE.

limit

If all = FALSE, the maximum number of child records to collect in this request. If all = TRUE, the page size used for each paginated request, not a total cap. If NULL, the allowed maximum limit number 10000 is used. Default: 100L.

type

A string indicating the query type. Should be one of File or Aggregation. Default: "File".

index_node

Optional ESGF index node used for the child query. If NULL, the index node that created the Dataset result is used. Default: NULL.

progress

Whether to show a progress bar while collecting ESGF child search pages. By default, the value of option epwshiftr.progress is used, falling back to interactive().

...

Optional child-result scope filter data_node, plus the control parameters replica, distrib, latest, and shards. Query-level parameters such as datetime_start and datetime_stop cannot be passed through .... File/Aggregation collection does not use ESGF datetime search parameters; call $filter_time() on the returned result for time filtering. If control parameters are omitted, they are inherited from the dataset query when available, with distrib = TRUE as fallback. If latest is omitted and was not set on the dataset query, no latest constraint is sent. For details on possible parameters, please see esg_query(). When a local EsgDict is available for the query project, child collection performs a warning-only dictionary check before sending the query. Missing local dictionaries are ignored and never downloaded. Aggregation collection uses dataset_id plus explicit child filters in ...; parent Dataset facet filters are not inherited because Aggregation records on standard ESGF search nodes do not necessarily expose the same facet fields as Dataset records.

Returns

• If type="File", an EsgResultFile object

• If type="Aggregation", an EsgResultAggregation object

---

Method expand_replicas()

Query ESGF for Dataset master and replica records.

Usage

EsgResultDataset$expand_replicas(
  by = c("instance_id", "master_id"),
  all = TRUE,
  index_node = NULL
)

Arguments

by

Replica identity key. Use "instance_id" to retrieve same-version Dataset replicas, or "master_id" to retrieve all versions and replicas for the logical Dataset. Default: "instance_id".

all

Whether to retrieve all matching records. Default: TRUE.

index_node

Optional ESGF index node used for the replica query. If NULL, the index node that created this result is used. Default: NULL.

Returns

A new EsgResultDataset object with expanded Dataset records when the requested identity key is available; otherwise self.

---

Method print()

Print a summary of the current dataset

Usage

EsgResultDataset$print(n = 10L)

Arguments

n

An integer indicating how many items to print. If NULL, all items will be printed. Default: 10L.

Returns

The EsgResultDataset object itself, invisibly.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

EsgResultDataset$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.