weights_jsd: Further weight functions

In baskwrap: Wrapper Package for Several Basket Trial R Packages

Further weight functions

Description

A couple of weight functions additional to the ones implemented in baskexact are supplied. The weight functions are based on the Jensen-Shannon divergence (JSD) and the Hellinger distance (HLD). The function weights_jsd is a wrapper of baskexact::weights_fujikawa. It can be used with both designs of class fujikawa_x (from the baskwrap package) and designs of class OneStageBasket (from the baskexact package). The function weights_jsd_vanilla is a convenience wrapper that calls this with epsilon = 1 and tau = 0 without pruning. Hence, this function returns precisely Fujikawa et al.'s weights without any tuning. The function weights_fujikawa_tuned tunes an existing weight matrix using the parameters epsilon and tau in accordance with Fujikawa et al.'s tuning rules. The function weights_hld and the "convenience wrapper" weights_hld_vanilla are a variant of Fujikawa's weights where the similarity is calculated using 1 minus Hellinger distance instead of 1 minus Jensen-Shannon divergence (see Details).

Usage

weights_jsd(design, n, logbase, epsilon, tau, lambda = NULL, ...)

weights_jsd_vanilla(design, n, logbase, ...)

weights_fujikawa_tuned(weight_mat, epsilon = 1.25, tau = 0.5, ...)

weights_hld_vanilla(design, n, ...)

weights_hld(design, n, epsilon, tau, ...)

Arguments

design	An object of class fujikawa_x or of class OneStageBasket from the baskexact package.
n	The sample size per basket.
logbase	Tuning parameter. The base of the logarithm that is used to calculate the Jensen-Shannon divergence.
epsilon	Tuning parameter that determines the amount of borrowing. See setup_fujikawa).
tau	Tuning parameter that determines how similar the baskets have to be that information is shared. See setup_fujikawa).
lambda	The posterior probability threshold, currently only used for designs with "exact" backend where pruning is activated. See documentation of baskexact::weights_fujikawa for more information.
...	Further arguments.
weight_mat	An untuned matrix including the weights of all possible pairwise outcomes.

Details

For posterior beta distributions as in Fujikawa's design, the Hellinger distance can be calculated "analytically", e.g. for posterior parameters (a_1,b_1) and (a_2,b_2), we have

HLD(\mathrm{Beta}(a_1,b_1),\mathrm{Beta}(a_2,b_2)) = 1 - \frac{B(\frac{a_1+a_2}{2},\frac{b_1+b_2}{2})}{\sqrt{B(a_1,b_1)B(a_2,b_2)}},

where B(\cdot,\cdot) is the beta function (Sasha 2012). The similarity between strata is calculated as 1-HLD(\cdot,\cdot).

Value

A matrix including the weights of all possible pairwise outcomes.

References

Sasha. Answer to "Hellinger distance between Beta distributions"; 2012. Available from: https://math.stackexchange.com/a/165399/332808

Examples

design <- setup_fujikawa_x(k = 3, p0 = 0.2, backend = "exact")
weight_mat <- weights_jsd_vanilla(design, n = 20, logbase = 2)
weight_mat_tuned <- weights_fujikawa_tuned(weight_mat, epsilon = 1.25,
                                           tau = 0.5)
# In theory, this weights_function is also compatible with baskexact.
baskexact::toer(design$design_exact, n = 20,
                lambda = 0.95, weight_fun = weights_jsd,
                weight_params = list(epsilon = 2,
                                     tau = 0,
                                     logbase = 2))
# Use different function in get_details
get_details(design = design, n = 20, p1 = c(0.2, 0.5, 0.5), lambda = 0.95,
            epsilon = 2, tau = 0, weight_fun = weights_jsd,
            logbase = exp(1))
get_details(design = design, n = 20, p1 = c(0.2, 0.5, 0.5), lambda = 0.95,
            epsilon = 2, tau = 0, weight_fun = weights_hld,
            logbase = exp(1))

baskwrap documentation built on March 19, 2026, 5:09 p.m.