MAP.estimation: Maximum A Posteriori estimation

In BFI: Bayesian Federated Inference

Maximum A Posteriori estimation

Description

MAP.estimation function is used (in local centers) to compute Maximum A Posterior (MAP) estimators of the parameters for Generalized Linear Models (GLM) and Survival models.

Usage

MAP.estimation(y,
               X,
               family = c("gaussian", "binomial", "survival"),
               Lambda,
               intercept = TRUE,
               basehaz = c("weibul", "exp", "gomp", "poly", "pwexp", "unspecified"),
               treatment = NULL,
               treat_round = NULL,
               refer_treat,
               gamma_bfi = NULL,
               RCT_propens = NULL,
               initial = NULL,
               alpha = 0.1,
               max_order = 2,
               n_intervals = 4,
               min_max_times,
               center_zero_sample = FALSE,
               zero_sample_cov,
               refer_cat,
               zero_cat,
               control = list())

Arguments

y	response vector. If the “binomial” family is used, this argument is a vector with entries 0 (failure) or 1 (success). Alternatively, for this family, the response can be a matrix where the first column is the number of “successes” and the second column is the number of “failures”. For the “survival” family, the response is a matrix where the first column is the survival time, named “time”, and the second column is the censoring indicator, named “status”, with 0 indicating censoring time and 1 indicating event time.
X	design matrix of dimension n_{\ell} \times p, where p is the number of covariates or predictors and n_{\ell} is the number of indeviduals in the local center. If there is a categorical covariate, then the function factor() should be used to encode the covariate as a factor. Note that the order of the covariates must be the same across the centers; otherwise, the output estimates of bfi() will be incorrect.
family	a description of the error distribution. This is a character string naming a family of the model. In the current version of the package, the family of model can be “gaussian” (with identity link function), “binomial” (with logit link function), or “survival”. Can be abbreviated. By default the “gaussian” family is used. In case of a linear regression model, family = "gaussian", there is an extra model parameter for the variance of measurement error. While in the case of survival model, family = "survival", the number of the model parameters depend on the choice of baseline hazard functions, see ‘Details’ for more information.
Lambda	the inverse variance-covariance matrix of the Gaussian distribution that is used as prior distribution for the model parameters. The dimension of the matrix depends on the number of columns of X, type of the covariates (continuous / dichotomous or categorical), family, and whether an intercept is included (if applicable). However, Lambda can be easily created by inv.prior.cov(). See inv.prior.cov for more information.
intercept	logical flag for fitting an intercept. If intercept=TRUE (the default), the intercept is fitted, i.e., it is included in the model, and if intercept = FALSE it is set to zero, i.e., it's not in the model. This argument is not used if family = "survival".
basehaz	a character string representing one of the available baseline hazard functions; exponential (“exp”), Weibull (“weibul”, the default), Gompertz (“gomp”), exponentiated polynomial (“poly”), piecewise constant exponential (“pwexp”), and unspecified baseline hazard (“unspecified”). Can be abbreviated. It is used only when family = "survival". If local sample size is large and the shape of the baseline hazard function is completely unknown, the “exponentiated polynomial” and “piecewise exponential” hazard functions would be preferred above the lower dimensional alternatives. However, if the local samples size is low, one should be careful using the “piecewise exponential” hazard function with many intervals. If basehaz = "unspecified", it means that a (semi-parametric) Cox model is considered, and the parameters (regression coefficients) are estimated using the partial log-likelihood. If treatment is not NULL, then basehaz must be set to "unspecified", as the regression coefficients are estimated using the weighted partial log-likelihood.
treatment	a character string representing the name or place of the binary covariate, respectively. This covariate indicates whether the patient got the new treatment (z_{\ell i}=1) or the placebo/standard treatment (z_{\ell i}=0). The treatment effect is estimated when this argument is NOT 'NULL'. If it is set to 'NULL' (the default), the treatment effect will not be estimated. For both the first and second rounds, it should not be 'NULL'. See ‘Details’.
treat_round	a character string representing the 'first' or 'second' round of estimating treatment effects. In the first round, treat_round = 'first', the local estimates of the coefficients (\gamma_{\ell}) is estimated. In the second round, treat_round = 'second', the treatment effect, propensity scores and the statistical summaries (for_ATE, only for 'binomial' and 'gaussian' families) are calculated to be sent to the central server for estimating the BFI treatment effect (\hat \zeta_{BFI}) and average treatment effects (ATEs).
refer_treat	a character string representing the reference category of the treatment variable. The reference category is considered as z_{\ell i}=0. This argument is used when treatment is not 'NULL'. Default is refer_treat = levels(X$treatment)[1].
gamma_bfi	a vector specifying the BFI estimates of the coefficients received from the central server in the first round. It can be defined by the output of MAP.estimation()$theta_hat obtained from the first round. The length of gamma_bfi equals the number of regression coefficients, including the intercept if intercept=TRUE, but excluding \zeta, which represents the treatment effect, as well as the nuisance parameter \sigma in the gaussian family and any parameters of the baseline hazard (\boldsymbol{\omega}) for survival. This argument is used only when the argument treatment is not 'NULL'. If treatment is not 'NULL' but gamma_bfi = NULL, then the argument RCT_propens must not be 'NULL', indicating an RCT study. See ‘Details’.
RCT_propens	a vector specifying the propensity scores, which represent the probability of receiving the treatment given the covariates, which are known in the randomized studies (RCTs). For example, in a 1:1 randomized trial, the propensity scores are, by definition, equal to 1/2 (or 0.5), whereas in an unbalanced randomized trial, e.g., a 2:1 trial, the propensity scores are now 2/3 and 1/3 for the two arms, respectively. The length of RCT_propens equals to the number of individuals in the local center denoted as n_{\ell}. This argument is used only when the study is a randomized control trial, i.e., the propensity scores are known for this local center. In this case, there is only ‘one’ round, and the argument treatment must not be 'NULL', whereas gamma_bfi = NULL. Indeed, when 'treatment' is not 'NULL', one of the arguments 'RCT_propens' or 'gamma_bfi' could be 'NULL'. See ‘Details’.
initial	a vector specifying initial values for the parameters to be optimized over. The length of initial is equal to the number of model parameters and thus, is equal to the number of rows or columns of Lambda. Since the 'L-BFGS-B' method is used in the algorithm, these values should always be finite. Default is a vector of zeros, except for the survival family with the poly function, where it is a vector with the first p elements as zeros for coefficients (\boldsymbol{\beta}) and -0.5 for the remaining parameters (\boldsymbol{\omega}). For the gaussian family, the last element of the initial vector could also be considered negative, because the Gaussian prior was applied to log(\sigma^2).
alpha	a significance level used in the chi-squared distribution (with one degree of freedom and 1-\alpha representing the upper quantile) to conduct a likelihood ratio test for obtaining the order of the exponentiated polynomial baseline hazard function. It is only used when family = "survival" and basehaz = "poly". Default is 0.1. See ‘Details’.
max_order	an integer representing the maximum value of q_l, which is the order/degree minus 1 of the exponentiated polynomial baseline hazard function. This argument is only used when family = "survival" and basehaz = "poly". Default is 2.
n_intervals	an integer representing the number of intervals in the piecewise exponential baseline hazard function. This argument is only used when family = "survival" and basehaz = "pwexp". Default is 4.
min_max_times	a scalar representing the minimum of the maximum event times observed in the centers. The value of this argument should be defined by the central server (which has access to the maximum event times of all the centers) and is only used when family = "survival" and basehaz = "pwexp".
center_zero_sample	logical flag indicating whether the center has a categorical covariate with no observations/individuals in one of the categories. Default is center_zero_sample = FALSE.
zero_sample_cov	either a character string or an integer representing the categorical covariate that has no samples/observations in one of its categories. This covariate should have at least two categories, one of which is the reference. It is used when center_zero_sample = TRUE.
refer_cat	a character string representing the reference category. The category with no observations (the argument zero_cat) cannot be used as the reference in the argument refer_cat. It is used when center_zero_sample = TRUE.
zero_cat	a character string representing the category with no samples/observations. It is used when center_zero_sample = TRUE.
control	a list of control parameters. See ‘Details’.

