Package 'PubChemR'

Assay, Compound, and Substance Identifiers

Description

These functions are used to retrieve identification information for assays, substances, and compounds from the PubChem database.

Usage

AIDs(object, ...)

CIDs(object, ...)

SIDs(object, ...)

## S3 method for class 'PubChemInstance_AIDs'
AIDs(object, .to.data.frame = TRUE, ...)

## S3 method for class 'PubChemInstance_CIDs'
CIDs(object, .to.data.frame = TRUE, ...)

## S3 method for class 'PubChemInstance_SIDs'
SIDs(object, .to.data.frame = TRUE, ...)

Arguments

object	An object returned from a PubChem request, typically generated by functions such as get_cids, get_aids, and get_sids.
...	Additional arguments passed to other methods. Currently, these arguments have no effect.
.to.data.frame	a logical. If TRUE, returned object will be forced to be converted into a data.frame (or tibble). If failed to convert into a data.frame, a list will be returned with a warning. Be careful for complicated lists (i.e., many elements nested within each other) since it may be time consuming to convert such lists into a data frame.

Examples

# Retrieve Assay IDs
aids <- get_aids(identifier = c("aspirin", "caffeine"), namespace = "name")
AIDs(aids)

# Compound IDs
cids <- get_cids(identifier = c("aspirin", "caffein"), namespace = "name")
CIDs(cids)

# Substance IDs
sids <- get_sids(identifier = c("aspirin", "caffein"), namespace = "name")
SIDs(sids)

---

Download Content from PubChem and Save to a File

Description

This function sends a request to PubChem to retrieve content in the specified format for a given identifier. It then writes the content to a specified file path.

Usage

download(
  filename = NULL,
  outformat,
  path,
  identifier,
  namespace = "cid",
  domain = "compound",
  operation = NULL,
  searchtype = NULL,
  overwrite = FALSE,
  options = NULL
)

Arguments

filename	a character string specifying the file name to be saved. If not specified, a default file name "file" is used.
outformat	A character string specifying the desired output format (e.g., "sdf", "json").
path	A character string specifying the path where the content should be saved.
identifier	A vector of positive integers (e.g. cid, sid, aid) or identifier strings (source, inchikey, formula). In some cases, only a single identifier string (name, smiles, xref; inchi, sdf by POST only).
namespace	Specifies the namespace for the query. For the 'compound' domain, possible values include 'cid', 'name', 'smiles', 'inchi', 'sdf', 'inchikey', 'formula', 'substructure', 'superstructure', 'similarity', 'identity', 'xref', 'listkey', 'fastidentity', 'fastsimilarity_2d', 'fastsimilarity_3d', 'fastsubstructure', 'fastsuperstructure', and 'fastformula'. For other domains, the possible namespaces are domain-specific.
domain	Specifies the domain of the query. Possible values are 'substance', 'compound', 'assay', 'gene', 'protein', 'pathway', 'taxonomy', 'cell', 'sources', 'sourcetable', 'conformers', 'annotations', 'classification', and 'standardize'.
operation	Specifies the operation to be performed on the input records. For the 'compound' domain, possible operations include 'record', 'property', 'synonyms', 'sids', 'cids', 'aids', 'assaysummary', 'classification', 'xrefs', and 'description'. The available operations are domain-specific.
searchtype	Specifies the type of search to be performed. For structure searches, possible values are combinations of 'substructure', 'superstructure', 'similarity', 'identity' with 'smiles', 'inchi', 'sdf', 'cid'. For fast searches, possible values are combinations of 'fastidentity', 'fastsimilarity_2d', 'fastsimilarity_3d', 'fastsubstructure', 'fastsuperstructure' with 'smiles', 'smarts', 'inchi', 'sdf', 'cid', or 'fastformula'.
overwrite	A logical value indicating whether to overwrite the file if it already exists. Default is FALSE.
options	Additional arguments.

Value

No return value. The function writes the content to the specified file path and prints a message indicating the save location.

Examples

# Download JSON file for the compound "aspirin" into "Aspirin.JSON"
# A folder named "Compound" will be created under current directory"
download(
  filename = "Aspirin",
  outformat = "json",
  path = "./Compound",
  identifier = "aspirin",
  namespace = "name",
  domain = "compound",
  overwrite = TRUE
)

# Remove downloaded files and folders.
file.remove("./Compound/Aspirin.json")
file.remove("./Compound/")

---

Retrieve Assay IDs (AIDs) from PubChem

Description

This function queries the PubChem database to retrieve Assay IDs (AIDs) based on a given identifier.

Usage

get_aids(
  identifier,
  namespace = "cid",
  domain = "compound",
  searchtype = NULL,
  options = NULL
)

Arguments

