R/estimate-liability.R

Defines functions estimate_liability_single

Documented in estimate_liability_single

utils::globalVariables("lower")
utils::globalVariables("upper")
utils::globalVariables("pb")
utils::globalVariables("phenotype")
utils::globalVariables("est")
utils::globalVariables("se")
utils::globalVariables("name")

#' Estimating the genetic or full liability
#'
#' \code{estimate_liability_single} estimates the genetic component of the full
#' liability and/or the full liability for a number of individuals based
#' on their family history.
#'
#' This function can be used to estimate either the genetic component of the
#' full liability, the full liability or both. It is possible to input either
#'
#' @param .tbl A matrix, list or data frame that can be converted into a tibble.
#' Must have at least five columns that hold the family identifier, the personal
#' identifier, the role and the lower and upper thresholds. Note that the
#' role must be one of the following abbreviations
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to \code{NULL}.
#' @param family_graphs A tibble with columns pid and family_graph_col.
#' See prepare_graph for construction of the graphs. The family graphs Defaults to NULL.
#' @param h2 A number representing the heritability on liability scale
#' for a single phenotype. Must be non-negative. Note that under the liability threshold model,
#' the heritability must also be at most 1.
#' Defaults to 0.5.
#' @param  pid A string holding the name of the column in \code{.tbl} (or \code{family} and
#' \code{threshs}) that hold the personal identifier(s). Defaults to "PID".
#' @param fid A string holding the name of the column in \code{.tbl} or \code{family} that
#' holds the family identifier. Defaults to "fid".
#' @param role A string holding the name of the column in \code{.tbl} that
#' holds the role. Each role must be chosen from the following list of abbreviations
#' - \code{g} (Genetic component of full liability)
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to "role".
#' @param family_graphs_col Name of column with family graphs in family_graphs. Defaults to "fam_graph".
#' @param out A character or numeric vector indicating whether the genetic component
#' of the full liability, the full liability or both should be returned. If \code{out = c(1)} or
#' \code{out = c("genetic")}, the genetic liability is estimated and returned. If \code{out = c(2)} or
#' \code{out = c("full")}, the full liability is estimated and returned. If \code{out = c(1,2)} or
#' \code{out = c("genetic", "full")}, both components are estimated and returned.
#' Defaults to \code{c(1)}.
#' @param tol A number that is used as the convergence criterion for the Gibbs sampler.
#' Equals the standard error of the mean. That is, a tolerance of 0.2 means that the
#' standard error of the mean is below 0.2. Defaults to 0.01.
#' @param method Estimation method used to estimate the (genetic) liability. Defaults to "PA".
#' Current implementation of PA only supports estimates of genetic liability. For full or both
#' genetic and full liability estimates use "Gibbs".
#' @param useMixture Logical indicating whether the mixture model should be used to calculate the genetic liability.
#' Requires K_i and K_pop columns as well as lower and upper. Defaults to FALSE.
#'
#' @return If \code{family} and \code{threshs} are two matrices, lists or
#' data frames that can be converted into tibbles, if \code{family} has two
#' columns named like the strings represented in \code{pid} and \code{fid}, if
#' \code{threshs} has a column named like the string given in \code{pid} as
#' well as a column named "lower" and a column named "upper" and if the
#' liability-scale heritability \code{h2}, \code{out}, \code{tol} and
#' \code{always_add} are of the required form, then the function returns a
#' tibble with either four or six columns (depending on the length of out).
#' The first two columns correspond to the columns \code{fid} and \code{pid} '
#' present in \code{family}.
#' If \code{out} is equal to \code{c(1)} or \code{c("genetic")}, the third
#' and fourth column hold the estimated genetic liability as well as the
#' corresponding standard error, respectively.
#' If \code{out} equals \code{c(2)} or \code{c("full")}, the third and
#' fourth column hold the estimated full liability as well as the
#' corresponding standard error, respectively.
#' If \code{out} is equal to \code{c(1,2)} or \code{c("genetic","full")},
#' the third and fourth column hold the estimated genetic liability as
#' well as the corresponding standard error, respectively, while the fifth and
#' sixth column hold the estimated full liability as well as the corresponding
#' standard error, respectively.
#'
#' @examples
#' sims <- simulate_under_LTM(fam_vec = c("m","f","s1"), n_fam = NULL,
#' add_ind = TRUE, h2 = 0.5, n_sim=10, pop_prev = .05)
#' #
#' estimate_liability_single(.tbl = sims$thresholds,
#' h2 = 0.5, pid = "indiv_ID", fid = "fid", role = "role", out = c(1),
#' tol = 0.01)
#' #
#' sims <- simulate_under_LTM(fam_vec = c(), n_fam = NULL, add_ind = TRUE,
#' h2 = 0.5, n_sim=10, pop_prev = .05)
#' #
#' estimate_liability_single(.tbl = sims$thresholds,
#' h2 = 0.5, pid = "indiv_ID", fid = "fid", role = "role",
#' out = c("genetic"), tol = 0.01)
#'
#' @seealso \code{\link[future.apply]{future_apply}}, \code{\link{estimate_liability_multi}},
#' \code{\link{estimate_liability}}
#'
#' @importFrom dplyr %>% pull bind_rows bind_cols select filter tibble
#' @importFrom stringr str_ends str_split str_subset str_detect
#' @importFrom rlang :=
#' @importFrom igraph vertex_attr
#'
#' @export
estimate_liability_single <- function(.tbl = NULL,
                                      family_graphs = NULL,
                                      h2 = 0.5,
                                      pid = "pid",
                                      fid = "fid",
                                      family_graphs_col = "fam_graph",
                                      role = NULL,
                                      out = c(1),
                                      tol = 0.01,
                                      useMixture = FALSE,
                                      method = "PA"){


  # validating input-agnostic variables --------------------------------------
  if (!(method %in% c("PA", "Gibbs"))) {
    stop(paste0("estimate_liability_single: method must be either 'PA' or 'Gibbs'!\n You entered: ", method))
  }
  # Turning pid and fid into strings
  pid <- as.character(pid)
  fid <- as.character(fid)

  # Checking that the heritability is valid
  if (validate_proportion(h2)) invisible()

  # Checking that tol is valid
  if (!is.numeric(tol) && !is.integer(tol)) stop("The tolerance must be numeric!")
  if (tol <= 0) stop("The tolerance must be strictly positive!")

  # Checking that out is either a character vector or a numeric vector
  if (is.numeric(out)) {

    out <- intersect(out, c(1,2))

  } else if (is.character(out)) {

    out <- c("genetic", "full")[rowSums(sapply(out, grepl, x = c("genetic", "full"))) > 0]
    out[out == "genetic"] <- 1
    out[out == "full"] <- 2
    out <- as.numeric(out)
  } else {
    stop("out must be a numeric or character vector!")
  }

  # Checking whether out is empty
  if (length(out) == 0) {
    warning("out is not of the required format! \n The function will return the estimated genetic liability!")
    out <- c(1)
  }

  # Sorting out
  out <- sort(out)


  # Validating input specific variables -------------------------------------

  # only one of .tbl / family_graphs may be given - .tbl silently takes
  # precedence otherwise, so family_graphs would be used for nothing
  if (!is.null(.tbl) && !is.null(family_graphs)) {
    stop("estimate_liability_single: provide only one of .tbl or family_graphs, ",
         "not both.")
  }

  if ( !is.null(.tbl) ) { #### .tbl input ####
    # validating .tbl input
    .tbl <- validate_tbl_input(.tbl = .tbl,
                                 pid = pid,
                                 fid = fid,
                                 role = role,
                                 useMixture = useMixture)

    # Extracting the (unique) family identifiers
    fam_list <- unique(pull(.tbl, !!as.symbol(fid)))

  } else if ( !is.null(family_graphs) ) { #### Graph input ####

    # validating graph input (nothing is returned)
    return_catch <- validate_graph_input(family_graphs = family_graphs,
                                           fid = fid,
                                           family_graphs_col = family_graphs_col,
                                           useMixture = useMixture)

    # Extracting the (unique) family identifiers
    fam_list <- unique(pull(family_graphs, !!as.symbol(fid)))


  } else ( stop("no valid input used.") )


# Starting estimation -----------------------------------------------------

  # how many workers are we using?
  message(paste0("The number of workers is ", future::nbrOfWorkers(), "\n"))

  # actual liability estimates happen below
  gibbs_res <- future.apply::future_lapply(X = 1:length(fam_list), FUN = function(i){

    # current family id (proband id for graphs)
    cur_fid = fam_list[i]

    ##### Ultimately, we get cov and temp_tbl from both of the cases below #####

    if ( !is.null(family_graphs) ) { # family_graph based covariance construction
      ph = extract_estimation_info_graph(
        # no need to pass family_Graphs, family_graphs_Col, or 'i' this way:
        cur_fam_graph = family_graphs[[family_graphs_col]][[i]],
        cur_fid = cur_fid,
        h2 = h2,
        useMixture = useMixture,
        pid = pid)

      temp_tbl = ph$tbl
      cov = ph$cov


    } else { # role based covariance construction
      # saving to place holder object
      ph = extract_estimation_info_tbl(
        .tbl = .tbl,
        pid = pid,
        fid = fid,
        cur_fid = cur_fid,
        role = role,
        useMixture = useMixture,
        h2 = h2)
      temp_tbl = ph$tbl
      cov = ph$cov
    }

    ### This section should require a temp_tbl and covmat object from above ###

    # if tbl input is used, the cov matrix has roles as row and column names.

    cur_target_id = case_when(
      !is.null(.tbl) & method == "PA" ~ "g",
      TRUE ~ paste0(cur_fid, "_g")
    )

    # estimation function that takes covariance matrix, thresholds,
    # estimation method, tolerance, out, and estimation specific parameters
    # such as burn_in and return estimates of genetic and/or full liability
    res <- estimation_function(
      tbl = temp_tbl,
      cov = cov,
      out = out,
      tol = tol,
      method = method,
      burn_in = 1000,
      useMixture = useMixture,
      target_id = cur_target_id)


    # formatting and returning result
    if ( !is.null(family_graphs) ) {
      # if graph format is used: pid and fid are the same
      tibble(!!as.symbol(fid) := cur_fid,
             !!as.symbol(pid) := cur_fid) %>%
        bind_cols(res)

    } else {
      tibble(!!as.symbol(fid) := cur_fid,
             # pulling id of proband in the family based on specified role
             !!as.symbol(pid) := filter(.tbl, !!as.symbol(fid) == cur_fid, !!as.symbol(role) == "o") %>% pull(!!as.symbol(pid))) %>%
        bind_cols(res)
    }

  }, future.seed = TRUE) %>%
    do.call("bind_rows", .)

  return(gibbs_res)
}


