| Type: | Package |
| Title: | Bayesian Multiscale Two-Sample Comparison |
| Version: | 0.1.0 |
| 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. |
| URL: | https://github.com/nawaya040/ptcompare |
| BugReports: | https://github.com/nawaya040/ptcompare/issues |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| Imports: | Rcpp, graphics, grDevices, stats, utils |
| LinkingTo: | Rcpp |
| Suggests: | testthat (≥ 3.0.0), knitr, rmarkdown, mclust |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | yes |
| Packaged: | 2026-10-28 08:35:10 UTC; naway |
| Author: | Naoki Awaya [aut, cre] |
| Maintainer: | Naoki Awaya <nawaya@waseda.jp> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-17 18:20:02 UTC |
ptcompare: compare the distributions of two groups
Description
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).
Details
A typical analysis:
-
fit <- compare_pt(x, y)compares group 1 (x) with group 2 (y). -
fitorsummary(fit)shows the posterior probability that the distributions differ. -
regions(fit, prob = 0.9)lists the regions where the groups differ. -
plot(fit)andplot(fit, type = "regions")show the results.
Settings are changed with pt_prior() (statistical model) and
pt_control() (computation).
Author(s)
Maintainer: Naoki Awaya nawaya@waseda.jp
References
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
Compare the distributions of two groups
Description
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.
Usage
compare_pt(
x,
y = NULL,
group = NULL,
support = NULL,
prior = pt_prior(),
control = pt_control(),
transform = if (is.null(support)) "rank" else "range"
)
Arguments
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. |
Details
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.
Value
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,variablesGroup names, number of observations per group and names of the variables used.
prior,control,transformThe settings used.
data,groupThe observations in the original units and their group (0 or 1), in the order they were given;
NULLwhenpt_control(keep_data = FALSE)was used.region_rows()andregion_data()use them to return the observations of a region.
References
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
See Also
regions(), region_data(), summary(),
plot(), pt_prior(), pt_control()
Examples
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)
Computational diagnostics
Description
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.
Usage
diagnostics(x, ...)
Arguments
x |
Result of |
... |
Not used. |
Value
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_scoresFor 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_fractionNumber of regions of the representative tree that reached
max_depthwith at leastmin_nodeobservations, and the fraction of observations in them.numerical_stop_leavesNumber of regions too narrow to divide further.
unique_proposals,peak_particle_payload_bytesNumber of distinct division steps computed, and the approximate memory used by the particles (bytes).
Examples
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_seconds
Plot the results of a comparison
Description
Four kinds of plots:
-
type = "tree"(default): the representative tree. Each node is a region, labeled with its division (variable <= threshold) andprob_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 ofregions()withprob_differenceat leastproband at leastmin_nobservations of each group, ordered byrank_by; at mosttopare 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 itsprob_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 indiagnostics().
Usage
## 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,
...
)
Arguments
x |
Result of |
type |
|
node |
For |
max_depth |
For |
top |
For |
prob |
For |
rank_by |
For |
min_n |
For |
... |
Graphical parameters such as |
Details
"regions" and "levels" need the data, which are kept unless
pt_control(keep_data = FALSE) was used.
Value
The data shown, invisibly.
References
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
Examples
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")
Computational settings
Description
Settings that control how compare_pt() carries out its computation.
They affect accuracy and running time. The defaults are suitable for most
analyses.
Usage
pt_control(
particles = 256L,
ess_threshold = 0.5,
keep_particles = FALSE,
keep_data = TRUE,
effect_draws = 4096L,
resample_power = 0.5
)
Arguments
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. |
Value
A pt_control object to pass to compare_pt().
See Also
pt_prior() for the statistical model settings.
Examples
pt_control()
pt_control(particles = 1024)
Model settings
Description
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.
Usage
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
)
Arguments
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 |
Value
A pt_prior object to pass to compare_pt().
See Also
pt_control() for the computational settings.
Examples
pt_prior()
pt_prior(max_depth = 6, split_grid = 7)
Observations in a region
Description
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.
Usage
region_rows(x, node, ...)
region_data(x, node, ...)
Arguments
x |
Result of |
node |
|
... |
Not used. |
Details
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.
Value
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.
See Also
regions() for which regions differ most;
plot(fit, type = "regions") to draw them.
Examples
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))
Regions where the two groups differ
Description
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.
Usage
regions(x, prob = 0.5, min_n = 0L, rank_by = c("probability", "effect"), ...)
## S3 method for class 'ptcompare_regions'
print(x, ...)
Arguments
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. |
Details
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.
Value
A data frame with one row per division, sorted by rank_by
(largest first). Columns:
node_id,parent_id,depthPosition 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,thresholdThe division: the left part is
variable <= threshold.n1,n2Number 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,upper95% 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.
See Also
compare_pt(); plot(fit, type = "regions") draws these regions
with the data; region_data() returns the observations of one region.
Examples
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)
Summarize a comparison
Description
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).
Usage
## 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, ...)
Arguments
x, object |
Result of |
... |
Not used. |
top |
Number of divisions to show. |
Value
summary() returns a summary.ptcompare_fit object, which is
printed. Its component regions holds the divisions shown. print()
returns its argument invisibly.
Examples
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)