identifier	A vector of identifiers, either numeric or character. The type of identifier depends on the namespace and domain parameters. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values depend on the domain parameter and include: - For domain = 'compound': cid, name, smiles, inchi, sdf, inchikey, formula, etc. - For domain = 'substance': sid, sourceid/<source id>, sourceall/<source name>, name, etc. - For domain = 'assay': aid, listkey, type/<assay type>, sourceall/<source name>, etc. For more details, see the Input section.
domain	A character string specifying the domain of the query. Possible values are: - compound (default) - substance - assay - Other domains as specified in the API documentation.
searchtype	An optional character string specifying the search type. Possible values depend on the namespace and domain. Examples include: - substructure, superstructure, similarity, identity for structure searches. - fastidentity, fastsimilarity_2d, fastsimilarity_3d, etc. for fast searches. If NULL (default), no search type is specified.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstance_AIDs', which is a list containing information retrieved from the PubChem database. Assay IDs can be extracted from the returned object using the getter function AIDs.

Note

To extract assay IDs from returned object, one may use AIDs function. See examples.

See Also

AIDs, get_pug_rest

Examples

# Request for multiple assays
# If assay identifier is unknown or incorrect, an error returns from PubChem Database
aids <- get_aids(
  identifier = c("aspirin", "ibuprofen", "rstudio"),
  namespace = "name"
)

print(aids)

# Return all Assay IDs.
AIDs(aids)

---

Retrieve All Sources from PubChem

Description

This function retrieves a list of all current depositors of substances or assays from PubChem.

Usage

get_all_sources(domain = "substance")

Arguments

domain

A character string specifying the domain for which sources are to be retrieved. Possible values are: - ''substance'' (default) - ''assay''

Details

The PubChem PUG REST API provides a way to retrieve all current depositors (sources) for substances or assays. For more detailed information, please refer to the PubChem Data Sources documentation.

Value

A character vector containing the names of all sources for the specified domain.

Examples

get_all_sources(
  domain = 'substance'
)

---

Retrieve Assays from PubChem

Description

This function sends a request to PubChem to retrieve assay data based on the specified parameters.

Usage

get_assays(identifier, namespace = "aid", operation = NULL, options = NULL)

Arguments

identifier	A vector of positive integers (e.g., cid, sid, aid) or identifier strings (source, inchikey, formula). In some cases, only a single identifier string (e.g., name, smiles, xref; inchi, sdf by POST only) can be provided. Multiple elements can be included as a vector. See Notes for details.
namespace	A character string specifying the namespace of the identifier. Possible values include: - aid: PubChem Assay Identifier (default) - listkey: A list key obtained from a previous query - type/<assay type>: Specify the assay type - sourceall/<source name>: Specify the source name - target/<assay target>: Specify the assay target - activity/<activity column name>: Specify the activity column name For more details, see the Input section of the PUG REST API.
operation	A character string specifying the operation to perform. Possible values include: - record: Retrieve the full assay record - concise: Retrieve a concise summary of the assay - aids: Retrieve related Assay IDs - sids: Retrieve related Substance IDs - cids: Retrieve related Compound IDs - description: Retrieve assay descriptions (default) - targets/<target type>: Retrieve targets of the assay - summary: Retrieve a summary of the assay - classification: Retrieve assay classification If NULL (default), the operation defaults to description. For a full list of operations, see the Operations section of the PUG REST API.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstanceList' containing the information retrieved from the PubChem database.

Note

To extract information about a specific assay from the returned list, use the instance function.

Each assay may include information on several properties. Specific information from the assay can be extracted using the retrieve function. See examples.

See Also

retrieve, instance

Examples

# Retrieve a list of assays from the PubChem database
assays <- get_assays(
  identifier = c(1234, 7815),
  namespace = 'aid'
)

# Return assay information for assay ID '1234'
assay1234 <- instance(assays, "1234")
print(assay1234)

# Retrieve specific elements from the assay output
retrieve(assay1234, "aid")

---

Retrieve Compound IDs (CIDs) from PubChem

Description

This function sends a request to PubChem to retrieve Compound IDs (CIDs) for given identifier(s).

Usage

get_cids(
  identifier,
  namespace = "name",
  domain = "compound",
  searchtype = NULL,
  options = NULL
)

Arguments

identifier	A vector of identifiers, either numeric or character. The type of identifier depends on the namespace and domain parameters. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values depend on the domain parameter and include: - For domain = 'compound': cid, name, smiles, inchi, sdf, inchikey, formula, etc. - For domain = 'substance':sid, sourceid/<source id>, sourceall/<source name>, name, etc. - For domain = 'assay': aid, listkey, type/<assay type>, sourceall/<source name>, etc. For more details, see the Input section of the PUG REST API.
domain	A character string specifying the domain of the query. Possible values are: - compound (default) - substance - assay - Other domains as specified in the API documentation.
searchtype	An optional character string specifying the search type. Possible values depend on the namespace and domain. Examples include: - substructure, superstructure, similarity, identity for structure searches. - fastidentity, fastsimilarity_2d, fastsimilarity_3d, etc. for fast searches. If NULL (default), no search type is specified.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstance_CIDs', which is a list containing information retrieved from the PubChem database. Compound IDs can be extracted from the returned object using the CIDs function.