#' Estimating the genetic or full liability for multiple phenotypes
#'
#' \code{estimate_liability_multi} estimates the genetic component of the full
#' liability and/or the full liability for a number of individuals based
#' on their family history for a variable number of phenotypes.
#'
#' This function can be used to estimate either the genetic component of the
#' full liability, the full liability or both for a variable number of traits.
#'
#' @param .tbl A matrix, list or data frame that can be converted into a tibble.
#' Must have at least seven columns that hold the family identifier, the personal
#' identifier, the role and the lower and upper thresholds for all phenotypes
#' of interest. Note that the role must be one of the following abbreviations
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to \code{NULL}.
#' @param family_graphs A tibble with columns pid and family_graph_col.
#' See prepare_graph for construction of the graphs. The family graphs Defaults to NULL.
#' @param genetic_corrmat A numeric matrix holding the genetic correlations between the desired
#' phenotypes. All diagonal entries must be equal to one, while all off-diagonal entries
#' must be between -1 and 1. In addition, the matrix must be symmetric.
#' @param full_corrmat A numeric matrix holding the full correlations between the desired
#' phenotypes. All diagonal entries must be equal to one, while all off-diagonal entries
#' must be between -1 and 1. In addition, the matrix must be symmetric.
#' @param h2_vec A numeric vector representing the liability-scale heritabilities
#' for all phenotypes. All entries in h2_vec must be non-negative and at most 1.
#' @param phen_names A character vector holding the phenotype names. These names
#' will be used to create the row and column names for the covariance matrix.
#' If it is not specified, the names will default to phenotype1, phenotype2, etc.
#' Defaults to NULL.
#' @param pid A string holding the name of the column in \code{family} and
#' \code{threshs} that hold the personal identifier(s). Defaults to "PID".
#' @param fid A string holding the name of the column in \code{family} that
#' holds the family identifier. Defaults to "fid".
#' @param role A string holding the name of the column in \code{.tbl} that
#' holds the role.Each role must be chosen from the following list of abbreviations
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to "role".
#' @param family_graphs_col Name of column with family graphs in family_graphs. Defaults to "fam_graph".
#' @param out A character or numeric vector indicating whether the genetic component
#' of the full liability, the full liability or both should be returned. If \code{out = c(1)} or
#' \code{out = c("genetic")}, the genetic liability is estimated and returned. If \code{out = c(2)} or
#' \code{out = c("full")}, the full liability is estimated and returned. If \code{out = c(1,2)} or
#' \code{out = c("genetic", "full")}, both components are estimated and returned.
#' Defaults to \code{c(1)}.
#' @param tol A number that is used as the convergence criterion for the Gibbs sampler.
#' Equals the standard error of the mean. That is, a tolerance of 0.2 means that the
#' standard error of the mean is below 0.2. Defaults to 0.01.
#' @param method Estimation method used to estimate the (genetic) liability. Defaults to "PA".
#' Current implementation of PA only supports estimates of genetic liability. For full or both
#' genetic and full liability estimates use "Gibbs".
#' @param target_phenotype With method = PA, which phenotype should be returned?
#' @param useMixture Logical indicating whether the mixture model should be used to calculate the genetic liability.
#'
#' @return If \code{family} and \code{threshs} are two matrices, lists or data frames
#' that can be converted into tibbles, if \code{family} has two columns named like
#' the strings represented in \code{pid} and \code{fid}, if \code{threshs} has a
#' column named like the string given in \code{pid} as well as a column named \code{"lower"}
#' and a column named \code{"upper"} and if the liability-scale heritabilities in \code{h2_vec},
#' \code{genetic_corrmat}, \code{full_corrmat}, \code{out} and \code{tol} are of the
#' required form, then the function returns a tibble with at least six columns (depending
#' on the length of out).
#' The first two columns correspond to the columns \code{fid} and \code{pid} present in
#' the tibble \code{family}.
#' If \code{out} is equal to \code{c(1)} or \code{c("genetic")}, the third and fourth columns
#' hold the estimated genetic liability as well as the corresponding standard error for the
#' first phenotype, respectively.
#' If \code{out} equals \code{c(2)} or \code{c("full")}, the third and fourth columns hold
#' the estimated full liability as well as the corresponding standard error for the first
#' phenotype, respectively.
#' If \code{out} is equal to \code{c(1,2)} or \code{c("genetic","full")}, the third and
#' fourth columns hold the estimated genetic liability as well as the corresponding standard
#' error for the first phenotype, respectively, while the fifth and sixth columns hold the
#' estimated full liability as well as the corresponding standard error for the first
#' phenotype, respectively.
#' The remaining columns hold the estimated genetic liabilities and/or the estimated full
#' liabilities as well as the corresponding standard errors for the remaining phenotypes.
#'
#' @examples
#' genetic_corrmat <- matrix(0.4, 3, 3)
#' diag(genetic_corrmat) <- 1
#' full_corrmat <- matrix(0.6, 3, 3)
#' diag(full_corrmat) <- 1
#' #
#' sims <- simulate_under_LTM(fam_vec = c("m","f"), n_fam = NULL, add_ind = TRUE,
#' genetic_corrmat = genetic_corrmat, full_corrmat = full_corrmat, h2 = rep(.5,3),
#' n_sim = 1, pop_prev = rep(.1,3))
#' estimate_liability_multi(.tbl = sims$thresholds, h2_vec = rep(.5,3),
#' genetic_corrmat = genetic_corrmat, full_corrmat = full_corrmat,
#' pid = "indiv_ID", fid = "fid", role = "role", out = c(1),
#' phen_names = paste0("phenotype", 1:3), target_phenotype = "phenotype1")
#'
#'
#' @seealso \code{\link[future.apply]{future_apply}}, \code{\link{estimate_liability_single}},
#' \code{\link{estimate_liability}}
#'
#' @importFrom dplyr %>% pull bind_rows bind_cols select row_number rename arrange left_join slice tibble
#' @importFrom rlang :=
#' @importFrom stringr str_detect
#' @importFrom tidyselect starts_with
#' @importFrom igraph vertex_attr
#'
#' @export
estimate_liability_multi <- function(.tbl = NULL,
                                     family_graphs = NULL,
                                     h2_vec,
                                     genetic_corrmat,
                                     full_corrmat,
                                     phen_names = NULL,
                                     pid = "pid",
                                     fid = "fid",
                                     role = "role",
                                     family_graphs_col = "fam_graph",
                                     out = c(1),
                                     tol = 0.01,
                                     method = "PA",
                                     useMixture = FALSE,
                                     target_phenotype = NULL){

  # validating input-agnostic variables --------------------------------------

  # validating that target_phenotype is specified when required by PA
  if (method == "PA" && is.null(target_phenotype)) {
    stop("estimate_liability_multi: target_phenotype must be one of the phen_names, but it is currently NULL.")
  }

  # is target_phenotype in phen_names?
  if (method == "PA" & !is.null(target_phenotype) & !is.null(phen_names)) {
    if (!(target_phenotype %in% phen_names)) {
      stop("estimate_liability_multi: target_phenotype must be one of the phen_names!\n")
    }
  }

  # Turning pid, fid into strings
  pid <- as.character(pid)
  fid <- as.character(fid)

  # Checking that the heritability is valid
  if (validate_proportion(h2_vec)) invisible()

  # Checking that all correlations are valid
  if (validate_correlation_matrix(genetic_corrmat)) invisible()
  if (validate_correlation_matrix(full_corrmat)) invisible()

  # Checking that tol is valid
  if (!is.numeric(tol) && !is.integer(tol)) stop("The tolerance must be numeric!")
  if (tol <= 0) stop("The tolerance must be strictly positive!")

  # Checking that out is either a character vector or a numeric vector
  if (is.numeric(out)) {

    out <- intersect(out, c(1,2))

  } else if (is.character(out)) {

    out <- c("genetic", "full")[rowSums(sapply(out, grepl, x = c("genetic", "full"))) > 0]
    out[out == "genetic"] <- 1
    out[out == "full"] <- 2
    out <- as.numeric(out)

  } else {
    stop("out must be a numeric or character vector!")
  }

  # Checking whether out is empty
  if (length(out) == 0) {

    warning("out is not of the required format! \n The function will return the estimated genetic liability!")
    out <- c(1)

  }

  # Sorting out
  out <- sort(out)

  # Now we can extract the number of phenotypes
  n_pheno <- length(h2_vec)


  # Validating input specific variables -------------------------------------

  # only one of .tbl / family_graphs may be given - .tbl silently takes
  # precedence otherwise, so family_graphs would be used for nothing
  if (!is.null(.tbl) && !is.null(family_graphs)) {
    stop("estimate_liability_multi: provide only one of .tbl or family_graphs, ",
         "not both.")
  }

  if ( !is.null(.tbl) ) {  #### .tbl input ####

    .tbl = validate_tbl_input_multi(
      .tbl = .tbl,
      pid = pid,
      fid = fid,
      role = role,
      phen_names = phen_names,
      useMixture = useMixture
    )

    #  Extracting the (unique) family identifiers
    fam_list <- unique(pull(.tbl, !!as.symbol(fid)))

  } else if ( !is.null(family_graphs) ) { #### Graph input ####

    # Validating graph input (nothing is returned)
    NULL_CATCHER = validate_graph_input_multi(
      family_graphs = family_graphs,
      fid = fid,
      family_graphs_col = family_graphs_col,
      phen_names = phen_names,
      useMixture = useMixture
    )

    # Extracting the (unique) family identifiers
    fam_list <- unique(pull(family_graphs, !!as.symbol(fid)))

  } else ( stop("no valid input used.") )

# Starting estimation -----------------------------------------------------

  # how many workers are we using?
  message(paste0("The number of workers is ", future::nbrOfWorkers(), "\n"))

  # actual liability estimates happen below
  gibbs_res <- future.apply::future_lapply(X = 1:length(fam_list), FUN = function(i){

    # current family id (proband id for graphs)
    cur_fid = fam_list[i]

    ##### Ultimately, we get cov and temp_tbl from both of the cases below #####

    if ( !is.null(.tbl) ) { # role based covariance construction
      ph = extract_estimation_info_tbl_multi(
        .tbl = .tbl,
        pid = pid,
        fid = fid,
        cur_fid = cur_fid,
        role = role,
        h2 = h2_vec,
        useMixture = useMixture,
        genetic_corrmat = genetic_corrmat,
        full_corrmat = full_corrmat,
        phen_names = phen_names
      )

      temp_tbl = ph$tbl
      cov = ph$cov

    } else if ( !is.null(family_graphs) ) { # family graph based covariance construction

      ph = extract_estimation_info_graph_multi(
        fid = fid,
        pid = pid,
        cur_fid = cur_fid,
        cur_fam_graph = family_graphs[[family_graphs_col]][[i]],
        h2_vec = h2_vec,
        genetic_corrmat = genetic_corrmat,
        phen_names = phen_names,
        useMixture = useMixture
      )

      temp_tbl = ph$tbl
      cov = ph$cov

    } else { stop("How did you even get here?") }

    ### This section should require a temp_tbl and covmat object from above ###
    # temp_tbl should have a long format that matches the covariance matrix

    # for PA_algorithm: which
    cur_target_id = case_when(
      !is.null(.tbl) & method == "PA" ~ paste0("g_", target_phenotype),
      TRUE ~ paste0(cur_fid, "_g_", target_phenotype)
    )

    # estimation function that takes covariance matrix, thresholds,
    # estimation method, tolerance, out, and estimation specific parameters
    # such as burn_in and return estimates of genetic and/or full liability
    res <- estimation_function(
      tbl = temp_tbl,
      cov = cov,
      out = out,
      tol = tol,
      method = method,
      burn_in = 1000,
      useMixture = useMixture,
      phen_names = phen_names,
      target_id = cur_target_id)


    # if graph format is used: pid and fid are the same
    if ( !is.null(family_graphs) ) {
      # formatting and returning result
      tibble(!!as.symbol(fid) := cur_fid,
             !!as.symbol(pid) := cur_fid) %>%
        bind_cols(res)

    } else {
      # formatting and returning result
      tibble(!!as.symbol(fid) := cur_fid,
             # pulling id of proband in the family based on specified role
             !!as.symbol(pid) := filter(.tbl, !!as.symbol(fid) == cur_fid, !!as.symbol(role) == "o") %>% pull(!!as.symbol(pid))) %>%
        bind_cols(res)
    }

  }, future.seed = TRUE) %>%
    do.call("bind_rows",.)

  return(gibbs_res)
}