Details

MAP.estimation function finds the Maximum A Posteriori (MAP) estimates of the model parameters by maximizing the log-posterior density with respect to the parameters, i.e., the estimates equal the values for which the log-posterior density is maximal (the posterior mode). In other words, MAP.estimation() optimizes the log-posterior density with respect to the parameter vector to obtain its MAP estimates. In addition to the model parameters (i.e., coefficients (\boldsymbol{\beta}) and variance error (\sigma^2_e) for gaussian or the parameters of the baseline hazard (\boldsymbol{\omega}) for survival), the curvature matrix (Hessian of the log-posterior) is estimated around the mode.

The MAP.estimation function returns an object of class 'bfi'. Therefore, summary() can be used for the object returned by MAP.estimation().

For the case where family = "survival" and basehaz = "poly", we assume that in all centers the q_\ell's are equal. However, the order of the estimated polynomials may vary across the centers so that each center can have different number of parameters, say q_\ell+1. After obtaining the estimates within the local centers (by using MAP.estimation()) and having all estimates in the central server, we choose the order of the polynomial approximation for the combined data to be the maximum of the orders of the local polynomial functions, i.e., \max \{q_1, \ldots, q_L \}, to approximate the global baseline hazard (exponentiated polynomial) function more accurately. This is because the higher-order polynomial approximation can capture more complex features and details in the combined data. Using the higher-order approximation ensures that we account for the higher-order moments and features present in the data while maintaining accuracy. As a result, all potential cases are stored in the theta_A_poly argument to be used in bfi() by the central server. For further information on the survival family, refer to the 'References' section.

