improve documentation

Author: rfhb

R/ctrGenerateQueries.R

@@ -5,6 +5,14 @@
 #' Extracts query parameters and register name from parameter `url` or
 #' from the clipboard, into which the URL of a register search was copied.
 #'
+#' To obtain the search query from CTIS, consider installing the
+#' \href{https://www.tampermonkey.net/}{Tampermonkey browser extension},
+#' click on the extension icon, "Create a new script", "Utility" and then
+#' "Import from this URL":
+#' `https://raw.githubusercontent.com/rfhb/ctrdata/master/tools/ctrdataURLcopier.js`
+#' This will copy query URLs from all registers into the clipboard; see
+#' \link{ctrOpenSearchPagesInBrowser} for additional uses.
+#'
 #' @param url URL such as from the browser address bar.
 #' If not specified, clipboard contents will be checked for
 #' a suitable URL.

R/ctrGetQueryUrl.R

@@ -11,17 +11,18 @@
 #' A previous query can be re-run, which replaces or adds trial
 #' records while keeping any user annotations of trial records.
 #'
-#' @param queryterm Either a string with the full URL of a search
-#' query in a register, or the data frame returned by
+#' @param queryterm Either a single string with the full URL of a search
+#' query in a register, e.g. one of the strings returned by
+#' \link{ctrGenerateQueries}, or a single-row data frame returned by
 #' \link{ctrGetQueryUrl} or \link{dbQueryHistory},
-#' or an `_id` in the format of one of the trial registers,
+#' or an `_id` in the format of one of the trial registers (e.g., "NCT..."),
 #' or, together with \code{register}, a string with query
 #' elements of a search URL. The query details are recorded in the
 #' \code{collection} for later use, e.g. to update records.
 #' For "CTIS", \code{queryterm} can be an empty string to obtain
 #' all trial records. For automatically copying the user's
-#' query of a register in a web browser to the clipboard, see
-#' \ifelse{latex}{\out{\href{https://rfhb.github.io/ctrdata/#id_2-script-to-automatically-copy-users-query-from-web-browser}{here}}}{\href{https://rfhb.github.io/ctrdata/#id_2-script-to-automatically-copy-users-query-from-web-browser}{here}}
+#' query of a register in a web browser to the clipboard, see the
+#' information on a browser extension script in \link{ctrGetQueryUrl}.
 #'
 #' @param register String with abbreviation of register to query,
 #' either "EUCTR", "CTGOV2", "ISRCTN" or "CTIS". Not needed
@@ -138,24 +139,25 @@
 #' @examples
 #' \dontrun{
 #'
+#' # Count ongoing interventional cancer trials involving children
+#' # Note this query is a classical CTGOV query and is translated
+#' # to a corresponding query for the current CTGOV2 webinterface
+#' ctrLoadQueryIntoDb(
+#'   queryterm = "cond=cancer&recr=Open&type=Intr&age=0",
+#'   register = "CTGOV",
+#'   only.count = TRUE
+#' )
+#'
 #' dbc <- nodbi::src_sqlite(collection = "my_collection")
 #'
 #' # Retrieve protocol- and results-related information
-#' # on two specific trials identified by their EU number
+#' # on two specific trials identified by their EU number,
+#' # including protocol versions from all Member States
 #' ctrLoadQueryIntoDb(
 #'   queryterm = "2005-001267-63+OR+2008-003606-33",
 #'   register = "EUCTR",
 #'   euctrresults = TRUE,
-#'   con = dbc
-#' )
-#'
-#' # Count ongoing interventional cancer trials involving children
-#' # Note this query is a classical CTGOV query and is translated
-#' # to a corresponding query for the current CTGOV2 webinterface
-#' ctrLoadQueryIntoDb(
-#'   queryterm = "cond=cancer&recr=Open&type=Intr&age=0",
-#'   register = "CTGOV",
-#'   only.count = TRUE,
+#'   euctrprotocolsall = TRUE,
 #'   con = dbc
 #' )
 #'

R/ctrLoadQueryIntoDb.R

@@ -2,7 +2,12 @@
 
 #' Open register to show query results or search page
 #'
-#' Open advanced search pages of register(s), or execute search in browser
+#' Open advanced search pages of register(s), or execute search in browser.
+#' For CTIS to accept a search URL and show results, consider installing the
+#' \href{https://www.tampermonkey.net/}{Tampermonkey browser extension},
+#' click on the extension icon, "Create a new script", "Utility" and then
+#' "Import from this URL":
+#' `https://raw.githubusercontent.com/rfhb/ctrdata/master/tools/ctrdataURLcopier.js`
 #'
 #' @param url of search results page to show in the browser. To open the
 #' browser with a previous search, the output of \link{ctrGetQueryUrl}

