Summarize a fitted model in a table.

```
hbl_summary(
mcmc,
data,
response = "response",
response_type = "raw",
study = "study",
study_reference = max(data[[study]]),
group = "group",
group_reference = min(data[[group]]),
patient = "patient",
rep = "rep",
rep_reference = min(data[[rep]]),
covariates = grep("^covariate", colnames(data), value = TRUE),
constraint = FALSE,
eoi = 0,
direction = "<"
)
```

- mcmc
A wide data frame of posterior samples returned by

`hbl_mcmc_hierarchical()`

or similar MCMC function.- data
Tidy data frame with one row per patient per rep, indicator columns for the response variable, study, group, patient, rep, and covariates. All columns must be atomic vectors (e.g. not lists).

- response
Character of length 1, name of the column in

`data`

with the response/outcome variable.`data[[response]]`

must be a continuous variable, and it*should*be the change from baseline of a clinical endpoint of interest, as opposed to just the raw response. Treatment differences are computed directly from this scale, please supply change from baseline unless you are absolutely certain that treatment differences computed directly from this quantity are clinically meaningful.- response_type
Character of length 1:

`"raw"`

if the response column in the data is the raw response,`"change"`

if the response columns is change from baseline. In the latter case, the`change_*`

columns in the output table are omitted because the response is already a change from baseline. Must be one of`"raw"`

or`"change"`

.- study
Character of length 1, name of the column in

`data`

with the study ID.- study_reference
Atomic of length 1, element of the

`study`

column that indicates the current study. (The other studies are historical studies.)- group
Character of length 1, name of the column in

`data`

with the group ID.- group_reference
Atomic of length 1, element of the

`group`

column that indicates the control group. (The other groups may be treatment groups.)- patient
Character of length 1, name of the column in

`data`

with the patient ID.- rep
Character of length 1, name of the column in

`data`

with the rep ID.- rep_reference
Atomic of length 1, element of the

`rep`

column that indicates baseline, i.e. the first rep chronologically. (The other reps may be post-baseline study visits or time points.)- covariates
Character vector of column names in

`data`

with the columns with baseline covariates. These can be continuous, categorical, or binary. Regardless,`historicalborrowlong`

derives the appropriate model matrix.Each baseline covariate column must truly be a

*baseline*covariate: elements must be equal for all time points within each patient (after the steps in the "Data processing" section). In other words, covariates must not be time-varying.A large number of covariates, or a large number of levels in a categorical covariate, can severely slow down the computation. Please consider carefully if you really need to include such complicated baseline covariates.

- constraint
Logical of length 1, whether to pool all study arms at baseline (first rep). Appropriate when the response is the raw response (as opposed to change from baseline) and the first rep (i.e. time point) is prior to treatment.

- eoi
Numeric of length at least 1, vector of effects of interest (EOIs) for critical success factors (CSFs).

- direction
Character of length

`length(eoi)`

indicating how to compare the treatment effect to each EOI.`">"`

means Prob(treatment effect > EOI), and`"<"`

means Prob(treatment effect < EOI). All elements of`direction`

must be either`">"`

or`"<"`

.

A tidy data frame with one row per group (e.g. treatment arm) and the columns in the following list. Unless otherwise specified, the quantities are calculated at the group-by-rep level. Some are calculated for the current (non-historical) study only, while others pertain to the combined dataset which includes all historical studies.

`group`

: group index.`group_label`

: original group label in the data.`rep`

: rep index.`rep_label`

: original rep label in the data.`data_mean`

: observed mean of the response specific to the current study.`data_sd`

: observed standard deviation of the response specific to the current study.`data_lower`

: lower bound of a simple frequentist 95% confidence interval of the observed data mean specific to the current study.`data_upper`

: upper bound of a simple frequentist 95% confidence interval of the observed data mean specific to the current study.`data_n`

: number of non-missing observations in the combined dataset (all studies).`data_N`

: total number of observations (missing and non-missing) in the combined dataset (all studies).`data_n_study_*`

: number of non-missing observations in each study. The suffixes of these column names are integer study indexes. Call`dplyr::distinct(hbl_data(your_data), study, study_label)`

to see which study labels correspond to these integer indexes.`data_N_study_*`

: total number of observations (missing and non-missing) within each study. The suffixes of these column names are integer study indexes. Call`dplyr::distinct(hbl_data(your_data), study, study_label)`

to see which study labels correspond to these integer indexes.`response_mean`

: Estimated posterior mean of the response from the model. (Here, the response variable in the data should be a change from baseline outcome.) Specific to the current study.`response_sd`

: Estimated posterior standard deviation of the mean response from the model. Specific to the current study.`response_variance`

: Estimated posterior variance of the mean response from the model. Specific to the current study.`response_lower`

: Lower bound of a 95% posterior interval on the mean response from the model. Specific to the current study.`response_upper`

: Upper bound of a 95% posterior interval on the mean response from the model. Specific to the current study.`response_mean_mcse`

: Monte Carlo standard error of`response_mean`

.`response_sd_mcse`

: Monte Carlo standard error of`response_sd`

.`response_lower_mcse`

: Monte Carlo standard error of`response_lower`

.`response_upper_mcse`

: Monte Carlo standard error of`response_upper`

.`change_*`

: same as the`response_*`

columns, but for change from baseline instead of the response. Not included if`response_type`

is`"change"`

because in that case the response is already change from baseline.`change_percent_*`

: same as the`change_*`

columns, but for the*percent*change from baseline (from 0% to 100%). Not included if`response_type`

is`"change"`

because in that case the response is already change from baseline. Specific to the current study.`diff_*`

: same as the`response_*`

columns, but for treatment effect.`P(diff > EOI)`

,`P(diff < EOI)`

: CSF probabilities on the treatment effect specified with the`eoi`

and`direction`

arguments. Specific to the current study.`effect_mean`

: same as the`response_*`

columns, but for the effect size (diff / residual standard deviation). Specific to the current study.`precision_ratio*`

: same as the`response_*`

columns, but for the precision ratio, which compares within-study variance to among-study variance. Only returned for the hierarchical model. Specific to the current study.

The `hbl_summary()`

function post-processes the results from
the model. It accepts MCMC samples of parameters and returns
interpretable group-by-rep posterior summaries such as change
from baseline response and treatment effect. To arrive at these
summaries, `hbl_summary()`

computes marginal posteriors of
transformed parameters. The transformations derive patient-level
fitted values from model parameters, then derive group-by-rep
responses as averages of fitted values. We refer to this style
of estimation as "unconditional estimation", as opposed to
"conditional estimation", which takes each group mean to be the
appropriate linear combination of the relevant `alpha`

and `delta`

parameters, without using `beta`

components or going through fitted
values. If the baseline covariates are balanced across studies,
unconditional and conditional estimation should produce similar
estimates of placebo and treatment effects.

Other summary:
`hbl_metrics()`

```
if (!identical(Sys.getenv("HBL_TEST", unset = ""), "")) {
set.seed(0)
data <- hbl_sim_pool(
n_study = 2,
n_group = 2,
n_patient = 5,
n_rep = 3
)$data
tmp <- utils::capture.output(
suppressWarnings(
mcmc <- hbl_mcmc_hierarchical(
data,
chains = 1,
warmup = 10,
iter = 20,
seed = 0
)
)
)
hbl_summary(mcmc, data)
}
```