Note

To extract compoud IDs from returned object, one may use CIDs function. See examples.

See Also

CIDs, get_pug_rest

Examples

compound <- get_cids(
  identifier = "aspirin",
  namespace = "name"
)

compound

# Extract compound IDs.
CIDs(compound)

---

Retrieve Compounds from PubChem

Description

This function sends a request to the PubChem database to retrieve compound data based on specified parameters.

Usage

get_compounds(
  identifier,
  namespace = "cid",
  operation = NULL,
  searchtype = NULL,
  options = NULL
)

Arguments

identifier	A vector of positive integers (e.g., cid, sid, aid) or identifier strings (source, inchikey, formula). In some cases, a single identifier string (e.g., name, smiles, xref; inchi, sdf by POST only) is sufficient. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values include: - cid: PubChem Compound Identifier (default) - name: Chemical name - smiles: SMILES string - inchi: InChI string - inchikey: InChIKey - formula: Molecular formula For more details, see the Input section of the PUG REST API.
operation	A character string specifying the operation to perform. Possible values include: - synonyms: Retrieve synonyms for the compounds. - description: Retrieve compound descriptions. - sids: Retrieve Substance IDs related to the compounds. - aids: Retrieve Assay IDs related to the compounds. - classification: Retrieve compound classification. - cids: Retrieve Compound IDs (used when the input is not CID). If NULL (default), the basic compound record is retrieved. For a full list of operations, see the Operations section of the PUG REST API.
searchtype	An optional character string specifying the search type. Possible values include: - similarity - substructure - superstructure - identity If NULL (default), no search type is specified. For more details, see the Input section of the PUG REST API.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstanceList' and 'PC_Compounds' containing compound information from the PubChem database.

See Also

retrieve, instance

Examples

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

print(compound)

# Return results for selected compound.
instance(compound, "aspirin")
instance(compound, "rstudio")
# instance(compound, "unknown"). # returns error.

# Extract compound properties for the compound "aspirin".
# Use the 'retrieve()' function to extract specific slots from the compound list.
retrieve(instance(compound, "aspirin"), "props")

---

Retrieve Compound Properties from PubChem

Description

This function sends a request to PubChem to retrieve compound properties based on the specified parameters.

Usage

get_properties(
  properties = NULL,
  identifier,
  namespace = "cid",
  searchtype = NULL,
  options = NULL,
  propertyMatch = list(.ignore.case = FALSE, type = "contain")
)

property_map(
  x,
  type = c("match", "contain", "start", "end", "all"),
  .ignore.case = TRUE,
  ...
)

Arguments

properties	A character vector specifying the properties to retrieve. If NULL (default), all available properties are retrieved. Properties can be specified by exact names, partial matches, or patterns, controlled by the propertyMatch argument. For a full list of properties, see the Property Table.
identifier	A vector of compound identifiers, either numeric or character. The type of identifier depends on the namespace parameter. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values include: - cid: PubChem Compound Identifier (default) - name: Chemical name - smiles: SMILES string - inchi: InChI string - inchikey: InChIKey - formula: Molecular formula - Other namespaces as specified in the API documentation.
searchtype	An optional character string specifying the search type. Possible values include: - similarity - substructure - superstructure - identity - Other search types as specified in the API documentation. If NULL (default), no search type is specified. For more details, see the API documentation.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.
propertyMatch	A list of arguments to control how properties are matched. The list can include: - type: The type of match. Possible values are exact, contain, match. Default is contain. - .ignore.case: Logical value indicating if the match should ignore case. Default is FALSE. - x: The properties to match (set internally; do not set manually). Default is list(.ignore.case = FALSE, type = "contain").
x	A character vector of compound properties. The property_map function will search for each property provided here within the available properties. The search can be customized using the type argument. This argument is ignored if type = "all".
type	Defines how to search within the available properties. The default is "match". See Notes for details.
.ignore.case	A logical value. If TRUE, the pattern match ignores case letters. This argument is ignored if type = "all". The default is TRUE.
...	Other arguments. Currently, these have no effect on the function's return.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class "PubChemInstanceList" containing all the properties of the requested compounds.

Note

Property Map:

property_map() is not used to request properties directly from the PubChem database. This function is intended to list the available compound properties that can be requested from PubChem. It has flexible options to search properties from the available property list of the PubChem database. The output of property_map is used as the property input in the get_properties function. This function may be practically used to request specific properties across a range of compounds. See examples for usage.

Examples