R/ctrOpenSearchPagesInBrowser.R

@@ -8,10 +8,8 @@
 #' \code{con} is provided or if the trial is not in database \code{con}.
 #' For use in a Shiny app, see output and render functions in source code
 #' \ifelse{latex}{\out{
-#' \href{https://github.com/rfhb/ctrdata/blob/master/R/ctrShowOneTrial.R\#L190}{here}}}{
-#' \href{https://github.com/rfhb/ctrdata/blob/master/R/ctrShowOneTrial.R#L190}{here}}.
-#'
-#'
+#' \href{https://github.com/rfhb/ctrdata/blob/master/R/ctrShowOneTrial.R\#L196}{here}}}{
+#' \href{https://github.com/rfhb/ctrdata/blob/master/R/ctrShowOneTrial.R#L196}{here}}.
 #'
 #' This is the widget for CTIS trial 2022-501142-30-00:
 #'
@@ -22,7 +20,7 @@
 #'   \out{\begin{center}}\figure{ctrdata_ctrShowOneTrial.jpg}\out{\end{center}}
 #' }
 #'
-#' @param identifier A trial identifier string
+#' @param identifier A trial identifier (`_id`) string, see examples
 #'
 #' @inheritParams ctrDb
 #'

R/ctrShowOneTrial.R

@@ -34,7 +34,7 @@
 #' \link{ctrShowOneTrial} (show widget to explore structure, fields and data of a trial),
 #' \link{dbFindFields} (find names of fields of interest in trial records in a collection),
 #' \link{dbGetFieldsIntoDf} (create a data frame with fields of interest and calculated trial concepts from collection),
-#' \link{ctrdata-trial-concepts} (calculate pre-defined trial concepts for every register),
+#' \link{ctrdata-trial-concepts} (calculate pre-defined trial concepts across registers),
 #' \link{dbFindIdsUniqueTrials} (get de-duplicated identifiers of clinical trials' records to subset a data frame).
 #'
 #' @section 4 - Operate on a trial data frame from dbGetFieldsIntoDf:

R/ctrdata-package.R

@@ -2,30 +2,30 @@
 #'
 #' Registers of the four clinical trial registers from which package
 #' \link{ctrdata} can retrieve, aggregate and analyse protocol- and
-#' result-related information as well as documents, last updated 2025-05-31.
+#' result-related information as well as documents, last updated 2025-07-24.
 #'
 #' @section 1 - Overview:
 #'
 #' - **EUCTR**: The EU Clinical Trials Register holds more than 44,300 clinical
 #' trials (at least one investigational medicinal product, IMP; in the European
-#' Union and beyond), including more than 25,100 trials with results, which
+#' Union and beyond), including more than 25,300 trials with results, which
 #' continue to be added (and can be loaded by `ctrdata`).
 #'
 #' - **CTIS**: The EU Clinical Trials Information System, launched in 2023,
-#' holds more than 9,200 publicly accessible clinical trials, including
-#' around 180 with results or a report (only as PDF files).
+#' holds more than 9,600 publicly accessible clinical trials, including
+#' around 230 with results or a report (only as PDF files).
 #' _No results in a structured electronic format are foreseeably available_,
 #' thus `ctrdata` cannot load any CTIS results.
 #' (To automatically get CTIS search query URLs, see
 #' \ifelse{latex}{\out{\href{https://rfhb.github.io/ctrdata/\#id_2-script-to-automatically-copy-users-query-from-web-browser}{here}}}{\href{https://rfhb.github.io/ctrdata/#id_2-script-to-automatically-copy-users-query-from-web-browser}{here}})
 #'
-#' - **CTGOV2**: ClinicalTrials.gov holds about 540,000 interventional and
-#' observational studies, including almost 71,000 interventional studies with
+#' - **CTGOV2**: ClinicalTrials.gov holds about 546,000 interventional and
+#' observational studies, including almost 68,000 interventional studies with
 #' results (can be loaded by `ctrdata`).
 #'
-#' - **ISRCTN**: The ISRCTN Registry holds more than 26,400 interventional and
-#' observational health studies, including almost 14,400 studies with
-#' results (only as references).
+#' - **ISRCTN**: The ISRCTN Registry holds more than 26,600 interventional and
+#' observational health studies, including almost 14,500 studies with
+#' results (as references).
 #' _No results in a structured electronic format are foreseeably available_,
 #' thus `ctrdata` cannot load any ISRCTN results.
 #'

R/ctrdata-registers.R