#' Estimating the genetic or full liability for a variable number of
#' phenotypes
#'
#' \code{estimate_liability} estimates the genetic component of the full
#' liability and/or the full liability for a number of individuals based
#' on their family history for one or more phenotypes.  It is a wrapper around
#' \code{\link{estimate_liability_single}} and \code{\link{estimate_liability_multi}}.
#'
#' This function can be used to estimate either the genetic component of the
#' full liability, the full liability or both for a variable number of traits.
#'
#' @param .tbl A matrix, list or data frame that can be converted into a tibble.
#' Must have at least five columns that hold the family identifier, the personal
#' identifier, the role and the lower and upper thresholds for all phenotypes
#' of interest. Note that the role must be one of the following abbreviations
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to \code{NULL}.
#' @param family_graphs A tibble with columns pid and family_graph_col.
#' See prepare_graph for construction of the graphs. The family graphs Defaults to NULL.
#' @param h2 Either a number representing the heritability on liability scale for a
#' single phenotype, or a numeric vector representing the liability-scale heritabilities
#' for all phenotypes. All entries in h2 must be non-negative and at most 1.
#' @param  pid A string holding the name of the column in \code{family} and
#' \code{threshs} that hold the personal identifier(s). Defaults to \code{"PID"}.
#' @param fid A string holding the name of the column in \code{family} that
#' holds the family identifier. Defaults to \code{"fid"}.
#' @param role A string holding the name of the column in \code{.tbl} that
#' holds the role.Each role must be chosen from the following list of abbreviations
#' \itemize{
#'  \item \code{g} (Genetic component of full liability)
#'  \item \code{o} (Full liability)
#'  \item \code{m} (Mother)
#'  \item \code{f} (Father)
#'  \item \code{c[0-9]*.[0-9]*} (Children)
#'  \item \code{mgm} (Maternal grandmother)
#'  \item \code{mgf} (Maternal grandfather)
#'  \item \code{pgm} (Paternal grandmother)
#'  \item \code{pgf} (Paternal grandfather)
#'  \item \code{s[0-9]*} (Full siblings)
#'  \item \code{mhs[0-9]*} (Half-siblings - maternal side)
#'  \item \code{phs[0-9]*} (Half-siblings - paternal side)
#'  \item \code{mau[0-9]*} (Aunts/Uncles - maternal side)
#'  \item \code{pau[0-9]*} (Aunts/Uncles - paternal side).
#' }
#' Defaults to "role".
#' @param family_graphs_col Name of column with family graphs in family_graphs. Defaults to "fam_graph".
#' @param out A character or numeric vector indicating whether the genetic component
#' of the full liability, the full liability or both should be returned. If \code{out = c(1)} or
#' \code{out = c("genetic")}, the genetic liability is estimated and returned. If \code{out = c(2)} or
#' \code{out = c("full")}, the full liability is estimated and returned. If \code{out = c(1,2)} or
#' \code{out = c("genetic", "full")}, both components are estimated and returned.
#' Defaults to \code{c(1)}.
#' @param tol A number that is used as the convergence criterion for the Gibbs sampler.
#' Equals the standard error of the mean. That is, a tolerance of 0.2 means that the
#' standard error of the mean is below 0.2. Defaults to 0.01.
#' @param method Estimation method used to estimate the (genetic) liability. Defaults to "PA".
#' Current implementation of PA only supports estimates of genetic liability. For full or both
#' genetic and full liability estimates use "Gibbs".
#' @param genetic_corrmat Either \code{NULL} (if \code{h2} is a number) or a numeric
#' matrix (if \code{h2} is a vector of length > 1) holding the genetic correlations
#' between the desired phenotypes. All diagonal entries must be equal to one, while
#' all off-diagonal entries must be between -1 and 1. In addition, the matrix must
#' be symmetric. Defaults to \code{NULL}.
#' @param full_corrmat Either \code{NULL} (if \code{h2} is a number) or a numeric
#' matrix (if \code{h2} is a vector of length > 1) holding the full correlations
#' between the desired phenotypes. All diagonal entries must be equal to one, while
#' all off-diagonal entries must be between -1 and 1. In addition, the matrix must
#' be symmetric. Defaults to \code{NULL}.
#' @param phen_names Either \code{NULL} or a character vector holding the phenotype
#' names. These names will be used to create the row and column names for the
#' covariance matrix. If it is not specified, the names will default to
#' phenotype1, phenotype2, etc. Defaults to NULL.
#' @param useMixture Logical indicating whether the mixture model should be used to calculate the genetic liability.
#' Requires K_i and K_pop columns as well as lower and upper. Defaults to FALSE.
#' @param target_phenotype With method = PA, which phenotype should be returned?
#'
#' @return If \code{family} and \code{threshs} are two matrices, lists or
#' data frames that can be converted into tibbles, if \code{family} has two
#' columns named like the strings represented in \code{pid} and \code{fid}, if
#' \code{threshs} has a column named like the string given in \code{pid} as
#' well as a column named "lower" and a column named "upper" and if the
#' liability-scale heritability \code{h2} is a number (\code{length(h2)=1}),
#' and \code{out}, \code{tol} and
#' \code{always_add} are of the required form, then the function returns a
#' tibble with either four or six columns (depending on the length of out).
#' The first two columns correspond to the columns \code{fid} and \code{pid} '
#' present in \code{family}.
#' If \code{out} is equal to \code{c(1)} or \code{c("genetic")}, the third
#' and fourth column hold the estimated genetic liability as well as the
#' corresponding standard error, respectively.
#' If \code{out} equals \code{c(2)} or \code{c("full")}, the third and
#' fourth column hold the estimated full liability as well as the
#' corresponding standard error, respectively.
#' If \code{out} is equal to \code{c(1,2)} or \code{c("genetic","full")},
#' the third and fourth column hold the estimated genetic liability as
#' well as the corresponding standard error, respectively, while the fifth and
#' sixth column hold the estimated full liability as well as the corresponding
#' standard error, respectively.
#' If \code{h2} is a numeric vector of length greater than 1 and if
#' \code{genetic_corrmat}, \code{full_corrmat}, \code{out} and \code{tol} are of the
#' required form, then the function returns a tibble with at least six columns (depending
#' on the length of out).
#' The first two columns correspond to the columns \code{fid} and \code{pid} present in
#' the tibble \code{family}.
#' If \code{out} is equal to \code{c(1)} or \code{c("genetic")}, the third and fourth columns
#' hold the estimated genetic liability as well as the corresponding standard error for the
#' first phenotype, respectively.
#' If \code{out} equals \code{c(2)} or \code{c("full")}, the third and fourth columns hold
#' the estimated full liability as well as the corresponding standard error for the first
#' phenotype, respectively.
#' If \code{out} is equal to \code{c(1,2)} or \code{c("genetic","full")}, the third and
#' fourth columns hold the estimated genetic liability as well as the corresponding standard
#' error for the first phenotype, respectively, while the fifth and sixth columns hold the
#' estimated full liability as well as the corresponding standard error for the first
#' phenotype, respectively.
#' The remaining columns hold the estimated genetic liabilities and/or the estimated full
#' liabilities as well as the corresponding standard errors for the remaining phenotypes.
#'
#' @examples
#' genetic_corrmat <- matrix(0.4, 3, 3)
#' diag(genetic_corrmat) <- 1
#' full_corrmat <- matrix(0.6, 3, 3)
#' diag(full_corrmat) <- 1
#' #
#' sims <- simulate_under_LTM(fam_vec = c("m","f"), n_fam = NULL, add_ind = TRUE,
#' genetic_corrmat = genetic_corrmat, full_corrmat = full_corrmat, h2 = rep(.5,3),
#' n_sim = 1, pop_prev = rep(.1,3))
#' estimate_liability(.tbl = sims$thresholds, h2 = rep(.5,3),
#' genetic_corrmat = genetic_corrmat, full_corrmat = full_corrmat,
#' pid = "indiv_ID", fid = "fid", role = "role", out = c(1),
#' phen_names = paste0("phenotype", 1:3), target_phenotype = "phenotype1")
#'
#' @seealso \code{\link[future.apply]{future_apply}}, \code{\link{estimate_liability_single}},
#' \code{\link{estimate_liability_multi}}
#'
#' @importFrom dplyr %>% pull bind_rows bind_cols select row_number rename
#' @importFrom rlang :=
#'
#' @export
estimate_liability <- function(.tbl = NULL,
                               family_graphs = NULL,
                               h2 = 0.5,
                               pid = "pid",
                               fid = "fid",
                               role = "role",
                               family_graphs_col = "fam_graph",
                               out = c(1),
                               tol = 0.01,
                               method = "PA",
                               useMixture = FALSE,
                               genetic_corrmat = NULL,
                               full_corrmat = NULL,
                               phen_names = NULL,
                               target_phenotype = NULL){
  if (method != "PA" & useMixture ) {
    stop("Only PA supports Mixture calculations at the moment!")
  }

  if (length(h2) == 1) {

    return(estimate_liability_single(.tbl = .tbl,
                                     family_graphs = family_graphs,
                                     h2 = h2,
                                     pid = pid,
                                     fid = fid,
                                     role = role,
                                     family_graphs_col = family_graphs_col,
                                     out = out,
                                     method = method,
                                     useMixture = useMixture,
                                     tol = tol))

  } else {

    return(estimate_liability_multi(.tbl = .tbl,
                                    family_graphs = family_graphs,
                                    h2_vec = h2,
                                    genetic_corrmat = genetic_corrmat,
                                    full_corrmat = full_corrmat,
                                    phen_names = phen_names,
                                    target_phenotype = target_phenotype,
                                    pid = pid,
                                    fid = fid,
                                    role = role,
                                    family_graphs_col = family_graphs_col,
                                    out = out,
                                    method = method,
                                    useMixture = useMixture,
                                    tol = tol))
  }
}


