# Tutorial

To use `waspr` the user first needs to load the package as follows:

    library(waspr)

The user must provide a 3-dimensional array with posterior samples for all parameters for each subset posterior (rows = subset posteriors, columns = parameters, slices = samples). The amount of parameters and samples must be equal for each subset posterior, these posterior samples may be obtained from any type of MCMC algorithm. `waspr` provides an example array with posterior samples for 8 parameters for 8 subset posteriors, `pois_logistic`, that will be used to illustrate the functionality of the package.

The main function `wasp()` runs the swapping algorithm, combines its output and computes the Wasserstein barycenter. It has four arguments, `mcmc`, that specifies the 3-dimensional array with samples for each subset posterior, and optional arguments `par.names`, that can be used to specify parameter names, `iter` to specify the maximum number of iterations of the swapping algorithm, `acc` to specify the accuracy of the swapping algorithm and `out` to indicate whether the results per iteration of the swap algorithm should be printed.

    out <- wasp(pois_logistic,
                iter = 10,
                acc = 0.001,
                par.names = c("beta_s", "alpha_l", "beta_l",
                             "baseline_sigma", "baseline_mu",
                             "correlation", "sigma_s", "sigma_l"))

`wasp()` prints the iteration number and cost function value of the swapping algorithm. The `out` object is of class `wasp` and contains several elements. To obtain the Wasserstein barycenter of the subset posteriors a user can specify `out$barycenter`. This returns a matrix of posterior samples (rows) for all parameters (columns) of the full data posterior. A summary of the approximation of the full data posterior is available through `summary(out)`.

    summary(out)
    #>                      mean       mode         sd      LB HPD     UB HPD
    #> beta_s          0.5527601  0.5518034 0.10988949  0.36598187  0.7896041
    #> alpha_l         2.6811079  2.6959176 0.19199304  2.30380675  3.0295802
    #> beta_l          0.7508520  0.7339988 0.21631011  0.37281283  1.1740767
    #> baseline_sigma  0.3563222  0.3811609 0.06859910  0.21910807  0.4870079
    #> baseline_mu    -0.8008872 -0.7516167 0.10867533 -1.01168299 -0.5944583
    #> correlation     0.1732170  0.1392670 0.07437737  0.02824474  0.3059979
    #> sigma_s         1.7225455  1.7535499 0.17920847  1.40126462  2.0610585
    #> sigma_l         1.2190297  1.2612822 0.07558163  1.06768047  1.3569757