# Isomeric SMILES of the compounds
props <- get_properties(
  properties = c("MolecularWeight", "MolecularFormula", "InChI"),
  identifier = c("aspirin", "ibuprofen", "caffeine"),
  namespace = "name"
)

# Properties for a selected compound
instance(props, "aspirin")
retrieve(props, .which = "aspirin", .slot = NULL)
retrieve(instance(props, "aspirin"), .slot = NULL)

# Combine properties of all compounds into a single data frame (or list)
retrieve(props, .combine.all = TRUE)

# Return selected properties
retrieve(props, .combine.all = TRUE,
  .slot = c("MolecularWeight", "MolecularFormula"))

# Return properties for the compounds in a range of CIDs
props <- get_properties(
  properties = c("mass", "molecular"),
  identifier = 2244:2255,
  namespace = "cid",
  propertyMatch = list(
    type = "contain"
  )
)

retrieve(props, .combine.all = TRUE, .to.data.frame = TRUE)

# Return all available properties of the requested compounds
props <- get_properties(
  properties = NULL,
  identifier = 2244:2245,
  namespace = "cid",
  propertyMatch = list(
    type = "all"
  )
)

retrieve(props, .combine.all = TRUE)



#### EXAMPLES FOR property_map() ####
# List all available properties:
property_map(type = "all")

# Exact match:
property_map("InChI", type = "match")
property_map("InChi", type = "match",
  .ignore.case = TRUE) # Returns no match. Ignores '.ignore.case'

# Match at the start/end:
property_map("molecular", type = "start", .ignore.case = TRUE)
property_map("mass", type = "end", .ignore.case = TRUE)

# Partial match with multiple search patterns:
property_map(c("molecular", "mass", "inchi"),
  type = "contain", .ignore.case = TRUE)

---

Retrieve Data from PubChem PUG REST API

Description

This function sends a request to the PubChem PUG REST API to retrieve various types of data for a given identifier. It supports fetching data in different formats and allows saving the output.

Usage

get_pug_rest(
  identifier = NULL,
  namespace = "cid",
  domain = "compound",
  operation = NULL,
  output = "JSON",
  searchtype = NULL,
  property = NULL,
  options = NULL,
  save = FALSE,
  dpi = 300,
  path = NULL,
  file_name = NULL,
  ...
)

Arguments

identifier	A vector of identifiers for the query, either numeric or character. The type of identifier depends on the namespace parameter. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace for the request. Possible values include: - cid: PubChem Compound Identifier (default) - name: Chemical name - smiles: SMILES string - inchi: InChI string - inchikey: InChIKey - formula: Molecular formula - sid: Substance ID For more details, see the PUG REST API documentation.
domain	A character string specifying the domain for the request. Possible values include: - compound (default) - substance - assay For more details, see the PUG REST API documentation.
operation	An optional character string specifying the operation for the request. Possible values depend on the domain and namespace. Examples include: - property - synonyms - classification - conformers - cids, sids, aids (to get related compound, substance, or assay IDs) If NULL (default), the default operation for the specified domain and namespace is used. For a full list of operations, see the PUG REST API documentation.
output	A character string specifying the output format. Possible values are: - JSON (default) - JSONP - XML - CSV - SDF - TXT - PNG For more details, see the PUG REST API documentation.
searchtype	An optional character string specifying the search type. Possible values include: - similarity - substructure - superstructure If NULL (default), no search type is specified. For more details, see the PUG REST API documentation.
property	An optional character string specifying the property or properties to retrieve. This is typically used when operation is property. Examples include: - MolecularWeight - MolecularFormula - IUPACName - InChI - InChIKey If NULL (default), all available properties are returned. For a full list of properties, see the Compound Property Tables.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.
save	A logical value indicating whether to save the output as a file or image. Default is FALSE. If TRUE, the output will be saved to the path specified by path.
dpi	An integer specifying the DPI for image output when output is PNG. Default is 300.
path	A character string specifying the directory path where the output file will be saved if save is TRUE. If NULL (default), a temporary directory will be used.
file_name	A character string specifying the name of the file (without file extension) to save. If NULL (default), the file name is set as "files_downloaded".
...	Additional arguments passed to the underlying HTTP request functions.

Details

For more information on the possible values for parameters such as namespace, domain, operation, output, searchtype, and property, please refer to the PUG REST API documentation.

Value

An object of class ''PugRestInstance'' containing:

'success'

Logical value indicating if the request was successful.

'error'

If 'success' is 'FALSE', a list containing error messages.

'result'

The content retrieved from the API; format depends on 'output'.

'request_args'

A list of the arguments used in the request.

'fileDetails'

If 'save' is 'TRUE', details about the saved file.

Examples

result <- get_pug_rest(identifier = "2244", namespace = "cid", domain = "compound", output = "JSON")
pubChemData(result)