The three arguments 'treatment', 'treat_round', 'refer_treat', 'gamma_bfi', and 'RCT_propens' are related to the estimation of the treatment effect. For observational and non-randomized studies, the treatment effect is estimated in two rounds; In the first round, \hat{\boldsymbol{\beta}}_{\ell} (or \hat{\boldsymbol{\gamma}}_{\ell}) are estimated locally and in the central server \hat{\boldsymbol{\beta}}_{BFI} (or \hat{\boldsymbol{\gamma}}_{BFI}) is estimated and then is sent to all local centers for the second round to estimate propensity scores, weights, treatment effect and ATEs. In the first round, the argument treatment should not be 'NULL' and treat_round = "first", while gamma_bfi = NULL and RCT_propens = NULL. Moreover, in the first round, the family must be set to binomial, however this is handled automatically. In the second round, local weighted MAP estimate of the treatment effects and propensity scores are estimated, and along with some summary statistics are sent to the central server to estimate the average treatment effects ATEs (in this case treatment and gamma_bfi should not be 'NULL' and treat_round = "second", but RCT_propens = NULL). In contrast, for the randomized control trial (RCT), the treatment effect can be estimated by only one round as the propensity scores are known (in this case treatment and RCT_propens should not be 'NULL', but gamma_bfi = NULL). NOTE: the argument gamma_bfi should not include estimates of the nuisance parameter \sigma in the gaussian family or any parameters of the baseline hazard (\boldsymbol{\omega}) and the intercept for survival. For more examples on treatment effect estimation, see the ‘Examples’ section of bfi.

To solve unconstrained and bound-constrained optimization problems, the MAP.estimation function utilizes an optimization algorithm called Limited-memory Broyden-Fletcher-Goldfarb-Shanno with Bound Constraints (L-BFGS-B), Byrd et. al. (1995). The L-BFGS-B algorithm is a limited-memory “quasi-Newton” method that iteratively updates the parameter estimates by approximating the inverse Hessian matrix using gradient information from the history of previous iterations. This approach allows the algorithm to approximate the curvature of the posterior distribution and efficiently search for the optimal solution, which makes it computationally efficient for problems with a large number of variables.

By default, the algorithm uses a relative change in the objective function as the convergence criterion. When the change in the objective function between iterations falls below a certain threshold ('factr') the algorithm is considered to have converged. The convergence can be checked with the argument convergence in the output. See ‘Value’.

