ctrLoadQueryIntoDb: Load and store register trial information

View source: R/main.R

ctrLoadQueryIntoDbR Documentation

Load and store register trial information

Description

Retrieves or updates information on clinical trials from registers and stores it in a collection in a database. This is the main function of ctrdata-package for accessing registers and loading trial information into a database collection, even if from different queries or different registers. The query details are stored in the database collection and can be accessed using dbQueryHistory. A previous query can be re-run, which replaces or adds trial records. However, user annotations of trial records are kept.

Usage

ctrLoadQueryIntoDb(
  queryterm = NULL,
  register = "",
  querytoupdate = NULL,
  forcetoupdate = FALSE,
  euctrresults = FALSE,
  euctrresultshistory = FALSE,
  euctrresultsfilespath = euctrresultspdfpath,
  euctrresultspdfpath = NULL,
  annotation.text = "",
  annotation.mode = "append",
  parallelretrievals = 4L,
  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).

euctrresultsfilespath

If this is a relative or absolute path to a directory that exists or can be created, save results files into it, e.g., PDF files of result publications that had been submitted to EUCTR (default is NULL).

euctrresultspdfpath

Deprecated, use euctrresultsfilespath

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 4

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 connection object, see section 'Databases' in ctrdata-package

verbose

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

Value

A list with elements 'n' (number of trial records newly imported or updated), ‘success' (a vector of _id’s of successfully loaded records), 'failed' (a vector of identifiers of records that failed to load) and 'queryterm' (the query term used). The returned list has several attributes (including database and collection name, as well as the query history of this database collection) to facilitate documentation.

Examples

## Not run: 

dbc <- nodbi::src_sqlite(collection = "my_collection")

# Retrieve protocol- and results-related information
# on a single trial identified by its EU number
ctrLoadQueryIntoDb(
  queryterm = "2013-001291-38",
  register = "EUCTR",
  euctrresults = TRUE,
  con = dbc
)

# Retrieve all information on about 2,000 ongoing
# interventional cancer trials involving children
# into the same collection as used before
ctrLoadQueryIntoDb(
  queryterm = "cancer&recr=Open&type=Intr&age=0",
  register = "CTGOV",
  con = dbc
)

# Retrieve all information on more than 40 trials
# that are labelled as phase 3 and that mention
# either neuroblastoma or lymphoma from ISRCTN,
# into the same collection as used before
ctrLoadQueryIntoDb(
  queryterm = "https://www.isrctn.com/search?q=neuroblastoma+OR+lymphoma&filters=phase%3APhase+III",
  con = dbc
)


## End(Not run)


ctrdata documentation built on Nov. 21, 2022, 1:06 a.m.