Nothing
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)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.