R/extract-estimation-info.R

Defines functions extract_estimation_info_graph_multi extract_estimation_info_graph extract_estimation_info_tbl_multi extract_estimation_info_tbl add_missing_roles_for_proband

Documented in extract_estimation_info_graph extract_estimation_info_graph_multi extract_estimation_info_tbl extract_estimation_info_tbl_multi

utils::globalVariables("trait")
utils::globalVariables("matchID")



#'
#' Add in missing roles for proband
#'
#' This function adds missing roles for a proband and fills lower threshold values with -Inf and upper threshold values with Inf.
#'
#' @param temp_tbl tibble to add missing proband roles to; originates from .tbl of estimate_liability.
#' @param role name of role column
#' @param cur_roles values of the role column
#' @param cur_fid current family ID being worked on
#' @param pid name of column with personal IDs
#' @param fid name of column with family IDs
#' @param useMixture whether mixture model input is returned
#' @param phen_names vector of phenotype names as given in .tbl of estimate_liability. Defaults to NULL (which is single trait).
#'
#' @return The provided temp_tbl object is returned, but with the missing "g" and/or "o" roles added, where -Inf and Inf values
#' have been used to fill the lower and upper threshold values. If phen_names is provided, a pair of upper and lower values is
#' provided for each entry in phen_names.
#'
#' @importFrom dplyr filter pull tibble %>% bind_rows
#' @noRd

add_missing_roles_for_proband = function(temp_tbl, role, cur_roles, cur_fid, pid, fid, useMixture, phen_names = NULL) {
  # role types to check for, centered on proband
  to_check_for = c("g", "o")

  # roles is already calculated; are they present?
  to_be_added = setdiff(to_check_for,   cur_roles)
  present     = intersect(to_check_for, cur_roles)

  # if some present, extract individual ID, if not, get family ID
  # note: %in% (not ==) since `present` can have length 2 (both g and o
  # already present) - == would recycle against the column instead of
  # testing membership.
  if (length(present) > 0 ) {
    i_pid = (temp_tbl %>% filter(!!as.symbol(role) %in% present) %>% pull(!!as.symbol(pid)))[1]
  } else {
    i_pid = pull(temp_tbl, !!as.symbol(fid))[1]
  }
  # suffixes of roles to be added
  id_suffixes = paste0("_",to_be_added) %>% stringr::str_replace_all(., "_o", "")

  if ( is.null(phen_names) ) { # single trait
    if (useMixture) {
      # construct tibble with desired roles
      tibble(
        !!as.symbol(fid) := pull(temp_tbl, !!as.symbol(fid))[1],
        !!as.symbol(pid)    := paste0(i_pid, id_suffixes),
        !!as.symbol(role)   := to_be_added,
        lower = rep(-Inf, length(to_be_added)),
        upper = rep( Inf, length(to_be_added)),
        K_i   = rep(NA, length(to_be_added)),
        K_pop = rep(NA, length(to_be_added))
      ) %>%
        bind_rows(., temp_tbl)

    } else {
      # construct tibble with desired roles
      tibble(
        !!as.symbol(fid) := pull(temp_tbl, !!as.symbol(fid))[1],
        !!as.symbol(pid)    := paste0(i_pid, id_suffixes),
        !!as.symbol(role)   := to_be_added,
        lower = rep(-Inf, length(to_be_added)),
        upper = rep( Inf, length(to_be_added))
      ) %>%
        bind_rows(., temp_tbl)
    }

  } else { # multi trait
    # constructs id rows, then adds lower and upper thresholds from phen_names provided
    if (useMixture) {
      tibble(
        !!as.symbol(fid) := pull(temp_tbl, !!as.symbol(fid))[1],
        !!as.symbol(pid)    := paste0(i_pid, id_suffixes),
        !!as.symbol(role)   := to_be_added
      ) %>%
        bind_cols(
          tibble(!!!c(stats::setNames(rep(-Inf, length(phen_names)), paste0("lower_", phen_names)),
                      stats::setNames(rep( Inf, length(phen_names)), paste0("upper_", phen_names)),
                      stats::setNames(rep(NA, length(phen_names)), paste0("K_i_", phen_names)),
                      stats::setNames(rep(NA, length(phen_names)), paste0("K_pop_", phen_names))))) %>%
        bind_rows(
          .,
          temp_tbl
        )
    } else {
      tibble(
        !!as.symbol(fid) := pull(temp_tbl, !!as.symbol(fid))[1],
        !!as.symbol(pid)    := paste0(i_pid, id_suffixes),
        !!as.symbol(role)   := to_be_added
      ) %>%
        bind_cols(
          tibble(!!!c(stats::setNames(rep(-Inf, length(phen_names)), paste0("lower_", phen_names)),
                      stats::setNames(rep( Inf, length(phen_names)), paste0("upper_", phen_names))))) %>%
        bind_rows(
          .,
          temp_tbl
        )
    }

  }
}