# Estimation method dispatcher, used internally by estimate_liability_single()
# and estimate_liability_multi() to select between the Gibbs and PA
# estimation methods. -------------------------------------------------------

utils::globalVariables(c("K_i", "K_pop"))

# estimation function that takes covariance matrix, thresholds, estimation method, tolerance, out, and estimation specific parameters such as burn_in and return estimates of genetic and/or full liability

estimation_function = function(tbl, cov,
                               out = NA,
                               tol = 0.01,
                               method = NA,
                               burn_in = NA,
                               phen_names = NULL,
                               useMixture = FALSE,
                               target_id = NA) {
  if (is.na(method)) {
    stop("Please specify the estimation method.")
  }

  if (method == "Gibbs") {
    res <- Gibbs_estimator(cov = cov, tbl = tbl, out = out, tol = tol, burn_in = burn_in, phen_names = phen_names)
  }

  if (method == "PA") {
    if (useMixture) {
      # note: if useMixture is TRUE, K_i and K_pop are expected to be in tbl as columns.
      res <- PA_algorithm(
        mu = rep(0, nrow(cov)),
        covmat = cov,
        lower = pull(tbl, lower),
        upper = pull(tbl, upper),
        K_i = pull(tbl, K_i),
        K_pop = pull(tbl, K_pop),
        target_id = target_id)
    } else {
      res <- PA_algorithm(
        mu = rep(0, nrow(cov)),
        covmat = cov,
        lower = pull(tbl, lower),
        upper = pull(tbl, upper),
        K_i = rep(NA, nrow(tbl)),
        K_pop = rep(NA, nrow(tbl)),
        target_id = target_id)
    }

  }
  return(res)
}