---

Retrieve PUG View Data from PubChem

Description

This function sends a request to the PubChem PUG View API to retrieve various types of data for a given identifier. It supports fetching annotations, QR codes, and more, with options for different output formats including JSON and SVG.

Usage

get_pug_view(
  annotation = NULL,
  identifier = NULL,
  domain = "compound",
  output = "JSON",
  heading = NULL,
  headingType = NULL,
  page = NULL,
  qrSize = "short",
  save = FALSE
)

Arguments

annotation	A character string specifying the type of annotation to retrieve. Valid values are: annotations (default): Retrieve annotations across all of PubChem’s primary databases. categories: List all PubChem depositors and their SIDs for a given compound, including categorization. literature: Retrieve URLs into PubMed for literature associated with a compound, organized by subheading. image: Display biologic images associated with compounds. qr: Generate QR codes that link to the LCSS page for a compound. linkout: Retrieve all the NCBI LinkOut records present for a substance, compound, or assay. structure: Retrieve 3D protein structures associated with a compound.
identifier	A single identifier for the query, either numeric or character. **Note:** Only one identifier is allowed per request for certain annotations. For some annotations like annotations with a heading, the identifier can be NULL.
domain	A character string specifying the domain for the request. Possible values include: compound (default) substance - Other domains as specified in the API documentation.
output	A character string specifying the output format. Possible values include: JSON (default) XML CSV TXT PNG SVG
heading	An optional character string specifying a heading to filter the data. Used with annotations when identifier is NULL.
headingType	An optional character string specifying a heading type to filter the data. Possible values include Compound, Substance, etc.
page	An optional integer specifying a page number for pagination.
qrSize	A character string specifying the size of the QR code. Possible values are short (default) and long. Used when annotation is qr.
save	A logical value indicating whether to save the output to a file. Default is FALSE.

Details

The PubChem PUG View API allows users to retrieve detailed information about compounds, substances, and assays. This function constructs the appropriate API call based on the provided parameters. For more detailed information, please refer to the PubChem PUG View API documentation.

Value

Depending on the output format, this function returns different types of content: JSON or JSONP format returns parsed JSON content. SVG format returns an image object. For QR codes, it returns an image object or saves a PNG file.

Examples

result <- get_pug_view(identifier = "2244", annotation = "linkout", domain = "compound")
retrieve(result, .slot = "ObjUrl", .to.data.frame = FALSE)

---

Retrieve/Save SDF Data from PubChem

Description

This function sends a request to PubChem to retrieve data in SDF format based on the specified parameters. It then saves the retrieved data as an SDF file in the current working directory (or into the system-specific temporary folder).

Usage

get_sdf(
  identifier,
  namespace = "cid",
  domain = "compound",
  operation = NULL,
  searchtype = NULL,
  path = NULL,
  file_name = NULL,
  options = NULL
)

Arguments

identifier	A vector of compound identifiers, either numeric or character. The type of identifier depends on the namespace parameter. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values include: - cid: PubChem Compound Identifier (default) - name: Chemical name - smiles: SMILES string - inchi: InChI string - inchikey: InChIKey - formula: Molecular formula - Other namespaces as specified in the API documentation. For more details, see the Input section of the PUG REST API.
domain	A character string specifying the domain of the query. Possible values include: - compound (default) - Other domains as specified in the API documentation.
operation	A character string specifying the operation to perform. For SDF retrieval, the operation is typically NULL or record. If NULL (default), the basic compound record is retrieved. For more details, see the Operations section of the PUG REST API.
searchtype	An optional character string specifying the search type. Possible values include: - substructure - superstructure - similarity - identity - Other search types as specified in the API documentation. If NULL (default), no search type is specified. For more details, see the Input section of the PUG REST API.
path	A character string specifying the directory path where the SDF file will be saved. If NULL (default), the file is saved in a temporary directory.
file_name	A character string specifying the name of the SDF file (without file extension). If NULL (default), a file name is generated based on the identifier and timestamp.
options	A list of additional options for the request. Available options depend on the specific request and the API. If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

The PubChem PUG REST API allows users to retrieve compound data in various formats, including SDF. This function constructs the appropriate API call and saves the SDF data to a file. For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

The function saves the retrieved data as an SDF file in the current working directory and prints a message indicating the file's location.

Examples

get_sdf(
  identifier = "aspirin",
  namespace = "name",
  path = NULL
)

---

Retrieve Substance IDs (SIDs) from PubChem

Description

This function sends a request to PubChem to retrieve Substance IDs (SIDs) for a given identifier.

Usage

get_sids(
  identifier,
  namespace = "cid",
  domain = "compound",
  searchtype = NULL,
  options = NULL
)

Arguments

