retrieve {PubChemR}

Retrieve Information from PubChem Instances

Description

This generic function extracts a specific slot from a PubChem instance.

Usage

retrieve(object, ...)

## S3 method for class 'PubChemInstance'
retrieve(object, .slot = NULL, .to.data.frame = TRUE, .verbose = FALSE, ...)

## S3 method for class 'PubChemInstanceList'
retrieve(
  object,
  .which = NULL,
  .slot = NULL,
  .to.data.frame = TRUE,
  .combine.all = FALSE,
  ...
)

## S3 method for class 'PC_Substance'
retrieve(
  object,
  .slot = NULL,
  .idx = 1,
  .to.data.frame = TRUE,
  .verbose = FALSE,
  ...
)

## S3 method for class 'PugViewInstance'
retrieve(object, .slot = NULL, .to.data.frame = TRUE, ...)

## S3 method for class 'PugViewSection'
retrieve(object, .slot = NULL, .to.data.frame = FALSE, ...)

Arguments

object

An object returned from a PubChem request.

...

Additional arguments passed to other methods.

.slot

A string specifying which slot to return. Should not be NULL or length of >1 with some exceptions. See the notes for details.

.to.data.frame

A logical value. If TRUE, the returned object will be converted into a data.frame (or tibble). If conversion to a data.frame fails, a list will be returned with a warning. Be cautious with complex lists (i.e., many elements nested within each other) as it may be time-consuming to convert such lists into a data frame. Additionally, .to.data.frame is ignored in specific scenarios.

.verbose

A logical value. Should the resulting object be printed to the R console? If TRUE, the object is returned invisibly and the output is printed nicely to the R console. This option may not be available for some slots (or classes). See Notes/Details.

.which

A character value. This is the identifier of the PubChem request that will be extracted from the complete list. It is ignored if .combine.all = TRUE.

.combine.all

a logical value. If TRUE, the properties of all requested instances are combined into a single data frame (or a list if .to.data.frame = FALSE).

.idx

An integer indicating which substance result should be returned. A PubChem request may return multiple substances in the output. .idx specifies the index of the substance to be extracted from the complete list.

Details on 'PugViewInstance' and 'PugViewSection'

The PugView API returns a detailed list related to PubChem requests. The 'Section' slot in this list is structured into a sub-class called 'PugViewSection'. This object contains information organized through several sections (or sub-sections), which can be retrieved using section-specific functions such as section and sectionList.

The function argument .to.data.frame is ignored if the "Section" slot is being extracted from the complete list. For other slots, .to.data.frame is considered as usual. See examples for usage.

Note

If the object is from the 'PC_Properties' class, the .slot can be defined as NULL. If .slot = NULL, retrieve() will return all available properties. If 'object' is of class other than 'PC_Properties', .slot should be length of 1.

Extracting multiple slots.

In some cases, it may be practical to extract multiple slots from 'object'. For example, one may wish to extract properties from the output of get_properties by running the functions in a loop. See codes below for a practical example:

  library(dplyr)

  props <- get_properties(
    properties = c("MolecularWeight", "MolecularFormula", "HBondDonorCount",
                   "HBondAcceptorCount", "InChIKey", "InChI"),
    identifier = 2244,
    namespace = "cid",
    propertyMatch = list(
      .ignore.case = TRUE,
      type = "contain"
    )
  )

  bind_columns <- function(x, ...){
    part1 <- x[[1]][ ,"Identifier"]
    part2 <- lapply(x, "[", 2) 
      bind_cols()

    bind_cols(part1, part2)
  }

  propsToExtract <- c("MolecularWeight", "MolecularFormula", "HBondDonorCount")
  tmp <- lapply(propsToExtract, retrieve, object = props, .which = "2244")
  bind_columns(tmp)

Use of the '.verbose' argument

retrieve returns output silently (invisibly) when .verbose = TRUE. However, the function behaves differently under the following scenarios:

• .verbose is ignored if .combine.all = TRUE. The output is returned silently.

• .verbose is ignored if the requested slot is not printable to the R console because it is too complicated to print.

Examples

compounds <- get_compounds(
  identifier = c("aspirin", "ibuprofen", "rstudio"),
  namespace = "name"
 )

# Extract information for "aspirin"
aspirin <- instance(compounds, "aspirin")
# print(aspirin)

# Extract a specific slot from the "aspirin" compound.
retrieve(aspirin, "props", .to.data.frame = TRUE)

# Examples (PubChemInstanceList)
retrieve(compounds, "aspirin", "props", .to.data.frame = TRUE)

# Verbose Assay References to R Console
assays <- get_assays(identifier = c(1234, 7815), namespace = "aid")

instance(assays, "7815")
retrieve(assays, "7815", "xref", .verbose = TRUE)

# Print assay protocol to R console (if available)
# Note that it may be too long to print for some assays.
# retrieve(assays, "1234", "protocol", .verbose = TRUE)

# No protocol is available for assay "1234".
# retrieve(assays, "7815", "protocol", .verbose = TRUE)

# Ignores ".verbose" and ".which" if ".combine.all = TRUE".
retrieve(assays, .slot = "xref", .verbose = TRUE, .combine.all = TRUE)

### PUG VIEW EXAMPLES ###
pview <- get_pug_view(identifier = "2244", annotation = "data", domain = "compound")

# PugViewSectionList object.
# This object contains all the section information related to the PubChem request.
sect <- retrieve(pview, .slot = "Section")
print(sect)

retrieve(pview, .slot = "RecordType", .to.data.frame = TRUE)