In case of convergence issue, it may be necessary to investigate and adjust optimization parameters to facilitate convergence. It can be done using the initial and control arguments. By the argument initial the initial points of the interative optimization algorithm can be changed, and the argument control is a list that can supply any of the following components:

maxit:

is the maximum number of iterations. Default is 150;

factr:

controls the convergence of the 'L-BFGS-B' method. Convergence occurs when the reduction in the objective is within this factor of the machine tolerance. Default for factr is 1e7, which gives a tolerance of about 1e-9. The exact tolerance can be checked by multiplying this value by .Machine$double.eps;

pgtol:

helps to control the convergence of the 'L-BFGS-B' method. It is a tolerance on the projected gradient in the current search direction, i.e., the iteration will stop when the maximum component of the projected gradient is less than or equal to pgtol, where pgtol\geq 0. Default is zero, when the check is suppressed;

trace:

is a non-negative integer. If positive, tracing information on the progress of the optimization is produced. Higher values may produce more tracing information: for the method 'L-BFGS-B' there are six levels of tracing. To understand exactly what these do see the source code of optim function in the stats package;

REPORT:

is the frequency of reports for the 'L-BFGS-B' method if 'control$trace' is positive. Default is every 10 iterations;

lmm:

is an integer giving the number of BFGS updates retained in the 'L-BFGS-B' method. Default is 5.

Value

MAP.estimation returns a list containing the following components:

theta_hat	the vector corresponding to the maximum a posteriori (MAP) estimates of the parameters. For the gaussian family, although a Gaussian prior was applied to \log(\sigma^2), the last element of this vector was back-transformed to \sigma^2. When treatment is not NULL and treat_round = 'first', this is the MAP estimates of only regression coefficients (\boldsymbol{\gamma}_\ell) except the treatment effect \zeta_\ell. While treatment is not NULL and treat_round = 'second', this is \hat{\zeta}_\ell, the weighted MAP estimate of the treatment effect \zeta_\ell in center \ell;
A_hat	minus the curvature (or Hessian) matrix around the point theta_hat. The dimension of the matrix is the same as the argument Lambda;
sd	the vector of (posterior) standard deviation of the MAP estimates in theta_hat, that is sqrt(diag(solve(A_hat)));
Lambda	the inverse variance-covariance matrix of the Gaussian distribution that is used as prior distribution for the parameters. It's exactly the same as the argument Lambda;
formula	the formula applied;
names	the names of the model parameters;
n	sample size, n_{\ell};
np	the number of coefficients;
q_l	the order/degree minus 1 of the exponentiated polynomial baseline hazard function determined for the current center by the likelihood ratio test. This output argument, q_l, is only shown when family = "survival" and basehaz = "poly", and will be used in the function bfi();
theta_A_poly	an array where the first component is a matrix with columns representing the MAP estimates of the parameters for different q_l's, i.e., q_l, q_l+1, ..., max_order. The other components are minus the curvature matrices for different q_l's, i.e., q_l, q_l+1, ..., max_order. Therefore, the first non-NA curvature matrix is equal to the output argument A_hat. This output argument, theta_A_poly, is only shown if family = "survival" and basehaz = "poly", and will be used in the function bfi();
lev_no_ref_zer	a vector containing the names of the levels of the categorical covariate that has no samples/observations in one of its categories. The name of the category with no samples and the name of the reference category are excluded from this vector. This argument is shown when family = "survival" and basehaz = "poly", and will be used in the function bfi();
treatment	a character string representing the name or place of the binary covariate, respectively. If it is set to 'NULL', the treatment effect will not be estimated;
refer_treat	the reference category of the treatment. It is shown when treatment is not 'NULL', and can be used in the function bfi();
gamma_bfi	a vector specifying the BFI estimates of the coefficients received from the central server in the first round. If treatment = NULL, then gamma_bfi must also be 'NULL';
RCT_propens	a vector specifying the propensity scores, which represent the probability of receiving the treatment given the covariates, which are known in the randomized studies (RCTs). If treatment = NULL, then RCT_propens must also be 'NULL';
propensity	a vector specifying the propensity scores (the probability a patient gets the treatment given the characteristics measured at baseline) calculated by Pr(Z_\ell = 1 | X_\ell);
for_ATE	a vector used in the central server to calculate the average treatment effect (ATE). For family of binomial and gaussian, its elements are: first m_{\ell 1}, the number of patients in the treatment group, where n_{\ell} = m_{\ell 1} + m_{\ell 2}, second m_{\ell 2}, the number of patients in the reference group, where m_{\ell 2} = n_{\ell} - m_{\ell 1}, third \sum_{i=1}^{n_{\ell}} z_{\ell i} y_{\ell i}, fourth \sum_{i=1}^{n_{\ell}} (z_{\ell i} y_{\ell i})^{2} , fifth \sum_{i=1}^{n_{\ell}} z_{\ell i} / e_{\ell i}, sixth \sum_{i=1}^{n_{\ell}} z_{\ell i} y_{\ell i} / e_{\ell i}, seventh \sum_{i=1}^{n_{\ell}} (1 - z_{\ell i}) / (1 - e_{\ell i}), eighth \sum_{i=1}^{n_{\ell}} (1 - z_{\ell i}) y_{\ell i} / (1 - e_{\ell i}), ninth \sum_{i=1}^{n_{\ell}} (1 - z_{\ell i}) y_{\ell i}, but for survival, it's 'NULL';
zero_sample_cov	the categorical covariate that has no samples/observations in one of its categories. It is shown when center_zero_sample = TRUE, and can be used in the function bfi();
refer_cat	the reference category. It is shown when center_zero_sample = TRUE, and can be used in the function bfi();
zero_cat	the category with no samples/observations. It is shown when center_zero_sample = TRUE, and can be used in the function bfi();
value	the value of minus the log-likelihood posterior density evaluated at theta_hat;
family	the family used;
basehaz	the baseline hazard function used;
intercept	logical flag used to fit an intercept if TRUE, or set to zero if FALSE;
convergence	an integer value used to encode the warnings and the errors related to the algorithm used to fit the model. The values returned are: 0 algorithm has converged, 1 maximum number of iterations ('maxit') has been reached, 2 Warning from the 'L-BFGS-B' method. See the message after this value;
control	the list of control parameters used to compute the MAP estimates.

