sendigR (version 1.0.0)

getSubjSex: Extract the set of animals of the specified sex - or just add the sex of each animal.

Description

Returns a data table with the set of animals included in the animalList of the sex specified in the sexFilter.
If the sexFilter is empty (null, na or empty string) - all rows from animalList are returned with the an additional populated SEX column.

Usage

getSubjSex(
  dbToken,
  animalList,
  sexFilter = NULL,
  inclUncertain = FALSE,
  noFilterReportUncertain = TRUE
)

Value

The function returns a data.table with columns:

• STUDYID (character)

• Additional columns contained in the animalList table

• SEX (character)

• UNCERTAIN_MSG (character)
  Included when parameter inclUncertain=TRUE.
  In case the sex cannot be confidently matched during the filtering of data, the column contains an indication of the reason.
  Is NA for rows where SEX can be confidently matched.
  A non-empty UNCERTAIN_MSG value generated by this function is merged with non-empty UNCERTAIN_MSG values which may exist in the input set of animals specified in animalList - separated by '|'.

• NOT_VALID_MSG (character)
  Included when parameter noFilterReportUncertain=TRUE.
  In case the sex cannot be confidently decided, the column contains an indication of the reason.
  Is NA for rows where sex 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 animals animalList - separated by '|'.

Arguments

dbToken

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

animalList

Mandatory, data.table.
A table with the list of animals to process.
The table must include at least columns named 'STUDYID' and 'USUBJID'.

sexFilter

Optional, character.
The sex value criterion to be used for filtering of the list of animals.
It can be a single string, a vector or a list of multiple strings.

inclUncertain

Mandatory, boolean.
Indicates whether animals for which the sex cannot be confidently identified shall be included or not in the output data table.

noFilterReportUncertain

Mandatory, boolean.
Only relevant if the sexFilter is empty.
Indicates if the reason should be included if the sex cannot be confidently decided for an animal.

Details

The sex value is decided from the DM.SEX variable.
The comparison of DM.SEX with the given value(s) in sexFilter is done case-insensitive.

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

• The DM.SEX value is empty or invalid (not CT value - CDISC codelist SEX - case insensitive comparison)

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

Examples

if (FALSE) {
getSubjSex(myDbToken, controlAnimals, 'M')
}