getControlSubj {sendigR}

Extract a list of control animals for a list of studies

Description

Returns a data table with a list of animals belonging to the groups for negative control in the given list of studies.

Usage

getControlSubj(dbToken, studyList, inclUncertain = FALSE)

Arguments

dbToken

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

studyList

Mandatory, data.table.
A table with a list of studies to limit the output to be within this set of studies.
The table must include a column named 'STUDYID'.

inclUncertain

Mandatory, boolean.
Indicates whether animals, which cannot be identified as neither negative nor positive control (i.e. uncertain animals), shall be included or not in the output data table.

Details

The set of animals contains all animals from DM where the SETCD is associated with a TX parameter 'TCNTRL'. Negative control animals are further defined by

• either containing a word from a set of words, to automatically distinguish it as a negative control:

  • ['placebo', 'untreated', 'sham']

• or containing a combination of a word from of two lists:

  1. ['negative', 'saline', 'peg', 'vehicle', 'citrate', 'dextrose', 'water', 'air']

  2. ['item', 'control', 'article']

Animals are in all cases excluded (i.e. whether inclUncertain=TRUE or inclUncertain=FALSE) from the output set, when they are identified as positive control animals - i.e. they are associated with a TX parameter 'TCNTRL' containing a word from this set of words:

• ['positive','reference']

The age in days at reference start date is calculated for each animal based on the age related variables in DM:

1. If BRTHDTC is populated compute DM.RFSTDTC – DM.BRTHDTC + 1

2. Else If AGE is populated convert from units specified in AGEU to days.

3. Else If AGETXT is populated convert the mid-point of the range from units specified in AGEU to days.
   These AGEU units are handled with the described conversion from value to number of days:

   • DAYS

   • WEEKS : value * 7

   • MONTHS : value * 365/12

   • YEARS : value * 365

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

• TX parameter 'TCNTRL' is missing

• TXVAL for TX parameter 'TCNTRL' cannot be identified as Negative or Positive control according to the algorithm described above

Value

The function return a data.table with columns:

• STUDYID (character)

• Additional columns contained in the studyList table

• TCNTRL (character)
  The value of the TX parameter TCNTRL which is used for identification of whether it is a negative control group or not

• USUBJID (character)

• RFSTDTC (character)

• DM_AGEDAYS (integer)
  The calculated age in days of the animal at the reference start day - i.e. the age registered in DM.

• DSDECOD (character)
  The standardized disposition term for the animal

• DS_AGEDAYS (integer)
  The calculated age in days of the animal at the disposition

• NO_AGE_MSG (character)
  Empty or contains the reason if a DM_AGEDAYS couldn't be calculated

• UNCERTAIN_MSG (character)
  Included when parameter inclUncertain=TRUE.
  Contains the reason for an uncertain animal is NA for rows for confident identified negative control animals.

• NOT_VALID_MSG (character)
  Included if the column is included in data table specified in studyList,

Examples

## Not run: 
controlAnimals <- getControlSubj(myDbToken, allSTudies)

## End(Not run)