getStudiesSTSTDTC: Extract a list of SEND studies with study start date within a...

View source: R/getStudiesSTSTDTC.R

getStudiesSTSTDTCR Documentation

Extract a list of SEND studies with study start date within a specified interval - or just add actual study start date for each study

Description

Returns a data table with the list of study ids from TS where the value of TSVAL for the TSPARMCD 'STSTDTC' is within a a given date interval.
If the fromDTC andtoDTC are empty (null, na or empty string)

  • all rows for the TSPARMCD 'STSTDTC' are returned.

Usage

getStudiesSTSTDTC(
  dbToken,
  studyList = NULL,
  fromDTC = NULL,
  toDTC = NULL,
  inclUncertain = FALSE,
  noFilterReportUncertain = TRUE
)

Arguments

dbToken

Mandatory.
Token for the open database connection (see initEnvironment).

studyList

Optional.
A data.table with the list of studies to process. If empty, all studies in the data base are processed
The table must include at least a column named 'STUDYID'.

fromDTC

Optional (either or both of fromDTC and toDTC must be filled).
The start of the date interval to extract - must be in ISO8601 date format.

toDTC

Optional (either or both of fromDTC and toDTC must be filled).
The end of the date interval to extract - must be in ISO8601 date format.

inclUncertain

Mandatory, boolean.
Indicates whether study ids with STSTDTC which are are missing or wrong shall be included or not in the output data table.

noFilterReportUncertain

Mandatory, boolean
Only relevant if the fromDTC andtoDTC are empty.
Indicates if the reason should be included if the STSTDTC cannot be confidently decided for an animal.

Details

Extracts the set of study ids from TS where the value of TSVAL for the TSPARMCD 'STSTDTC' falls within a specified start/end date interval in IS8601 format (input parameters fromDTC/toDTC).

Both complete and incomplete input start/end dates can be handled.

  • If only a year is specified - the date set to the first of January that year.

  • If only a year and month is specified - the date set to the first day in that month.

  • If a time part is included in a specified input start/end date, it is ignored.

If both a start and end input date are specified - all the STUDYID values from TS where TSVAL for TSPARMCD 'STSTDTC' is with the interval of the specified start/end date interval are extracted and returned - including the values equal to the start/end dates. are included.

If only a start input date is specified - all the STUDYID values from TS where TSVAL for TSPARMCD 'STSTDTC' is equal to or later than the input date are extracted and returned.

If only an end date is specified - all the STUDYID values from TS where TSVAL for TSPARMCD 'STSTDTC' is equal to or earlier than the are date are extracted and returned.

If a data table with a list of studies is specified in studyList, only the subset of studies included in that set is processed.

If input inclUncertain is TRUE, uncertain studies are included in the output set. These uncertain situations are identified and reported (in column UNCERTAIN_MSG):

  • TS contains now row for TSPARMCD='STSTDTC'

  • TSVAL contains an invalid ISO8601 date format for TSPARMCD='STSTDTC'

The same checks are performed and reported in column NOT_VALID_MSG if fromDTC and toDTC are empty and noFilterReportUncertain=TRUE.

Value

The function return a data.table with columns:

  • STUDYID (character)

  • Additional columns contained in the studyList table (if such an input table is given)

  • STSTDTC (character - ISO8601 format)

  • UNCERTAIN_MSG (character)
    Only included when parameter inclUncertain=TRUE.
    Contains indication of whether STSTDTC is missing of has wrong format.
    Is NA for rows where SDESIGN is valid.
    A non-empty UNCERTAIN_MSG value generated by this function is merged with non-empty UNCERTAIN_MSG values which may exist in the optional input set of studies specified in studyList - separated by '|'.

  • NOT_VALID_MSG (character)
    Included when parameter noFilterReportUncertain=TRUE.
    In case the STSTDTC cannot be confidently decided, the column contains an indication of the reason.
    Is NA for rows where STSTDTC can be confidently decided.
    A non-empty NOT_VALID_MSG value generated by this function is merged with non-empty NOT_VALID_MSG values which may exist in the input set of studies specified in studyList - separated by '|'.

Examples

## Not run: 
GetStudyListSTSTDTC(myDbToken, allSTudies, '2018','2020')

## End(Not run)

sendigR documentation built on Aug. 18, 2022, 9:07 a.m.