--- title: "Introduction to ptcompare" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to ptcompare} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.6, dpi = 120, out.width = "100%", fig.align = "center") has_mclust <- requireNamespace("mclust", quietly = TRUE) ``` `ptcompare` compares two samples of continuous multivariate observations. It implements the hidden Markov Pólya tree of Awaya and Ma (2024), a nonparametric Bayesian model whose structure is a recursive partition of the data space. This vignette fits three comparisons: a simulation in two variables where the difference is confined to a small part of the plane, a set of 30 measurements of cell nuclei where the groups are two diagnoses, and a pair of samples drawn from the same distribution. ```{r} library(ptcompare) ``` # A simulated example in two variables Both groups are standard normal in two variables, `marker_A` and `marker_B`. They differ in that about 15% of group 2 is drawn instead from a narrow cluster near `(1.6, 1.6)`. ```{r} set.seed(11) n <- 1000L x <- matrix(rnorm(2 * n), ncol = 2, dimnames = list(NULL, c("marker_A", "marker_B"))) y <- matrix(rnorm(2 * n), ncol = 2, dimnames = list(NULL, c("marker_A", "marker_B"))) extra <- runif(n) < 0.15 y[extra, ] <- cbind(rnorm(sum(extra), 1.6, 0.3), rnorm(sum(extra), 1.6, 0.3)) sum(extra) ``` Over most of the plane the two samples are drawn from the same distribution and lie on top of one another. The cluster occupies a small region in the upper right, and it belongs to one group only. ```{r, fig.cap = "The two samples. Group 2 carries an extra cluster near (1.6, 1.6)."} plot(rbind(x, y), type = "n", xlab = "marker_A", ylab = "marker_B") points(x, pch = 0, col = "#123E7C", cex = 0.6) points(y, pch = 2, col = "#B65D35", cex = 0.6) legend("topleft", c("group 1", "group 2"), pch = c(0, 2), col = c("#123E7C", "#B65D35"), bty = "n") ``` `compare_pt()` takes the two samples; every other argument has a default. ```{r} set.seed(12) fit <- compare_pt(x, y) fit ``` `prob_difference` is the posterior probability that the two distributions differ. That probability says only that a difference exists somewhere, but `regions()` can locate it. Each row is one division of the representative tree, the tree with the highest posterior score among those sampled, and the rows are ordered by `prob_difference` — which here is the probability that the groups branch differently at that one division, not the global quantity printed above. ```{r} regions(fit, prob = 0.9, min_n = 40) ``` Take the first row. Its `condition` restricts attention to the observations with `marker_A > 0.866` and `marker_B > 0.101`, a part of the plane holding 102 observations of group 1 and 209 of group 2. Within it the division is at `marker_B = 0.841`, and the two groups fall below that threshold in different proportions: `prob_difference` is 1.00, and `effect`, a log odds ratio of group 1 against group 2, is 1.98, so the odds of falling below the threshold are about seven times higher in group 1. The `lower` and `upper` columns give a 95% credible interval for that log odds ratio. The region is the upper right part of the plane, where the simulated cluster lies, and the sign of the effect says that group 2 is the one over-represented above the threshold. Two further columns are reported for each division: `effect_abs`, the posterior mean of the absolute log odds ratio, which is not in general the absolute value of `effect`, and `prob_positive`, the posterior probability that the log odds ratio is positive. ## Plots The same regions can be drawn with the data. `min_n` is passed again so that the panels match the rows of the table above. ```{r, fig.height = 5.4, fig.cap = "The four most probable regions. The box is the region, the dashed line its threshold."} plot(fit, type = "regions", top = 4, min_n = 40) ``` Each panel is one region. The box is the region, the dashed line is the threshold that divides it, and the observations inside are drawn as blue squares and brown triangles, with the rest of the data in gray for context. The first panel is the region discussed above; the brown triangles concentrated inside it are the simulated cluster. The tree shows how the regions are nested and which variable each division uses. Here `max_depth` limits how much of the tree is drawn; it does not change the fit. ```{r, fig.cap = "The representative tree, drawn to depth 3."} plot(fit, max_depth = 3) ``` With two variables the regions at each depth can also be shaded by their probability of a difference, which shows how the comparison narrows as the partition becomes finer. ```{r, fig.height = 5.4, fig.cap = "Regions by depth, shaded by the probability of a difference."} plot(fit, type = "levels", max_depth = 3) ``` At depth 0 the only region is the whole plane, so the shading reports no more than that the samples differ somewhere. The shaded area contracts as the tree deepens, and by depth 3 it has settled on the upper right corner. # Cell nuclei from breast mass images The `wdbc` data in the **mclust** package are the Wisconsin Diagnostic Breast Cancer data of Street, Wolberg and Mangasarian (1993). For each of 569 patients, a fine needle aspirate was taken from a breast mass and photographed, and the boundary of each cell nucleus in the image was traced. Ten geometric features were computed for every nucleus: radius, texture, perimeter, area, smoothness, compactness, concavity, concave points, symmetry and fractal dimension. Each feature was then summarized over the nuclei of an image by its mean, its standard error and an extreme value, which is how the 30 variable names below are composed. The mass was separately diagnosed as benign or malignant. ```{r, eval = has_mclust} data("wdbc", package = "mclust") features <- setdiff(names(wdbc)[sapply(wdbc, is.numeric)], "ID") features table(wdbc$Diagnosis) ``` The question is how nuclear morphology differs between the two diagnoses. Here the groups are a label on a single data set rather than two matrices, so they are given through `group`. The levels of that factor fix the order, so group 1 is `B`, the benign masses, and group 2 is `M`. ```{r, eval = has_mclust} set.seed(2) fit_wdbc <- compare_pt(wdbc[, features], group = wdbc$Diagnosis) summary(fit_wdbc, top = 3) ``` The two diagnoses differ, and `summary()` also reports the computation: the effective number of particles at the end of the sequential Monte Carlo, how often the particles were resampled, and the running time. Asking for the regions with a probability of at least 0.9 and at least 25 observations of each group returns two. The third division in the summary above is dropped by the second condition, not the first: it holds only 10 benign cases. ```{r, eval = has_mclust} found <- regions(fit_wdbc, prob = 0.9, min_n = 25) found[, c("depth", "variable", "n1", "n2", "prob_difference", "effect")] ``` ```{r, eval = has_mclust, fig.cap = "Left: the division at the root. Right: a division within the large nuclei."} plot(fit_wdbc, type = "regions", top = 2, min_n = 25) ``` The first region is at depth 0, which is to say it is the whole data set, and it reproduces the familiar result: the nuclei of malignant masses are larger. The division is on `Perimeter_extreme` at 102, with an effect of about 5 on the log odds scale. This is a difference between two marginal distributions, and needs no partition to find. The second region is at depth 6, and is the kind of statement that does. ```{r, eval = has_mclust} local <- found[found$depth > 0, ][1, ] local$condition ``` Six conditions, all of them lower bounds on measurements of size, restrict attention to the images whose nuclei are large: 41 benign masses and 182 malignant ones. Within that region the method reports a further division, and it falls on a measure of shape rather than size, `Nconcave_mean`, which summarizes the concave points on the nucleus boundary. `region_data()` returns the observations of a region, with a column giving the group, so the division can be examined directly. ```{r, eval = has_mclust} cells <- region_data(fit_wdbc, local$node_id) tapply(cells$Nconcave_mean, cells$group, median) tapply(cells$Nconcave_mean <= local$threshold, cells$group, mean) ``` Among these large nuclei the median benign image sits at 0.039 against 0.088 for the malignant ones, and 76% of the benign images fall below the threshold against 9% of the malignant ones. The two diagnoses are therefore separated twice over by different features: once by size across the whole data set, and again by the irregularity of the nucleus boundary among the masses whose nuclei are large. The second statement is about a conditional distribution inside a subset of the data, and it is the kind of result the partition is there to produce. # A comparison with no difference The last comparison uses the same 30 variables, but splits the benign cases into two halves at random and compares those with each other. The two samples come from the same distribution by construction. ```{r, eval = has_mclust} benign <- wdbc[wdbc$Diagnosis == "B", features] set.seed(3) half <- sample(c(TRUE, FALSE), nrow(benign), replace = TRUE) set.seed(4) fit_null <- compare_pt(benign[half, ], benign[!half, ]) fit_null nrow(regions(fit_null, prob = 0.9)) ``` The posterior probability of a difference is 0.07, and no division reaches a probability of 0.9. # Notes and further documentation The regions and effect sizes are reported for the representative tree, the one with the highest posterior score among the trees that were sampled. Regions selected by a probability threshold can be nested inside one another, and they carry no frequentist multiple-testing guarantee. * `?compare_pt` for the arguments, including `transform`, which sets the common scale the variables are put on before the space is divided. * `?pt_prior` and `?pt_control` for the model and the computational budget, and for the defaults used above. * `?regions` for the meaning of each column, and for `rank_by = "effect"`, which orders by the size of a difference rather than its probability. * `?region_rows` and `?region_data` for extracting the observations of a region. * `?plot.ptcompare_fit` for the plots used here. With three or more variables a panel draws two of them, so the box is the region seen in those two variables only, and the symbols rather than the box indicate membership. This applies to both panels of the 30-variable figure above. * `system.file("STATISTICAL-SPECIFICATION.md", package = "ptcompare")` for the model, the target distribution of the sequential Monte Carlo and the definition of the effect sizes. # 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. Street, W. N., Wolberg, W. H. and Mangasarian, O. L. (1993). Nuclear feature extraction for breast tumor diagnosis. *IS&T/SPIE International Symposium on Electronic Imaging: Science and Technology*, 1905, 861--870.