@@ -21,7 +21,7 @@
 #' The following trial concepts can be used by referencing their name when
 #' calling \link{dbGetFieldsIntoDf} (parameter `calculate`).
 #' Concepts will continue to be refined and added;
-#' last updated 2025-07-18.
+#' last updated 2025-07-24.
 #'
 #' - \link{f.assignmentType} (factor) was the assignment to treatment based on
 #' randomisation or not? ("R" or "NR")
@@ -42,27 +42,28 @@
 #' of study design)
 #'
 #' - \link{f.isUniqueTrial} (logical) is the trial record unique in the data
-#' frame of trial, based on default parameters of \link{dbFindIdsUniqueTrials}?
+#' frame of trial records, based on default parameters of
+#' \link{dbFindIdsUniqueTrials}?
 #'
 #' - \link{f.likelyPlatformTrial} (logical, list of likely related trials, and
 #' list of maybe related trials) is the trial possibly a (research)
 #' platform trial, and what are related trials? (based on trial title,
-#' f.numTestArmsSubstances, number of periods; identifiers of related trials;
+#' `f.numTestArmsSubstances`, number of periods; identifiers of related trials;
 #' similarity of terms in parts of trial titles)
 #'
 #' - \link{f.numSites} (integer) how many sites does the trial have?
 #'
-#' - \link{f.numTestArmsSubstances} (integer) how many arms or groups have
-#' medicines that are investigational? (cannot be calculated for ISRCTN or
-#' for phase 1 trials)
+#' - \link{f.numTestArmsSubstances} (integer) how many arms or groups in the
+#' trial have medicines that are investigational? (cannot be calculated for
+#' ISRCTN or for phase 1 trials)
 #'
 #' - \link{f.primaryEndpointDescription} (list of character) string containing
 #' protocol definition, details and time frames, concatenated with " == "
 #'
 #' - \link{f.primaryEndpointResults} (columns of number, character, integer,
 #' logical) returning the statistical testing p value and method as well as the
-#' number of subjects included in the test and if the record includes results,
-#' each in one new column, for the first primary endpoint only
+#' number of subjects included in the test, each in one new column, for the
+#' first primary endpoint only
 #'
 #' - \link{f.resultsDate} (date) the planned or achieved date of results availability
 #'
@@ -81,11 +82,11 @@
 #' withdrawn)
 #'
 #' - \link{f.trialObjectives} (string) identifies with letters those objectives
-#' that could be identified by text fragments, e.g. "E S PD D", with "E"
+#' that could be identified in text fragments, e.g. "E S PD D", with "E"
 #' (efficacy), "S" (safety), "D" (dose-finding)
 #'
 #' - \link{f.trialPhase} (ordered factor) the phase(s) of medicine development
-#' with which a trial is associated
+#' with which a trial is associated ("phase 1", "phase 1+2" etc.)
 #'
 #' - \link{f.trialPopulation} (columns of factor, string and string) age groups
 #' (e.g., "P" for paediatric participants, "A" for adults, "E" for older than

R/ctrdata-trial-concepts.R

@@ -2,13 +2,12 @@
 
 #' Find names of fields in the database collection
 #'
-#' Given part of the name of a field of interest to the user, this
+#' Given a part of the name of fields that are of interest to the user, this
 #' function returns the full field names used in records that were
-#' previously loaded into a collection
-#' (using \link{ctrLoadQueryIntoDb}). Only names of fields that have
-#' a value in the collection can be returned.
+#' previously loaded into a collection (using \link{ctrLoadQueryIntoDb}).
+#' Only names of fields that have a value in the collection can be returned.
 #' Set \code{sample = FALSE} to force screening all records in the
-#' collection for field names, see below.
+#' collection for field names, which can take long.
 #' See \link{ctrShowOneTrial} to interactively find fields.
 #'
 #' The full names of child fields are returned in dot notation (e.g.,
@@ -57,7 +56,7 @@
 #'
 #' dbFindFields(namepart = "date", con = dbc)[1:5]
 #'
-#' # view all 1880+ fields from all registers:
+#' # view names of all 3838 fields from all registers:
 #'
 #' allFields <- dbFindFields(con = dbc, sample = FALSE)
 #'

R/dbFindFields.R

@@ -13,8 +13,8 @@
 #' (and, for "EUCTR", between records for different Member States).
 #' Such differences are not considered by this function.
 #'
-#' Note that the trial concept ".isUniqueTrial" (which uses this function)
-#' can be calculated at the time of creating a data frame with
+#' Note that the trial concept \link{f.isUniqueTrial} (which uses this
+#' function) can be calculated at the time of creating a data frame with
 #' \link{dbGetFieldsIntoDf}, which often may be the preferred approach.
 #'
 #' @param preferregister A vector of the order of preference for