Get started
In unsum: Reconstruct Raw Data from Summary Statistics

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%"
)

library(unsum)

Here is a brief walkthrough of using CLOSURE in unsum.

Call closure_generate() to run the CLOSURE algorithm. Enter mean, SD, and sample size that you read in a paper. For scale_min and scale_max, use the empirical minimum and maximum if available. Otherwise, use the more fundamental scale bounds, e.g., 1 and 7 for a 1-7 scale.

The mean and sd arguments must be strings to preserve trailing zeros. Note that CLOSURE can only be used if the values must be integers: e.g., a value can be 2 or 3, but not 2.5.

data <- closure_generate(
  mean = "3.5",
  sd = "1.8",
  n = 80,
  scale_min = 1,
  scale_max = 5
)

First create a plot of the mean sample found by CLOSURE. This gives us a sense of the overall results, which are quite polarized:

#| fig.alt: >
#|   Barplot of `data`, the CLOSURE output.
#|   It specifically visualizes the `f_average` column of
#|   the `frequency` tibble, but also gives percentage figures,
#|   similar to the `f_relative` column. The overall shape is
#|   a strongly polarized distribution.
closure_plot_bar(data)

You can customize the plot, e.g., to show the sum of all samples found instead of the average sample, or only percentages, or different colors. See documentation at closure_plot_bar(). However, the default should be informative enough for a start.

CLOSURE results

Now let's look at the results themselves:

data

inputs records the arguments in closure_generate().
metrics shows the number of possible samples that could have led to the reported summary statistics (samples_all) and the total number of all values found in them (values_all).

Importantly, it also features an index of variation in bounded scales (horns). It ranges from 0 to 1, where 0 means no variability and 1 would be a sample evenly split between the extremes — here, 1, and 5 — with no values in between. The reference value horns_uniform shows which value horns would have if the mean sample was uniformly distributed. This is 0.5 because of the 1-5 scale. See horns() for more details.

The actual horns value is 0.79, which is a high degree of variability even in the abstract. However, in practice, 0.79 might be extremely high compared to theoretical expectations: if the sample should have a roughly normal shape, even the hypothetical 0.5 uniform value would be surprisingly high, let alone the 0.79 actual value.
frequency shows the absolute and relative frequencies of values found by CLOSURE at each scale point. It also gives us the (absolute) frequency of values in the average sample that we saw in the plot above.
results stores all the samples that CLOSURE found (sample). Each has a unique number (id).

See closure_generate() for more details.

In addition to the bar plot, unsum offers an ECDF plot for CLOSURE results:

#| fig.alt: >
#|   Empirical cumulative distribution function (ECDF) plot
#|   of `data`, the CLOSURE output. The curve rises most steeply at the
#|   first and last scale values, indicating a strongly polarized distribution.
closure_plot_ecdf(data)

Horns index variation

You may wonder about variability between the samples. Couldn't there be some with a much lower or higher horns index than the overall mean horns? In this case, there would be a chance that the original data looked quite different from the average. Check this using closure_horns_analyze():

data_horns <- closure_horns_analyze(data)
data_horns

Also, closure_horns_histogram() visualizes the distribution of horns values across all samples:

#| fig.alt: >
#|   Barplot of horns values distribution.
#|   The scale limits range from 0 to 1,
#|   but values only start after 0.75
#|   and end before 0.90.
closure_horns_histogram(data_horns)

In sum, the horns values are quite tightly confined. Wide variation among them seems to occur only if mean and sd have no decimal places.

Read and write

What if you have a huge object with CLOSURE results that you want to save? Write it to disk with closure_write():

# Using a temporary folder via `tempdir()` just for this example --
# you should use a real folder on your computer instead!
path_new_folder <- closure_write(data, path = tempdir())

This stores the results using the highly efficient Parquet format. It will only take a tiny fraction of a CSV file's disk space.

In your later session, read the data in from the folder to get the same CLOSURE list back:

data_new <- closure_read(path_new_folder)

A caveat: don't modify the output of closure_generate() before passing it into other closure_*() functions. The latter need input with a very specific format, and if you manipulate the data between two closure_*() calls, these assumptions may no longer hold. Some checks are in place to detect alterations, but they may not catch all of them.