#' Title Internal Function used to extact input needed for liability estimation
#'
#' @param .tbl .tbl input from estimate_liability
#' @param cur_fid current family ID being worked on
#' @param h2 heritability value from estimate_liability
#' @param fid name of family ID column
#' @param pid name of personal ID column
#' @param role name of role column
#' @param useMixture whether mixture model input is returned
#' @param add_ind Whether the genetic liability be added. Default is TRUE.
#'
#' @returns list with two elements: tbl (tibble with all relevant information) and cov (covariance matrix) estimated through construct_covmat()
#'
#' @export
extract_estimation_info_tbl = function(.tbl, cur_fid, h2, fid, pid, role, useMixture, add_ind = TRUE) {
  # extract all with current family ID.
  temp_tbl = filter(.tbl, !!as.symbol(fid) == cur_fid)

  # Extract the roles for all family members
  roles <- pull(temp_tbl, !!as.symbol(role))

  # Constructing the covariance matrix.
  cov_obj <- construct_covmat(fam_vec = roles, n_fam = NULL, add_ind = add_ind, h2 = h2)

  # check for whether covariance matrix is positive definite
  # correct if needed.
  cov_PD = correct_positive_definite_simplified(covmat = cov_obj)
  cov = cov_PD$covmat

  # adding missing roles (of either g or o)
  if (add_ind) {
    temp_tbl = add_missing_roles_for_proband(temp_tbl = temp_tbl,
                                             role = role,
                                             useMixture = useMixture,
                                             cur_roles = roles,
                                             cur_fid = cur_fid,
                                             pid = pid,
                                             fid = fid)

  }

  # Now that we have extracted all the relevant information, we only need to
  # order the observations before we can run the Gibbs sampler/PA algorithm,
  # as g and o need to be the first two observations (when present, i.e.
  # when add_ind = TRUE). We order against cov's own column names - built
  # from these same `roles` a few lines up - rather than hardcoding
  # c("g", "o"), so this works whether or not add_ind adds them, and never
  # relies on a role being present that the covariance matrix doesn't also
  # expect (mirrors extract_estimation_info_tbl_multi()'s matchID approach).
  ord_idx <- match(colnames(cov), pull(temp_tbl, !!as.symbol(role)))
  if (anyNA(ord_idx)) {
    stop("extract_estimation_info_tbl: could not align .tbl to the covariance ",
        "matrix for family '", cur_fid, "' - a required role is missing from the input.")
  }
  temp_tbl <- temp_tbl[ord_idx, ]
  return(list(tbl = temp_tbl, cov = cov))
}

#' Title Internal Function used to extact input needed from multi-trait tibble input for liability estimation
#'
#' @param .tbl .tbl input from estimate_liability
#' @param cur_fid current family ID being worked on
#' @param h2 vector of heritability value from estimate_liability
#' @param fid name of family ID column
#' @param pid name of personal ID column
#' @param role name of role column
#' @param useMixture whether mixture model input is returned
#' @param phen_names vector of phenotype names as given to estimate_liability
#' @param genetic_corrmat genetic correlation matrix as given to estimate_liability
#' @param full_corrmat full correlation matrix as given to estimate_liability
#' @param add_ind Whether the genetic liability be added. Default is TRUE.
#'
#' @returns list with two elements: tbl (tibble with all relevant information) and cov (covariance matrix) estimated through construct_covmat()
#'
#' @export
extract_estimation_info_tbl_multi = function(.tbl, cur_fid, h2, fid, pid, role, useMixture, phen_names, genetic_corrmat, full_corrmat, add_ind = TRUE) {
  # extract all with current family ID.
  temp_tbl = filter(.tbl, !!as.symbol(fid) == cur_fid)

  # Extract the roles for all family members
  roles <- pull(temp_tbl, !!as.symbol(role))

  # Constructing the covariance matrix.
  cov_obj <- construct_covmat(fam_vec = roles, n_fam = NULL, add_ind = add_ind, h2 = h2,
                              genetic_corrmat = genetic_corrmat,
                              full_corrmat = full_corrmat,
                              phen_names = phen_names)

  # check for whether covariance matrix is positive definite
  # correct if needed.
  cov_PD = correct_positive_definite_simplified(covmat = cov_obj)
  cov = cov_PD$covmat

  # adding missing roles (of either g or o)
  if (add_ind) {
    temp_tbl = add_missing_roles_for_proband(temp_tbl = temp_tbl,
                                             role = role,
                                             useMixture = useMixture,
                                             cur_roles = roles,
                                             cur_fid = cur_fid,
                                             pid = pid,
                                             fid = fid,
                                             phen_names = phen_names)

  }

  # Now that we have extracted all the relevant information, we
  # only need to order the observations before we can run
  # Gibbs sampler, as g and o need to be the first two observations.

  # pivoting longer to have one row per individual-trait combination
  if (useMixture) {
    temp_tbl <- temp_tbl %>%
      select(!!as.symbol(fid), !!as.symbol(pid), !!as.symbol(role),
             starts_with("lower_"), starts_with("upper_"),
             starts_with("K_i_"), starts_with("K_pop_")) %>%
      tidyr::pivot_longer(
        cols = -c(fid, pid, role),
        names_to = c(".value", "trait"),
        names_pattern = "(lower|upper|K_i|K_pop)_(.*)"
      ) %>%
      mutate(matchID = paste0(!!as.symbol(role), "_", trait)) %>%
      select(-trait)

  } else {
    temp_tbl <- temp_tbl %>%
      select(!!as.symbol(fid), !!as.symbol(pid), !!as.symbol(role),
             starts_with("lower_"), starts_with("upper_")) %>%
      tidyr::pivot_longer(
        cols = -c(fid, pid, role),
        names_to = c(".value", "trait"),
        names_pattern = "(lower|upper)_(.*)"
      ) %>%
      mutate(matchID = paste0(!!as.symbol(role), "_", trait)) %>%
      select(-trait)
  }

  # ordering temp_tbl to match covmat
  ord_idx = match(colnames(cov), pull(temp_tbl, matchID))
  temp_tbl = temp_tbl[ord_idx, ] %>%
    select(-matchID)

  return(list(tbl = temp_tbl, cov = cov))
}