Author(s)

Hassan Pazira and Marianne Jonker
Maintainer: Hassan Pazira [e-mail]

References

Jonker M.A., Pazira H. and Coolen A.C.C. (2024). Bayesian federated inference for estimating statistical models based on non-shared multicenter data sets, Statistics in Medicine, 43(12): 2421-2438. <https://doi.org/10.1002/sim.10072>

Pazira H., Massa E., Weijers J.A.M., Coolen A.C.C. and Jonker M.A. (2025b). Bayesian Federated Inference for Survival Models, Journal of Applied Statistics (Accepted). <https://arxiv.org/abs/2404.17464>

Jonker M.A., Pazira H. and Coolen A.C.C. (2025a). Bayesian Federated Inference for regression models based on non-shared medical center data, Research Synthesis Methods, 1-41. <https://doi.org/10.1017/rsm.2025.6>

Byrd R.H., Lu P., Nocedal J. and Zhu C. (1995). A limited memory algorithm for bound constrained optimization. SIAM Journal on Scientific Computing, 16, 1190-1208. <https://doi.org/10.1137/0916069>

See Also

bfi, inv.prior.cov and summary.bfi

Examples

###--------------###
### y ~ Gaussian ###
###--------------###

# Setting a seed for reproducibility
set.seed(11235)

# model parameters: coefficients and sigma2 = 1.5
theta <- c(1, 2, 2, 2, 1.5)