#' Wrapper around the Gibbs Sampler that returns formatted liability estimates for the proband
#'
#' @param cov Covariance (kinship matrix times heritability with corrected diagonal) matrix
#' @param tbl Tibble with lower and upper bounds for the Gibbs sampler
#' @param out Vector indicating if genetic ans/or full liabilities should be estimated
#' @param tol Convergence criteria, tolerance
#' @param burn_in Number of burn-in iterations
#' @param phen_names Names of the phenotypes being analyzed
#'
#' @returns Formatted liability estimate(s) and standard error(s) of the mean for the proband.
#' @export
#'
#' @importFrom dplyr pull
#' @examples
#' # uninformative sampling:
#' Gibbs_estimator(cov = diag(3), tbl = tibble::tibble(lower = rep(-Inf, 3),
#' upper = rep(Inf, 3)), out = 1:2, tol = 0.01, burn_in = 1000)
Gibbs_estimator = function(cov, tbl, out, tol = 0.01, burn_in = 1000, phen_names = NULL) {

  # if phen_names are provided, then return out values for each phenotype
  if (!is.null(phen_names)) {
    # previously `which(str_detect(colnames(cov), "g_"))`, which always
    # selected every phenotype's genetic-liability column regardless of
    # `out` - requesting out = 2 ("full") silently returned genetic
    # liability mislabeled as "full", and out = c(1,2) crashed, since
    # `updated_out` (length = n phenotypes) and `return_names` below
    # (length = n phenotypes * length(out)) disagreed.
    #
    # Fixed by position rather than by name: both construct_covmat_multi()
    # (.tbl path) and graph_based_covariance_construction_multi() (graph
    # path) guarantee genetic liability is the 1st and full liability the
    # 2nd entry of each phenotype's block in cov, but they name those
    # columns differently ("g_<phen>"/"o_<phen>" vs.
    # "<id>_g_<phen>"/"<id>_<phen>"), so matching by name only worked for
    # one of the two paths.
    if (ncol(cov) %% length(phen_names) != 0) {
      stop("Gibbs_estimator: cov's dimension (", ncol(cov), ") is not evenly ",
          "divisible by the number of phenotypes (", length(phen_names), "); ",
          "cannot assume a uniform per-phenotype block size.")
    }
    fam_size = ncol(cov) / length(phen_names)
    block_offsets = (seq_along(phen_names) - 1) * fam_size
    updated_out = as.vector(outer(out, block_offsets, "+"))
  } else { # otherwise the specified out values
    updated_out = out
  }

  # Setting the variables needed for Gibbs sampler
  fixed <- (pull(tbl,upper) - pull(tbl,lower)) < 1e-04
  std_err <- rep(Inf, length(updated_out))
#  names(std_err) <- c("genetic", "full")[out]
  n_gibbs <- 1


  # return names
  if (is.null(phen_names)) {
    return_names = c("genetic", "full")[out]
  } else {
    return_names = paste0(rep(c("genetic", "full")[out], length(phen_names)),"_", rep(phen_names, each = length(out)))
  }
  # Running Gibbs sampler
  while (any(std_err > tol)) {

    if (n_gibbs == 1) {

      est_liabs <- rtmvnorm.gibbs(n_sim = 1e+05, covmat = cov, lower = pull(tbl, lower), upper = pull(tbl, upper),
                                  fixed = fixed, out = updated_out, burn_in = burn_in) %>%
        `colnames<-`(return_names) %>%
        tibble::as_tibble()

    } else {

      est_liabs <- rtmvnorm.gibbs(n_sim = 1e+05, covmat = cov, lower = pull(tbl, lower), upper = pull(tbl, upper),
                                  fixed = fixed, out = updated_out, burn_in = burn_in) %>%
        `colnames<-`(return_names) %>%
        tibble::as_tibble() %>%
        bind_rows(est_liabs)
    }

    # Computing the standard error
    std_err <- batchmeans::bmmat(est_liabs)[,2]
    # Adding one to the counter
    n_gibbs <- n_gibbs + 1
  }

  # If all standard errors are below the tolerance,
  # the estimated liabilities as well as the corresponding
  # standard error can be returned
  res <- tibble::as_tibble(batchmeans::bmmat(est_liabs), rownames = "out") %>%
    tidyr::pivot_longer(., cols = c(est,se)) %>%
    mutate(name = paste0(out, "_", name), .keep = "unused") %>%
    tidyr::pivot_wider()
  return(res)
}

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.