Extract the set of animals of the specified species and strain - or just add the species and strain for each animal.

Returns a data table with the set of animals included in the animalList matching the species and strain specified in the speciesFilter and strainFilter.
If the speciesFilter and strainFilter are empty (null, na or empty string) - all rows from animalList are returned with additional populated SPECIES and STRAIN columns.

Usage

getSubjSpeciesStrain(
  dbToken,
  animalList,
  speciesFilter = NULL,
  strainFilter = NULL,
  inclUncertain = FALSE,
  exclusively = FALSE,
  noFilterReportUncertain = TRUE
)

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'.

speciesFilter

Optional, character.
The species value(s) to use as criterion for filtering of the input data table.
It can be a single string, a vector or a list of multiple strings.

strainFilter

Optional, character.
The strain value(s) to use as criterion for filtering of the input data table.
It is only valid to specify value(s) if one or more values have been specified for parameter speciesFilter
It can be a single string, a vector or a list of multiple strings. When multiple values are specified for speciesFilter, each strain value must be prefixed by species and ':' , e.g. c('RAT:WISTAR','DOG: BEAGLE').
There may be included any number of blanks after ':'

inclUncertain

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

exclusively

Mandatory, boolean.

TRUE: Include animals only for studies with no other species and optional strains then included in speciesFilter and strainFilter
FALSE: Include animals for all studies with species and strain matching speciesFilter and strainFilter respectively.

noFilterReportUncertain

Optional, boolean.
Only relevant if the speciesFilter and strainFilter are empty.
Indicates if the reason should be included if the species or strain cannot be confidently decided for an animal.

Value

The function returns a data.table with columns:

STUDYID (character)
Additional columns contained in the animalList table
SPECIES (character) The value is always returned in uppercase and trimmed for leading/trailing blanks.
STRAIN (character) The value is always returned in uppercase and trimmed for leading/trailing blanks.
UNCERTAIN_MSG (character)
Included when parameter inclUncertain=TRUE.
In case the species or strain cannot be confidently matched during the filtering of data, the column contains an indication of the reason.
Is NA for rows where species and strain 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 species or strain cannot be confidently decided, the column contains an indication of the reason.
Is NA for rows where species and strain 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 '|'.

Details

The species and strain per animal respectively are identified by a hierarchical lookup in these domains

DM - If the DM.SPECIES (DM.STRAIN) isn't empty, this value is included in the output.
TX - if a TX parameter 'SPECIES' ('STRAIN') exists for the group related to the animal, the TXVAL value for this is included in the output.
TS - if a TS parameter 'SPECIES' ('STRAIN') exists, this is included in the output.

The comparisons of species/strain values is done case insensitive and trimmed for leading/trailing blanks.

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

TS parameter SPECIES/STRAIN is missing or invalid (not CT value - CDISC SEND code list SPECIES/STRAIN) and TX parameter SPECIES/STRAIN is missing or invalid (not CT value) and DM.SPECIES/STRAIN is missing or invalid (not CT value)
Different values of SPECIES/STRAIN across TS, TX and DM for studies where no or only one TS parameter SPECIES/STRAIN is registered
Multiple TS parameter SPECIES/STRAIN values are registered for study and TX parameter SPECIES/STRAIN and/or DM.SPECIES/STRAIN do not match any of the TS values.
Multiple TS parameter SPECIES/STRAIN values are registered for study and TX parameter SPECIES/STRAIN and DM.SPECIES/STRAIN are unequal.

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

Examples

if (FALSE) {
# Extract rats and mice plus uncertain animals
getSubjSpeciesStrain(dbToken, controlAnimals,
                     speciesFilter = c('RAT', 'MOUSE'),
                     inclUncertain = TRUE)
# Extract Spargue-Dawley rats plus uncertain animals.
# Include only animals from studies which do not contain other species or
# strains
getSubjSpeciesStrain(dbToken, controlAnimals,
                     speciesFilter = 'RAT',
                     strainFilter = 'SPRAGUE-DAWLEY',
                     inclUncertain = TRUE,
                     exclusively = TRUE,
                     noFilterReportUncertain = TRUE)
# Extract Wistar rats and and Beagle dogs - and no uncertain animals
getSubjSpeciesStrain(dbToken, controlAnimals,
                     speciesFilter = c('RAT', 'DOG'),
                     strainFilter = c('RAT: WISTAR', 'DOG: BEAGLE'))
# No filtering, just add SPECIES and STRAIN - do not include messages when
# these values cannot be confidently found
getSubjSpeciesStrain(dbToken, controlAnimals,
                     noFilterReportUncertain = FALSE)
}