ctrdata (version 1.6.0)

ctrLoadQueryIntoDb: Retrieve or update information on clinical trials from register and store in database

Description

This is the main function of package ctrdata for accessing registers. Note that re-rerunning this function adds or updates trial records in a database, even if from different queries or different registers. Updating means that the previously stored record is overwritten; see annotation.text for persisting user comments added to a record.

Usage

ctrLoadQueryIntoDb(
  queryterm = "",
  register = "",
  querytoupdate = 0L,
  forcetoupdate = FALSE,
  euctrresults = FALSE,
  euctrresultshistory = FALSE,
  euctrresultspdfpath = NULL,
  annotation.text = "",
  annotation.mode = "append",
  parallelretrievals = 10L,
  only.count = FALSE,
  con = NULL,
  verbose = FALSE
)

Arguments

queryterm

Either a string with the full URL of a search in a register, or the data frame returned by the ctrGetQueryUrl or the dbQueryHistory functions, or, together with parameter register, a string with query elements of a search URL. The queryterm is recorded in the collection for later use to update records.

register

String with abbreviation of register to query, either "EUCTR", "CTGOV" or "ISRCTN". Not needed if queryterm provide the information which register to query (see queryterm).

querytoupdate

Either the word "last" or the number of the query (based on dbQueryHistory) that should be run to retrieve any trial records that are new or have been updated since this query was run the last time. This parameter takes precedence over queryterm. For EUCTR, updates are available only for the last seven days; the query is run again if more time has passed since it was run last.

forcetoupdate

If TRUE, run again the query given in querytoupdate, irrespective of when it was run last (default is FALSE).

euctrresults

If TRUE, also download available results when retrieving and loading trials from EUCTR. This slows down this function. (For CTGOV, all available results are always retrieved and loaded.)

euctrresultshistory

If TRUE, also download available history of results publication in EUCTR. This is quite time-consuming (default is FALSE).

euctrresultspdfpath

If a valid directory is specified, save PDF files of result publications from EUCTR into this directory (default is NULL).

annotation.text

Text to be including in the records retrieved with the current query, in the field "annotation".

annotation.mode

One of "append" (default), "prepend" or "replace" for new annotation.text with respect to any existing annotation for the records retrieved with the current query.

parallelretrievals

Number of parallel downloads of information from the register, defaults to 10.

only.count

Set to TRUE to return only the number of trial records found in the register for the query. Does not load trial information into the database. Default is FALSE.

con

A src connection object, as obtained with nodbi::src_mongo() or nodbi::src_sqlite()

verbose

Printing additional information if set to TRUE; default is FALSE.

Value

A list with elements "n" (the number of trials that were newly imported or updated with this function call), "ids" (a vector of the _id[s] of these trials) and the "queryterm" used, with several attributes set (database connection details and a data frame of the query history in this database).

Examples

# NOT RUN {
db <- nodbi::src_sqlite(
  collection = "test"
)
# Retrieve protocol-related information on a
# single trial identified by EudraCT number
ctrLoadQueryIntoDb(
  queryterm = "2013-001291-38", con = db
)
# Retrieve protocol-related information on
# ongoing interventional cancer trials in children
ctrLoadQueryIntoDb(
  queryterm = "cancer&recr=Open&type=Intr&age=0",
  register = "CTGOV",
  con = db
)
# }
# NOT RUN {
# }