Skip to contents

Extract a set of findings for a specified study phase - or just add phase for each animal.

Source: R/getFindingsPhase.R
getFindingsPhase.Rd

Returns a data table with the set of findings rows included in the findings of the phase(s) specified in the phaseFilter.
If the phaseFilter is empty (null, na or empty string), all rows from findings are returned with the an additional PHASE column.

Usage

getFindingsPhase(
  dbToken,
  findings,
  phaseFilter = NULL,
  inclUncertain = FALSE,
  noFilterReportUncertain = TRUE
)

Arguments

dbToken

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

findings

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

  • STUDYID

  • USUBJID

  • DOMAIN

  • domainSEQ

  • domainDTC

where domain is the name of the actual findings domain - e.g. LBSEQ and LBDTC

phaseFilter

Optional, character.
The phase 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.
Only relevant if the phaseFilter is not empty.
Indicates whether finding rows for which the phase cannot be confidently identified shall be included or not in the output data table.

noFilterReportUncertain

Mandatory, boolean.
Only relevant if the phaseFilter is empty.
Indicates if the reason should be included if the phase 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)

  • PHASE (character)

  • UNCERTAIN_MSG (character)
    Included when parameter inclUncertain=TRUE.
    In case the phase 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, all messages for subjects per pool/findings are merged together and reported as one message per pool/finding.
    Is NA for rows where phase 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 phase cannot be confidently decided, the column contains an indication of the reason.
    Is NA for rows where phase 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 findings findings - separated by '|'.

Details

The logic for the extraction is based on the subject elements and the trial design domains - for each finding row:

  • The related subject element is found in SE as the row where the value of domainDTC is within the interval from SESTDTC to SEENDTC

  • The actual EPOCH is found in TA in the row matching the found element (via the ETCD value)

  • The actual study phase is derived from the EPOCH value matching at set of text patterns

For pooled findings rows - i.e. POOLID is populated instead of USUBJID - the phase is identified per animal included in the each pool and finding, and if all identified phases are equal per pool and finding, the identified phase are returned per pool and finding.

The populated value of a phase is one of:

  • 'Screening'
    If TA.EPOCH fulfills one:

    • contains 'pre' followed by one of ['treat','trt','dos',test','study','exposure']

    • contains one of ['acclimat','screen','baseline','allocat','random']

  • 'Recovery'
    If TA.EPOCH doesn't fulfill the pattern for 'Screening' and fulfills one of:

    • contains 'recovery'

    • contains 'post' followed by one of ['treat','trt','dos','test','study','exposure']

  • 'Treatment'
    If TA.EPOCH doesn't fulfill the patterns for 'Screening' or 'Recovery' and fulfills both:

    • contains one of ['treat','trt','dos','test','exposure']

    • does not contain any of ['off','non'|','free'|','holiday']

  • 'Uncertain'
    If the TA.EPOCH is empty or does not fulfills any of the requirements described for the three phases above.

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

  • One of the date/time values SESTDTC, SEENDTC or domainDTC is empty or contains an invalid ISO 8601 value

  • The value of domainDTC is included in more then one SESTDTC/SEENDTC interval

  • The EPOCH value does not match any of the patterns identifying the set of possible study phases.

  • Different phases have been identified for individual subjects in a pool for a given finding

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

Examples

if (FALSE) {
# Extract LB rows for the Treatment phase - include uncertain rows
getFindingsPhase(dbToken, lb,
                 phaseFilter = 'Treatment',
                 inclUncertain = TRUE)
# No filtering, just add PHASE to FW rows - do not include messages when
# the phase cannot be confidently identified
getFindingsPhase(dbToken, fw,
                 noFilterReportUncertain = FALSE)
}