#----------------
# Data Simulation
#----------------
n   <- 30   # sample size
p   <- 3    # number of coefficients without intercept
X   <- data.frame(matrix(rnorm(n * p), n, p)) # continuous variables
# linear predictor:
eta <- theta[1] + theta[2] * X$X1 + theta[3] * X$X2 + theta[4] * X$X3
# inverse of the link function ( g^{-1}(\eta) = \mu ):
mu  <- gaussian()$linkinv(eta)
y   <- rnorm(n, mu, sd = sqrt(theta[5]))

# Load the BFI package
library(BFI)

#-----------------------------------------------
# MAP estimations for theta and curvature matrix
#-----------------------------------------------
# MAP estimates with 'intercept'
Lambda <- inv.prior.cov(X, lambda = c(0.1, 1), family = "gaussian")
(fit <- MAP.estimation(y, X, family = "gaussian", Lambda))
class(fit)
summary(fit, cur_mat = TRUE)

# MAP estimates without 'intercept'
Lambda <- inv.prior.cov(X, lambda = c(0.1, 1), family = 'gaussian',
                        intercept = FALSE)
(fit1 <- MAP.estimation(y, X, family = 'gaussian', Lambda, intercept = FALSE))
summary(fit1, cur_mat = TRUE)



###-----------------###
### Survival family ###
###-----------------###

# Setting a seed for reproducibility
set.seed(112358)

#-------------------------
# Simulating Survival data
#-------------------------
n    <- 50
beta <- 1:4
p    <- length(beta)
X    <- data.frame(matrix(rnorm(n * p), n, p)) # continuous (normal) variables

## Simulating survival data from Weibull with a predefined censoring rate of 0.3
y <- surv.simulate(Z = list(X), beta = beta, a = 5, b = exp(1.8), u1 = 0.1,
                   cen_rate = 0.3, gen_data_from = "weibul")$D[[1]][, 1:2]

#---------------------------------------
# MAP estimations with "weibul" function
#---------------------------------------
Lambda <- inv.prior.cov(X, lambda = c(0.1, 1), family = 'survival',
                        basehaz = "weibul")
fit2 <- MAP.estimation(y, X, family = 'survival', Lambda = Lambda,
                       basehaz = "weibul")
fit2
summary(fit2, cur_mat = TRUE)

#-------------------------------------
# MAP estimations with "poly" function
#-------------------------------------
Lambda <- inv.prior.cov(X, lambda = c(0.1, 1), family = 'survival',
                        basehaz = 'poly')
fit3 <- MAP.estimation(y, X, family = "survival", Lambda = Lambda,
                       basehaz = "poly")
# Degree of the exponentiated polynomial baseline hazard
fit3$q_l + 1
# theta_hat for (beta_1, ..., beta_p, omega_0, ..., omega_{q_l})
fit3$theta_A_poly[,,1][,fit3$q_l+1] # equal to fit3$theta_hat
# A_hat
fit3$theta_A_poly[,,fit3$q_l+2] # equal to fit3$A_hat
summary(fit3, cur_mat = TRUE)

#------------------------------------------------------
# MAP estimations with "pwexp" function with 3 intervals
#-------------------------------------------------------
# Assume we have 4 centers
Lambda <- inv.prior.cov(X, lambda = c(0.1, 1), family = 'survival',
                        basehaz = 'pwexp', n_intervals = 3)
# For this baseline hazard ("pwexp"), we need to know
# maximum survival times of the 3 other centers:
max_times <- c(max(rexp(30)), max(rexp(50)), max(rexp(70)))
# Minimum of the maximum values of the survival times of all 4 centers is:
min_max_times <- min(max(y$time), max_times)
fit4 <- MAP.estimation(y, X, family = "survival", Lambda = Lambda,
                       basehaz = "pwexp", n_intervals = 3,
                       min_max_times=max(y$time))
summary(fit4, cur_mat = TRUE)


#--------------------------
# Semi-parametric Cox model
#--------------------------
Lambda <- inv.prior.cov(X, lambda = c(0.1), family = 'survival',
                        basehaz = "unspecified")
fit5 <- MAP.estimation(y, X, family = 'survival', Lambda = Lambda,
                       basehaz = "unspecified")
summary(fit5, cur_mat = TRUE)

BFI documentation built on June 8, 2025, 12:41 p.m.