identifier	A vector of identifiers, either numeric or character. The type of identifier depends on the namespace and domain parameters. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values depend on the domain parameter and include: - For domain = 'compound': cid, name, smiles, inchi, sdf, inchikey, formula, etc. - For domain = 'substance': sid, sourceid/<source id>, sourceall/<source name>, name, etc. - For domain = 'assay': aid, listkey, type/<assay type>, sourceall/<source name>, etc. For more details, see the Input section of the PUG REST API.
domain	A character string specifying the domain of the query. Possible values are: - compound (default) - substance - assay - Other domains as specified in the API documentation.
searchtype	An optional character string specifying the search type. Possible values depend on the namespace and domain. Examples include: - substructure, superstructure, similarity, identity for structure searches. - fastidentity, fastsimilarity_2d, fastsimilarity_3d, etc. for fast searches. If NULL (default), no search type is specified. For more details, see the Input section of the PUG REST API.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

#' For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstance_SIDs', which is a list containing information retrieved from the PubChem database. Substance IDs can be extracted from the returned object using the SIDs function.

Examples

result <- get_sids(
  identifier = c("aspirin", "ibuprofen"),
  namespace = "name"
)

# Extract substance IDs of all compounds
SIDs(result)

---

Retrieve Substances from PubChem

Description

This function sends a request to PubChem to retrieve substance data based on the specified parameters.

Usage

get_substances(identifier, namespace = "sid", operation = NULL, options = NULL)

Arguments

identifier	A vector of substance identifiers, either numeric or character. The type of identifier depends on the namespace parameter. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values include: - sid: PubChem Substance Identifier (default) - sourceid/<source id>: Source-specific substance ID - sourceall/<source name>: Source name - name: Substance name - <xref>: Cross-reference - listkey: A list key obtained from a previous query For more details, see the Input section of the PUG REST API.
operation	A character string specifying the operation to perform. Possible values include: - record: Retrieve the full substance record (default) - synonyms: Retrieve synonyms for the substances - sids: Retrieve Substance IDs - cids: Retrieve Compound IDs related to the substances - aids: Retrieve Assay IDs related to the substances - assaysummary: Retrieve assay summary - classification: Retrieve substance classification - <xrefs>: Retrieve cross-references - description: Retrieve substance descriptions If NULL (default), the operation defaults to record. For a full list of operations, see the Operations section of the PUG REST API.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstanceList' containing all the substance information of requested compounds.

Examples

subs <- get_substances(
  identifier = c("aspirin", "ibuprofen"),
  namespace = "name"
)

instance(subs, "aspirin")
retrieve(instance(subs, "aspirin"), "source")

---

Retrieve Synonyms from PubChem

Description

This function sends a request to PubChem to retrieve synonyms for a given identifier. It returns a list of synonyms corresponding to the provided identifier.

Usage

get_synonyms(
  identifier,
  namespace = "cid",
  domain = "compound",
  searchtype = NULL,
  options = NULL
)

Arguments

identifier	A vector of identifiers, either numeric or character. The type of identifier depends on the namespace and domain parameters. **Note**: identifier must be provided; it cannot be NULL.
namespace	A character string specifying the namespace of the identifier. Possible values depend on the domain parameter and include: - For domain = 'compound': cid, name, smiles, inchi, sdf, inchikey, formula, etc. - For domain = 'substance': sid, sourceid/<source id>, sourceall/<source name>, name, etc. - For domain = 'assay': aid, listkey, type/<assay type>, sourceall/<source name>, etc. For more details, see the Input section of the PUG REST API.
domain	A character string specifying the domain of the query. Possible values are: - compound (default) - substance - assay - Other domains as specified in the API documentation.
searchtype	An optional character string specifying the search type. Possible values depend on the namespace and domain. Examples include: - substructure, superstructure, similarity, identity for structure searches. - fastidentity, fastsimilarity_2d, fastsimilarity_3d, etc. for fast searches. If NULL (default), no search type is specified. For more details, see the Input section of the PUG REST API.
options	A list of additional options for the request. Available options depend on the specific request and the API. Examples include: - For similarity searches: list(Threshold = 95) - For substructure searches: list(MaxRecords = 100) If NULL (default), no additional options are included. For more details, see the Structure Search Operations section of the PUG REST API.

Details

The PubChem PUG REST API allows for retrieving synonyms related to various domains. The table below summarizes valid combinations for retrieving synonyms: For more detailed information, please refer to the PubChem PUG REST API documentation.

Value

An object of class 'PubChemInstance_Synonyms', which is a list containing information retrieved from the PubChem database. Synonyms data can be extracted from the returned object using the synonyms function.

Examples

syns <- get_synonyms(
  identifier = "aspirin",
  namespace = "name"
)

syns

synonyms(syns)

---

Retrieve Information for Requested Instances

Description

This function extracts the results of a PubChem instance from an object. It is designed to retrieve information about a compound from a comprehensive list where multiple elements (such as assay, compound, etc.) are requested.