#' Title Internal Function used to extact input needed from graph input for liability estimation
#'
#' @param cur_fam_graph neightbourhood graph of degree n around proband
#' @param cur_fid proband ID
#' @param h2 heritability value from estimate_liability
#' @param pid Name of column of personal ID
#' @param useMixture whether mixture input is returned
#' @param add_ind Whether the genetic liability be added. Default is TRUE.
#'
#' @returns list with two elements: tbl (tibble with all relevant information) and cov (covariance matrix) estimated through graph_based_covariance_construction()
#'
#' @export
#'
extract_estimation_info_graph = function(cur_fam_graph, cur_fid, h2, pid, useMixture, add_ind = TRUE) {
  # extract current (local) family graph and
  # construct covariance and extract threshold information from graph.
  cov_obj = graph_based_covariance_construction(pid = pid,
                                                cur_proband_id = cur_fid,
                                                cur_family_graph = cur_fam_graph,
                                                useMixture = useMixture,
                                                h2 = h2, add_ind = add_ind)
  # cov and temp_tbl are ordered during construction

  # check whether covariance matrix is positive definite
  # correct if needed.
  cov_PD = correct_positive_definite_simplified(covmat = cov_obj$covmat)

  return(list(tbl = cov_obj$temp_tbl, cov = cov_PD$covmat))
}


#' Title Internal Function used to extact input needed from multi-trait graph input for liability estimation
#'
#' @param cur_fam_graph neightbourhood graph of degree n around proband
#' @param fid Name of column of family ID
#' @param pid Name of column of personal ID
#' @param cur_fid proband ID
#' @param h2_vec vector of heritability values from estimate_liability
#' @param genetic_corrmat genetic correlation matrix as given to estimate_liability
#' @param phen_names vector of phenotype names as given to estimate_liability
#' @param useMixture whether mixture model is used
#' @param add_ind Whether the genetic liability be added. Default is TRUE.
#'
#' @returns list with three elements: tbl (tibble with all relevant information),
#' cov (covariance matrix) estimated through graph_based_covariance_construction_multi(),
#' and newOrder (order of individuals in covariance matrix)
#' @export
extract_estimation_info_graph_multi = function(cur_fam_graph, fid, pid, cur_fid,  h2_vec, genetic_corrmat, phen_names, useMixture, add_ind = TRUE) {
  # extract current (local) family graph and
  # construct covariance and extract threshold information from graph.
  cov_obj = graph_based_covariance_construction_multi(
    fid = fid,
    pid = pid,
    cur_proband_id = cur_fid,
    cur_family_graph = cur_fam_graph,
    h2_vec = h2_vec,
    genetic_corrmat = genetic_corrmat,
    phen_names = phen_names,
    useMixture = useMixture,
    add_ind = add_ind)
  # cov and temp_tbl are ordered during construction

  # check whether covariance matrix is positive definite
  # correct if needed.
  cov_PD = correct_positive_definite_simplified(covmat = cov_obj$cov)

  return(list(tbl = cov_obj$temp_tbl, cov = cov_PD$covmat, newOrder = cov_obj$newOrder) )
}

Try the LTFGRS package in your browser

Any scripts or data that you put into this service are public.

LTFGRS documentation built on Nov. 20, 2026, 5:10 p.m.