R/calc_fu.r

In mmparker/to1check: Reporting and quality checks for TBESC TO 1 data

#' Generates a report of participants eligible for follow-up.
#' 
#' This function generates a data.frame of participants who are eligible
#' to complete a 6-, 12-, 18-, or 24-month follow-up interview.
#' 
#' 
#' @return
#' This function returns a data.frame of participants who are eligible for
#' follow-up, including study ID, original visit date, the date the person
#' became eligible for this follow-up period, the end date of the eligibility
#' period, the number of days until the end of the follow-up period, and
#' and indicator of whether the follow-up has been completed.
#' The data.frame is ordered by days left to complete the interview.
#' 
#' 
#' @param cleanlist The list of cleaned TO1 data generated by 
#'   \code{\link{clean_to1}}
#' 
#' @seealso \code{\link{check_fu}} for identifying follow-ups that occurred
#'     outside of an eligibility period.
#' 
#' @export

calc_fu <- function(cleanlist) {


    # Subset to those with 1+ positive tests who completed enrollment
    # This is a crude approximation
    testpos <- cleanlist$master[cleanlist$master$CloseReason %in% "Open",
                                c("StudyID", "EnrollDate")]

    # Use visit date as the date of record - the protocol allows some 
    # variability, but this ought to be close enough.
    fu.months <- c(6, 12, 18, 24)


    # Iterate over each possible month of FU, then bind them all together
    fu.report <- ldply(fu.months, .fun = function(fu.month) {

        # Load the test-positive
        parts <- testpos

        # Mark the start of their follow-up period
        # Enrollment date plus two days (to approximate date of TST reading)
        # This follow-up's number of months, with a standard 30-day month
        # Less 14 days for the front edge of the FU window.
        parts$fu_start <- (parts$EnrollDate + 2) + (fu.month * 30) - 14

        # Mark the end of their follow-up period
        # Enrollment date plus two days (to approximate date of TST reading)
        # This follow-up's number of months, with a standard 30-day month
        # Plus 30 days for the rear edge of the FU window.
        parts$fu_end <- parts$EnrollDate %m+% months(fu.month) + days(30)

        # If today is inside those dates, they're eligible for FU
        parts$eligible <- Sys.Date() >= parts$fu_start &
                            Sys.Date() <= parts$fu_end

        # Add an indicator for which FU this is
        parts$which_fu <- fu.month


        # Calculate the number of days left for FU
        parts$days_left <- parts$fu_end - Sys.Date()



        # Determine whether it's been completed
        fu_complete <- with(cleanlist$followupfortb,
            cleanlist$followupfortb[VisitInterval %in% fu.month, ]
        )

        parts$completed <- parts$StudyID %in% fu_complete$StudyID



        # Return only those who are eligible
        parts[parts$eligible %in% TRUE & parts$completed %in% FALSE, ]

    })


    # Return
    fu.report[order(fu.report$days_left, decreasing = TRUE), ]

}