| Title: | Bayesian Multiscale Two-Sample Comparison |
|---|---|
| Description: | Bayesian comparison of two multivariate distributions using hidden Markov Polya trees with adaptive partitions, following Awaya and Ma (2024) <doi:10.1080/01621459.2022.2105223>. Provides posterior evidence for overall differences, interpretable partition trees, local effect sizes and computational diagnostics. Posterior computation combines sequential Monte Carlo and recursive message passing. |
| Authors: | Naoki Awaya [aut, cre] |
| Maintainer: | Naoki Awaya <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.1.0 |
| Built: | 2026-11-18 00:13:16 UTC |
| Source: | https://github.com/cran/ptcompare |
Compares the distributions of two groups of observations on numeric variables and finds the regions where they differ, using the hidden Markov Pólya tree method of Awaya and Ma (2024).
A typical analysis:
fit <- compare_pt(x, y) compares group 1 (x) with group 2 (y).
fit or summary(fit) shows the posterior probability that the
distributions differ.
regions(fit, prob = 0.9) lists the regions where the groups differ.
plot(fit) and plot(fit, type = "regions") show the results.
Settings are changed with pt_prior() (statistical model) and
pt_control() (computation).
Maintainer: Naoki Awaya [email protected]
Awaya, N. and Ma, L. (2024). Hidden Markov Pólya Trees for High-Dimensional Distributions. Journal of the American Statistical Association, 119(545), 189–201. doi:10.1080/01621459.2022.2105223
Compares the distributions of two groups of observations on one or more
numeric variables, using the hidden Markov Pólya tree method of Awaya and
Ma (2024). It gives the posterior probability that the two distributions
differ, and finds regions of the data space where they differ. Each region
is described by conditions on the variables, such as age <= 40.
compare_pt( x, y = NULL, group = NULL, support = NULL, prior = pt_prior(), control = pt_control(), transform = if (is.null(support)) "rank" else "range" )compare_pt( x, y = NULL, group = NULL, support = NULL, prior = pt_prior(), control = pt_control(), transform = if (is.null(support)) "rank" else "range" )
x |
Data for group 1: a numeric matrix or data frame with one row per
observation and one column per variable, or a numeric vector for a single
variable. When |
y |
Data for group 2, with the same columns as |
group |
Group labels for the rows of |
support |
Optional known range of the variables: a matrix with one row
per variable and two columns (lower and upper limit), or a vector
|
prior |
Model settings from |
control |
Computational settings from |
transform |
How the variables are put on a common scale before dividing.
In both cases, thresholds and regions are reported in the original units. |
The method divides the data space into regions step by step, building a tree of divisions, and compares how the two groups fall on the two sides of each division. Many candidate trees are explored; the one that best fits the data (the representative tree) is used to describe where the groups differ.
Variables that take the same value in all observations are
removed with a warning. Missing (NA) and infinite values are not
allowed; remove those rows first. If there are fewer than min_node
observations in total (see pt_prior()), no division is possible and
prob_difference is 0.
A ptcompare_fit object. Use summary(),
regions() and plot() to look at the results. Its
main components are:
prob_differencePosterior probability that the two distributions differ.
prob_nullPosterior probability that they are the same
(1 - prob_difference).
treeThe representative tree, one row per region. regions()
gives an easier-to-read table of its divisions.
diagnosticsInformation about the computation; see
diagnostics().
group_names, sample_sizes, variables
Group names, number of observations per group and names of the variables used.
prior, control, transform
The settings used.
data, group
The observations in the original units and
their group (0 or 1), in the order they were given; NULL when
pt_control(keep_data = FALSE) was used. region_rows() and
region_data() use them to return the observations of a region.
Awaya, N. and Ma, L. (2024). Hidden Markov Pólya Trees for High-Dimensional Distributions. Journal of the American Statistical Association, 119(545), 189–201. doi:10.1080/01621459.2022.2105223
regions(), region_data(), summary(),
plot(), pt_prior(), pt_control()
set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) fit summary(fit) # Data in one data frame with a group column two <- droplevels(subset(iris, Species != "setosa")) fit2 <- compare_pt(two[, 1:4], group = two$Species, control = pt_control(particles = 32)) regions(fit2, prob = 0.9)set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) fit summary(fit) # Data in one data frame with a group column two <- droplevels(subset(iris, Species != "setosa")) fit2 <- compare_pt(two[, 1:4], group = two$Species, control = pt_control(particles = 32)) regions(fit2, prob = 0.9)
Information about the computation of compare_pt(), such as the number of
effective particles and the running time. plot(fit, type = "diagnostics")
shows the effective number of particles as a graph.
diagnostics(x, ...)diagnostics(x, ...)
x |
Result of |
... |
Not used. |
A list with components:
final_essEffective number of particles at the end (at most
particles).
resamplesNumber of resampling steps.
elapsed_secondsRunning time of compare_pt() in seconds.
traceData frame with one row per step of the computation:
effective number of particles before resampling (ess), number of
different trees (unique_trees), number of distinct initial
particles that the current particles descend from
(root_ancestors), and whether resampling took place (resampled).
weights, particle_null, particle_scores
For each final particle: its weight, its probability that the groups are the same, and the fit score used to choose the representative tree.
log_evidenceEstimated log marginal likelihood of the data.
depth_limited_leaves, depth_limited_fraction
Number of
regions of the representative tree that reached max_depth with at
least min_node observations, and the fraction of observations in
them.
numerical_stop_leavesNumber of regions too narrow to divide further.
unique_proposals, peak_particle_payload_bytes
Number of distinct division steps computed, and the approximate memory used by the particles (bytes).
set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) d <- diagnostics(fit) d$final_ess d$elapsed_secondsset.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) d <- diagnostics(fit) d$final_ess d$elapsed_seconds
Four kinds of plots:
type = "tree" (default): the representative tree. Each node is a
region, labeled with its division (variable <= threshold) and
prob_difference. Larger nodes contain more observations. The color
shows the direction of the difference: blue when group 1 is more likely
to be in the left part, brown when group 2 is.
type = "regions": the regions where the two groups differ most, one
panel per region (similar to Figure 14 of the supplement of Awaya and Ma,
2024). The regions are those of regions() with prob_difference at
least prob and at least min_n observations of each group, ordered by
rank_by; at most top are shown. With two or more variables, each
panel is a scatter plot: the horizontal axis is the variable that divides
the region (dashed line: threshold), the vertical axis another variable
that bounds the region. Observations inside the region are shown as blue
squares (group 1) and brown triangles (group 2), the others in gray.
The box is the region seen in the two variables of the panel only. With
three or more variables the region may also be bounded by variables that
the panel does not show, so an observation can lie inside the box and
still be gray; the symbols, not the box, show which observations are in
the region. With two variables the box is the region itself. With one
variable, each panel shows the distributions of the two groups inside
the region.
type = "levels": for two variables only. One scatter plot per depth of
the tree; each region at that depth is shaded by its prob_difference
(as in Figure 7 of Soriano and Ma, 2017). Dotted lines show how each
region is divided at the next depth.
type = "diagnostics": the effective number of particles at each step of
the computation, with the resampling threshold as a dashed line and the
steps where resampling took place marked. The other recorded quantities
are in diagnostics().
## S3 method for class 'ptcompare_fit' plot( x, type = c("tree", "regions", "levels", "diagnostics"), node = NULL, max_depth = 3L, top = 9L, prob = 0.5, rank_by = c("probability", "effect"), min_n = 50L, ... )## S3 method for class 'ptcompare_fit' plot( x, type = c("tree", "regions", "levels", "diagnostics"), node = NULL, max_depth = 3L, top = 9L, prob = 0.5, rank_by = c("probability", "effect"), min_n = 50L, ... )
x |
Result of |
type |
|
node |
For |
max_depth |
For |
top |
For |
prob |
For |
rank_by |
For |
min_n |
For |
... |
Graphical parameters such as |
"regions" and "levels" need the data, which are kept unless
pt_control(keep_data = FALSE) was used.
The data shown, invisibly.
Soriano, J. and Ma, L. (2017). Probabilistic multi-resolution scanning for two-sample differences. Journal of the Royal Statistical Society, Series B, 79(2), 547–572. doi:10.1111/rssb.12180
set.seed(1) x <- matrix(rnorm(400), ncol = 2) y <- matrix(rnorm(400, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) plot(fit) plot(fit, type = "regions") plot(fit, type = "regions", top = 4, rank_by = "effect") plot(fit, type = "regions", node = 2) plot(fit, type = "levels", max_depth = 3) plot(fit, type = "diagnostics")set.seed(1) x <- matrix(rnorm(400), ncol = 2) y <- matrix(rnorm(400, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) plot(fit) plot(fit, type = "regions") plot(fit, type = "regions", top = 4, rank_by = "effect") plot(fit, type = "regions", node = 2) plot(fit, type = "levels", max_depth = 3) plot(fit, type = "diagnostics")
Settings that control how compare_pt() carries out its computation.
They affect accuracy and running time. The defaults are suitable for most
analyses.
pt_control( particles = 256L, ess_threshold = 0.5, keep_particles = FALSE, keep_data = TRUE, effect_draws = 4096L, resample_power = 0.5 )pt_control( particles = 256L, ess_threshold = 0.5, keep_particles = FALSE, keep_data = TRUE, effect_draws = 4096L, resample_power = 0.5 )
particles |
Number of candidate trees computed in parallel (the
particles of sequential Monte Carlo). More particles give more accurate
results but take longer. Try |
ess_threshold |
Fraction of |
keep_particles |
If |
keep_data |
If |
effect_draws |
Number of points (256 to 1048576) used to compute
|
resample_power |
Number in (0, 1] used when resampling. Particles are drawn with probabilities proportional to their weights raised to this power. The default 0.5 follows Awaya and Ma (2024); 1 gives standard resampling. |
A pt_control object to pass to compare_pt().
pt_prior() for the statistical model settings.
pt_control() pt_control(particles = 1024)pt_control() pt_control(particles = 1024)
Settings of the statistical model used by compare_pt(): how finely the
data space may be divided into regions, where the divisions may be placed,
and how likely the two groups are to differ before seeing the data.
pt_prior( max_depth = 8L, split_grid = 15L, min_node = 20L, gamma = 0.3, beta = 1, prune = 0.3, precision = 1, eta = 0.1, midpoint_spike = TRUE )pt_prior( max_depth = 8L, split_grid = 15L, min_node = 20L, gamma = 0.3, beta = 1, prune = 0.3, precision = 1, eta = 0.1, midpoint_spike = TRUE )
max_depth |
Maximum number of successive divisions (1 to 20). Larger values allow smaller regions and take longer. |
split_grid |
Number of candidate division points for a variable within a region (an odd number from 1 to 127). The candidates are equally spaced and include the middle of the region. |
min_node |
Regions with fewer observations than this (both groups together) are not divided further. |
gamma |
Prior tendency of the two groups to differ, between 0 and 1. Larger values make differences more likely before seeing the data. |
beta |
Number from 1 to 100. Values above 1 make differences in smaller (deeper) regions less likely before seeing the data. The default 1 follows Awaya and Ma (2024). |
prune |
Prior probability, between 0 and 1, that a region and all its subregions are the same in the two groups. |
precision |
Positive number. Larger values make the proportion of observations falling on each side of a division closer, before seeing the data, to the proportion of the region's width on that side. |
eta |
Non-negative number. Larger values favor division points closer
to the middle of a region, more strongly in regions with many
observations. |
midpoint_spike |
If |
A pt_prior object to pass to compare_pt().
pt_control() for the computational settings.
pt_prior() pt_prior(max_depth = 6, split_grid = 7)pt_prior() pt_prior(max_depth = 6, split_grid = 7)
region_rows() says which observations fall in a region of the
representative tree, and region_data() returns those observations. Use
them to look at the subsets that regions() reports as the most different.
region_rows(x, node, ...) region_data(x, node, ...)region_rows(x, node, ...) region_data(x, node, ...)
x |
Result of |
node |
|
... |
Not used. |
A region is any node of the tree, not only a divided one: node 1 is the
whole data space, and the node_id column of regions() or the numbers in
plot(fit) identify the others.
region_rows(): a logical vector with one entry per observation,
TRUE for those in the region. The entries follow the order in which the
data were given to compare_pt(): the rows of x and then the rows of
y, or the rows of the single data set when group was used.
region_data(): a data frame of the observations in the region, with one
column per variable in the original units and a last column holding the
group, named group unless a variable already has that name. Its row
names are the positions in that same order.
Both need the data, which are kept unless pt_control(keep_data = FALSE)
was used.
regions() for which regions differ most;
plot(fit, type = "regions") to draw them.
set.seed(1) x <- matrix(rnorm(200), ncol = 2, dimnames = list(NULL, c("a", "b"))) y <- matrix(rnorm(200, mean = 0.8), ncol = 2, dimnames = list(NULL, c("a", "b"))) fit <- compare_pt(x, y, control = pt_control(particles = 32)) top <- regions(fit)$node_id[1] sum(region_rows(fit, top)) head(region_data(fit, top))set.seed(1) x <- matrix(rnorm(200), ncol = 2, dimnames = list(NULL, c("a", "b"))) y <- matrix(rnorm(200, mean = 0.8), ncol = 2, dimnames = list(NULL, c("a", "b"))) fit <- compare_pt(x, y, control = pt_control(particles = 32)) top <- regions(fit)$node_id[1] sum(region_rows(fit, top)) head(region_data(fit, top))
Lists the divisions of the representative tree and how much the two groups differ at each one. Use it to find where, and in which direction, the distributions differ.
regions(x, prob = 0.5, min_n = 0L, rank_by = c("probability", "effect"), ...) ## S3 method for class 'ptcompare_regions' print(x, ...)regions(x, prob = 0.5, min_n = 0L, rank_by = c("probability", "effect"), ...) ## S3 method for class 'ptcompare_regions' print(x, ...)
x |
Result of |
prob |
Show only rows with |
min_n |
Show only regions with at least this many observations of each group. |
rank_by |
Which divisions to put first. |
... |
Not used. |
Each row is one division of a region into two parts. Inside the region
described by condition, the observations are divided into those with
variable <= threshold (the left part) and the rest (the right part). The
row tells whether the two groups fall into the left part in different
proportions.
A data frame with one row per division, sorted by rank_by
(largest first). Columns:
node_id, parent_id, depth
Position of the region in the
tree (as in plot(fit)); depth 0 is the whole data space.
conditionThe region, as conditions on the variables.
variable, threshold
The division: the left part is
variable <= threshold.
n1, n2
Number of observations of group 1 and group 2 in the region.
prob_differencePosterior probability that the two groups fall into the left part in different proportions.
effectSize and direction of the difference: the log odds ratio of falling into the left part, group 1 versus group 2 (posterior mean). Positive values mean group 1 is more likely to be in the left part; negative values mean group 2 is.
effect_absPosterior mean of the absolute log odds ratio: the size of the difference regardless of direction.
lower, upper
95% credible interval for the log odds ratio. A limit is exactly 0 when the groups may not differ at this division.
prob_positivePosterior probability that group 1 is more likely than group 2 to be in the left part.
compare_pt(); plot(fit, type = "regions") draws these regions
with the data; region_data() returns the observations of one region.
set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) regions(fit) regions(fit, prob = 0.9, min_n = 20)set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) regions(fit) regions(fit, prob = 0.9, min_n = 20)
print(fit) shows the posterior probability that the two distributions
differ. summary(fit) also shows the settings, a short report of the
computation and the divisions with the largest prob_difference (see
regions() for the meaning of the columns).
## S3 method for class 'ptcompare_fit' print(x, ...) ## S3 method for class 'ptcompare_fit' summary(object, ..., top = 6L) ## S3 method for class 'summary.ptcompare_fit' print(x, ...)## S3 method for class 'ptcompare_fit' print(x, ...) ## S3 method for class 'ptcompare_fit' summary(object, ..., top = 6L) ## S3 method for class 'summary.ptcompare_fit' print(x, ...)
x, object
|
Result of |
... |
Not used. |
top |
Number of divisions to show. |
summary() returns a summary.ptcompare_fit object, which is
printed. Its component regions holds the divisions shown. print()
returns its argument invisibly.
set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) fit summary(fit) summary(fit, top = 3)set.seed(1) x <- matrix(rnorm(200), ncol = 2) y <- matrix(rnorm(200, mean = 0.8), ncol = 2) fit <- compare_pt(x, y, control = pt_control(particles = 32)) fit summary(fit) summary(fit, top = 3)