Usage

instance(object, ...)

## S3 method for class 'PubChemInstanceList'
instance(object, .which = NULL, ...)

Arguments

object	An object of class 'PubChemInstanceList' returned from a PubChem request.
...	Additional arguments passed to other methods. Currently, these have no effect.
.which	A string specifying which instance's results to return. If NULL, the results of the first instance in the object are returned. The default value is NULL.

Examples

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

instance(compounds)  # Returns the results for "aspirin"
instance(compounds, "ibuprofen")

---

Retrieve Raw Data from PUG REST Object

Description

A short description...

Usage

pubChemData(object, ...)

## S3 method for class 'PugRestInstance'
pubChemData(object, ...)

Arguments

object	an object of class 'PugRestInstance' returned from get_pug_rest function.
...	additional arguments. Currently has no effect on results.

Value

a vector, list, or data.frame containing the raw data retrieved from Pub Chem database through PUG REST API.

See Also

get_pug_rest

Examples

result <- get_pug_rest(identifier = "2244", namespace = "cid", domain = "compound", output = "JSON")
pubChemData(result)

---

PubChemInstanceList and PubChemInstance Classes

Description

The PubChemInstanceList object is a superclass returned by a request for compound(s) from the PubChem Database, such as the output from get_compounds, get_assays, etc.

The PubChemInstance object is another superclass for a PubChem instance, such as an assay, compound, substance, etc. These instances are nested within the results slot of a PubChemInstanceList object. Similar to PubChemInstanceList, the PubChemInstance also contains the same slots as described below. For more details, see instance.

Slots

results:

A list containing elements of each of the requested compounds, assays, substances, etc.

request_args:

A list containing the input arguments of a PubChem request.

success:

A logical value indicating whether the request was successfully completed (TRUE) or not (FALSE).

error:

A list detailing any errors encountered during the request, if applicable.

Note

There is no constructor function for the PubChemInstanceList or PubChemInstance classes. These objects are constructed within related functions and returned as the output of PubChem requests.

There are several subclasses defined under the PubChemInstanceList and PubChemInstance superclasses. The PubChem API returns request results in a list; however, each request may have a different list structure and/or items within the returned list. Therefore, we have defined subclasses to make generic functions compatible with any PubChem request, such as assays, instances, substances, etc. These subclasses may include PC_Compounds, PC_Substance, PC_Properties, PubChemInstance_AIDs, PubChemInstance_SIDs, PubChemInstance_CIDs, PubChemInstance_Synonyms, and PubChemInstance_Substances.

Most of the defined subclasses have similar slots as described above. However, some classes may have additional slots not described here. Please refer to the contents of the returned object for more details.

---

Classes for Pug View Request

Description

The Pug View API of PubChem database returns more detailed information about a PubChem request, such as assays, compounds, substances, etc. A super-class PugViewInstance is defined, which is returned from get_pug_view function. This class has slots detailed below.

Slots

results:

A list containing elements of each of the requested compounds, assays, substances, etc.

request_args:

A list containing the input arguments of a PubChem request.

success:

A logical value indicating whether the request was successfully completed (TRUE) or not (FALSE).

error:

A list detailing any errors encountered during the request, if applicable.

Note

Pug View API returns many section about the requested instance, which includes detailed information from PubChem database. There may be many nested sections, where each contains details about different features of the instance requested. These sections can be listed via sectionList function.

Other classes, called PugViewSectionList and PugViewSection, are defined to control the outputs of available sections and sub-sections returned from get_pug_view. See related functions for details.

See Also

section, sectionList

---

Retrieve Function Inputs

Description

This function retrieves the input arguments from a specified PubChem database request object.

Usage

request_args(object, .which = NULL, ...)

Arguments

object	An object returned from related request functions of the PubChem database.
.which	A string specifying which argument's content to retrieve from object. If NULL, all function inputs will be returned.
...	Additional arguments. These have no effect on the returned outputs and are included for compatibility with S3 methods in the PubChemR package.

Value

A list or string vector containing the options used in the function call.

Examples

request <- get_cids("aspirin", namespace = "name")

request_args(request, "identifier")
request_args(request)

---

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)

---

Extract Sections from Pug View Request

Description

section returns section details from a Pug View request.

Usage

section(object, ...)

## S3 method for class 'PugViewInstance'
section(object, .id = "S1", .verbose = FALSE, ...)

## S3 method for class 'PugViewSectionList'
section(object, .id = "S1", .verbose = FALSE, ...)

## S3 method for class 'PugViewSection'
section(object, .id = "S1", .verbose = FALSE, ...)

Arguments

object	an object returned from get_pug_view.
...	other arguments. Currently has no effect on the outputs. Can be ignored.
.id	A character value that corresponds to the ID of a specific section. Detailed information about the section with the given section ID will be returned. If NULL, the first section (i.e., "S1") is returned. If there is no section under object, it returns NULL with a warning. See Note/Details for more information.
.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.

