# Maximum A Posteriori estimation `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. ```r 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 . ## Returns `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. ## 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. ## 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. 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)**. 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. 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. ## Author(s) Hassan Pazira and Marianne Jonker Maintainer: Hassan Pazira hassan.pazira@radboudumc.nl ## See Also `bfi`, `inv.prior.cov` and `summary.bfi` ## Examples ```r ###--------------### ### 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) ```

MAP.estimation function