Skip to contents

Add the subject age at finding time - and optionally extract the set of findings within a specified range of age.

Source: R/getFindingsSubjAge.R
getFindingsSubjAge.Rd

Returns a data table with the set of findings rows included in the findings where the age of subjects at finding time is within the interval specified in fromAge to fromAge.
If the fromAge and fromAge are empty (null, na or empty string), all rows from findings are returned.

Usage

getFindingsSubjAge(
  dbToken,
  findings,
  animalList,
  fromAge = NULL,
  toAge = NULL,
  inclUncertain = FALSE,
  noFilterReportUncertain = TRUE
)

Arguments

dbToken

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

findings

Mandatory, data.table.
A table with the set of input finding rows to process.
The table must include at least columns named

  • STUDYID

  • USUBJID

  • DOMAIN

  • [domain]SEQ

  • [domain]DY

  • [domain]DTC

where [domain] is the name of the actual findings domain - e.g. LBSEQ, LBDY and LBDTC

animalList

Mandatory, data.table.
A data with the set of animals included in the findings table (may contain more animals than included in findings).
The data set must contain at least these columns returned by the function getControlSubj

  • STUDYID

  • USUBJID

  • RFSTDTC

  • DM_AGEDAYS

  • NO_AGE_MSG

fromAge

Optional, character
The start of age interval to extract.
Must be in a string in this format:
[value][age unit] where [age unit] is one of

  • d, day, days

  • w, week, weeks

  • m, month, months

  • y, year, years

The unit is case-insensitive, space(s) between age value and unit is allowed.

toAge

Optional. character
The start of age interval to extract.
Must be in a string in in the same format as described for fromAge.

inclUncertain

Mandatory, boolean.
Only relevant if the fromAge and/or toAge is/are not empty.
Indicates whether finding rows for which the age at finding time cannot be confidently identified, shall be included or not in the output data table.

noFilterReportUncertain

Optional, boolean.
Only relevant if the fromAge and toAge are empty.
Indicates if the reason should be included if the age at finding time cannot be confidently decided for an animal.

Value

The function returns a data.table with columns in this order:

  • All columns contained in the findings input table (original order except optional UNCERTAIN_MSG and NOT_VALID_MSG)

  • AGEDAYS (character)
    The subject age at finding time calculated in days. Is NA if thge age cannot be confidently calculated.

  • UNCERTAIN_MSG (character)
    Included when parameter inclUncertain=TRUE.
    In case the age at finding time cannot be confidently matched during the filtering of data, the column contains an indication of the reason.
    If any uncertainties have been identified for individual subjects included in pools for pooled finding rows, one message for is reported per pool/finding.
    Is NA for rows where the age at finding time 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 findings specified in findings - separated by '|'.

  • NOT_VALID_MSG (character)
    Included when parameter noFilterReportUncertain=TRUE.
    In case the age at finding time cannot be confidently calculated, the column contains an indication of the reason.
    Is NA for rows where age at finding time can be confidently calculated.
    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 findings findings - separated by '|'.

Details

In both situation, the subject age at finding time is calculated into an additional column AGEDAYS for each row in findings combined with the the additional input data.table animalList using this algorithm:

  • Determine the number of study days between study start and findings

    • if findings.[domain]DY is populated

      • If findings.[domain]DY > 0 then use findings.[domain]DY - 1

      • Else use findings.[domain]DY

    • Else If findings.[domain]DTC is populated compute animalList.RFSTDTC – findings.[domain]DTC in days
      where animalList.RFSTDTC is each subject's reference start date (DM.RFSTDTC)

  • Animal age at time of finding is then calculated as animalList.AGEDAYS + [study days between study start and findings]
    where animalList.AGEDAYS is the subject age at reference start date(calculated during extraction of control subjects in getControlSubj.

  • For pooled findings rows - i.e. POOLID is populated instead of USUBJID - the animal age at time of finding is calculated per animal included in the each pool and finding.

    • If all calculated ages are equal within a pool and finding, the calculated age is populated for this pool/finding.

    • If all calculated ages are within the same time internal (2 days) within a pool and finding, the minimum calculated age plus 1 day is populated for this pool/finding.

If both fromAge and toAge values are specified - all the rows from the input table findings where value of the calculated AGEDYAS is within the interval of the specified start/end age interval are returned - including the values equal to the start/end age values.
If only a fromAge value is specified - all the rows from the input table findings where value of AGEDYAS equal to or greater than the input age are returned.
If only a toAge value is specified - all the rows from input table findings where value of AGEDAYS is equal to or less than the input age are extracted and returned. The input age value(s) is/are converted to days before extraction of rows from the input data tables using the input value(s) as filter - using this conversion:

  • DAYS

  • WEEKS : value * 7

  • MONTHS : value * 365/12

  • YEARS : value * 365

If input parameter inclUncertain=TRUE, findings rows where the age at finding time cannot be confidently identified are included in the output set. These uncertain situations are identified and reported (in column UNCERTAIN_MSG):

  • No age at reference time has been calculated for subject (animalList.AGEDAYS)

  • Reference start time is missing or contains invalid ISO8601 date value for subject (animalList.RFSTDTC).

  • Missing [domain]DY value and missing or invalid ISO8601 date [domain]DTC value for finding

  • For pooled findings:

    • More than two days between minimum and maximum of animalList.AGEDAYS for the set of animals in a pool.

    • Different values in animalList.RFSTDTC for the set of animals in a pool.

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

Examples

if (FALSE) {
# Extract LB rows for the animals at age between 8 and 12 weeks at finding
# time - include uncertain rows
getFindingsSubjAge(dbToken = db,
                   findings = lb,
                   animalList = animals,
                   fromAge = '8w',
                   toAge = '12w',
                   inclUncertain = TRUE)
# No filtering, just add AGEDAYS to FW rows - do not include messages when
# the AGEDAYS cannot be confidently identified
getFindingsSubjAge(dbToken = db, findings = fw,  animalList = animals,
                   noFilterReportUncertain = FALSE)
}