Note

Sections in a Pug View Request

A Pug View Request returns a detailed list from the PubChem database. This list may include data under many nested sections, each corresponding to a different property structured within further nested sections. The complicated structure of the returned object makes it impossible to print all information to the R console at once. Therefore, it is recommended to print sections selectively. Furthermore, one may navigate through the nested sections using the section function. See Examples.

Use the sectionList function to list available sections (or subsections of a section) of a Pug View request and related section IDs.

Use of '.verbose' to Print Section Details

It is possible to print section details to the R console. If .verbose = TRUE, the resulting object is returned invisibly and a summary of section details is printed to the R console. This might be useful to navigate through nested sections and sequentially print multiple sections to the R console. For example, consider following command:

> section(section(request, "S1", .verbose = TRUE), "S3", .verbose = TRUE)

This command will print section "S1" and the subsection "S3" located under "S1" to the R console. One may navigate through sections under other sections, similar to exploring dreams within dreams as depicted in the exceptional movie Inception. (SPOILER WARNING!!) However, be careful not to get lost or stuck in the dreams!! Also, note that this strategy works only if .verbose = TRUE for all sections and/or subsections.

See Also

sectionList

Examples

# Pug View request for the compound "aspirin (CID = 2244)".
pview <- get_pug_view(identifier = "2244", annotation = "data", domain = "compound")

section(pview, "S1")
section(pview, "S1", .verbose = TRUE)

# List all available sections
sectionList(pview)

# Subsections under the section "S1"
sectionList(section(pview, "S1"))

# Print multiple sections
# section(section(pview, "S1", .verbose = TRUE), "S3", .verbose = TRUE)

---

List Available Section/Subsections

Description

This function may be used to list available sections (or subsections) of a PubChem request returned from get_pug_view. It is useful when one wants to extract a specific section (or subsection) from PubChem request. It supports patteern-specific searches within sections. See Detail/Note below for more information.

Usage

sectionList(object, ...)

## S3 method for class 'PugViewInstance'
sectionList(object, ...)

## S3 method for class 'PugViewSectionList'
sectionList(
  object,
  .pattern = NULL,
  .match_type = c("contain", "match", "start", "end"),
  ...
)

## S3 method for class 'PugViewSection'
sectionList(
  object,
  .pattern = NULL,
  .match_type = c("contain", "match", "start", "end"),
  ...
)

Arguments

object	an object of PubChem request, generally returned from get_pug_view.
...	other arguments. Currently has no effect on the outputs. Can be ignored.
.pattern	a character vector. Each text pattern given here will be searched within Pug View sections by using the pattern matching strategy defined with .match_type. If not specified or NULL, all available sections will be returned.
.match_type	a string. How should search patterns (i.e., .pattern) matched with section names? Available options are "contain", "match", "start", and "end" which can be used for partial and/or exact pattern matching. Default is "contain". See Details below for more information.

Details

Pattern matching is used to filter sections that match user-defined patterns. It is useful when there are more sections than allowed to print R console. In such situations, it may be reasonable to print a subset of all section list to R console that meets search criteria. There are several pattern matching methods as described below

• Partial Matching ("contain", "start", "end"): Returns the section names that contains or starts/ends by given text patterns.

• Exact Matching ("match"): Returns the section names that exactly matches given text patterns.

See Also

section

Examples

pview <- get_pug_view(identifier = "2244", annotation = "data", domain = "compound")

# List all section names
sectionList(pview)

# Pattern-matched section names
sectionList(pview, .pattern = c("safety", "chemical"), .match_type = "contain")
sectionList(pview, .pattern = "safety", .match_type = "match")
sectionList(pview, .pattern = "properties", .match_type = "end")

# Use section IDs to extract section data from Pug View request
section(pview, "S12") # Safety and Hazards

---

Getter function for 'Synonyms'

Description

Extracts synonym data from a PubChem request using the function get_synonyms.

Usage

synonyms(object, ...)

## S3 method for class 'PubChemInstance_Synonyms'
synonyms(object, .to.data.frame = TRUE, ...)

Arguments

object	An object of class 'PubChemInstance_Synonyms'.
...	Additional arguments passed to other methods. Currently, these have no effect.
.to.data.frame	a logical. If TRUE, returned object will be forced to be converted into a data.frame (or tibble). If failed to convert into a data.frame, a list will be returned with a warning. Be careful for complicated lists (i.e., many elements nested within each other) since it may be time consuming to convert such lists into a data frame.

Value

A data.frame (or list) object containing the synonym data.

Examples

syns <- get_synonyms(identifier = c("aspirin", "caffeine"), namespace = "name")
synonyms(syns)

---