(1) Overview
Introduction
Exploratory data analysis (EDA), coined by John Tukey [1], aims to help statisticians and analysts understand the data before applying formal statistical methods. Visualization methods play a crucial role in this process by revealing the patterns, structures, and associations within data, especially when dealing with high-dimensional datasets. As an EDA tool, the use of matrix visualization (MV) [2, 3, 4, 5, 6], also known as heatmap, has become increasingly widespread to explore high-dimensional datasets by encoding visual elements such as color, size, and shape to uncover the underlying information. Bertin [2] first introduced the concept of using reorderable matrices to methodically represent the structures and relationships within data. Ghoniem et al. [4] conducted a controlled experiment to compare node-link and matrix-based representations. Henry and Fekete [5] developed a dual-representation system that integrates node-link diagrams and MVs to support the exploration of social networks. Such approaches make it possible to detect clusters and latent associations that may be overlooked with traditional plots. Extending this idea, generalized association plots (GAP) [3] incorporate proximity computation and seriation to reorder samples (rows) and variables (columns), providing clearer views of hidden correlation structures. The rank-2 ellipse (R2E), also introduced in [3], is particularly distinctive in capturing global clustering patterns by projecting objects onto a two-dimensional elliptical space.
Building on this framework, Wu et al. [6] developed GAP software as a standalone Java-based package. The system provides an interactive environment where users can explore and analyze data directly and support a wide range of data types, including continuous, binary, ordinal, and nominal. However, despite these advantages, the standalone design limits its integration with the R ecosystem, where most statistical analysis and visualization tasks are now performed.
The R environment has several packages providing solutions to visualize correlation within data. The corrplot package [7] offers intuitive color-coded representations of correlation coefficients. However, it is confined to proximity matrices and provides only a few basic reordering methods. While packages such as pheatmap [8] and ComplexHeatmap [9, 10] have incorporated hierarchical clustering tree (HCT), they lack GAP-specific methods such as R2E and tree-flipping mechanisms. Without these features, refining hierarchical structures or achieving optimal layouts for interpretability is challenging. A comparative summary of these packages is provided in Table 2.
In terms of ordering, the seriation package [11, 12] provides various reordering algorithms but serves mainly as an ordering function rather than a visualization tool, leaving users to combine its results with external plotting functions. Furthermore, although it includes methods such as HCT and R2E, it lacks GAP-specific enhancements like flipping mechanisms and cannot handle large datasets due to lack of performance optimization.
In summary, these packages have notable limitations in seriation capabilities, visualization completeness, and computational efficiency, highlighting the need for a more integrated and efficient solution. The GAPR package fulfills this need as an R implementation of the GAP framework that integrates more efficient proximity computation with HCT and R2E seriation. It has a tree-based flipping mechanism with a comprehensive visualization layout, where the data matrix, proximity matrices, dendrograms for rows and columns, and contextual information are all presented in reordered form to reveal structural patterns. Moreover, these visualization features are further enhanced by optimized algorithms implemented in C++, making GAPR a robust and efficient tool for EDA within the R ecosystem.
Rank-2 Ellipse (R2E)
The R2E algorithm, first introduced in the context of GAP [3], is a seriation algorithm that leverages the converging sequence of iteratively generated correlation matrices. It begins with a given p × p proximity matrix, from which an initial correlation matrix is constructed and further computes it iteratively. This sequence then converges into a matrix whose elements are all +1 or –1, which effectively separates the p objects into two mutually exclusive groups. When the process reaches an iteration where the correlation matrix has numerical rank two, all column vectors of this matrix fall into a two-dimensional subspace and can be represented on the circumference of an ellipse. Each object thereby has a unique relative position on the ellipse. To obtain a one-dimensional ordering, the largest gap between two consecutive objects is identified based on their angular coordinates on the ellipse. By cutting at this point and rearranging the sequence accordingly, R2E produces a successive ordering of the objects. The resulting ordering emphasizes global trends and continuous transitions, making R2E particularly effective for visualizing hidden data structures and enhancing interpretability in seriation tasks.
Implementation and Architecture
Building on the conceptual foundations of GAP introduced above, we describe the implementation and architecture of the GAPR package, which translates these concepts into efficient computation and flexible visualization within the R environment. Core computational procedures are implemented in C++ and interfaced through Rcpp [13, 14], enabling faster proximity calculations and ordering algorithms. For visualization, GAPR builds on the ComplexHeatmap engine [9, 10], which provides robust heatmap rendering, HCT, and covariate annotation. In addition, GAPR introduces GAP-specific features such as R2E seriation, tree-flipping, and customized layout control. The following sections describe how these components are organized and how they interact to produce reordered MVs.
The package Functions and Demonstration
In this section, we present the core functionalities of the GAPR package and illustrate them using the psychosis disorder dataset originally introduced by Lin et al. [15]. The package logic is organized into three components: (1) proximity computation, which calculates distance or correlation between samples or variables; (2) seriation and flipping mechanisms, which reorder samples and variables to enhance pattern visibility; and (3) evaluation metrics, which assess the quality of the reordering based on anti-Robinson structure criteria [16].
Package installation
The GAPR package is available on CRAN and can be installed using:
install.packages("GAPR")For the latest development version, the package can be installed from GitHub:
devtools::install_github("shuyyu/GAPR")After installation, the package can be loaded using:
library(GAPR)
Dataset
The psychosis disorder dataset, derived from Andreasen’s positive and negative symptom scales, including the Scale for the Assessment of Positive Symptoms (SAPS) with 30 items [17] and the Scale for the Assessment of Negative Symptoms (SANS) with 20 items [18], is hereafter referred to as SAPSSANS. Within SAPS, symptoms are organized into four subgroups: hallucinations (AH1–AH6), delusions (DL1–DL12), behavior (BE1–BE4), and thought disorder (TH1–TH8). SANS has five subgroups, including expression (NA1–NA7), speech (NB1–NB4), hygiene (NC1–NC3), activity (ND1–ND4), and inattentiveness (NE1–NE2). The dataset contains symptom scores measured on a six-point ordinal scale (0–5), with each sample (row) representing one of the 95 first-time hospitalized psychosis disorder patients—69 diagnosed with schizophrenia and 26 with bipolar disorder—and each variable (column) corresponding to a specific symptom. In this study, the ordinal symptom scores are treated as continuous variables. Additional discrete covariates— Xd for variables and Yd for samples—indicate the symptom group (positive or negative) and the diagnostic status of each individual (1 for schizophrenia diagnosis, 0 for bipolar disorder diagnosis), respectively.
Proximity computation
Proximity computation is the first step in the GAP workflow, where a matrix is constructed to quantify relationships between samples or variables. This proximity matrix forms the basis for subsequent seriation and visualization. GAPR supports correlation-based, distance-based, and binary similarity measures for binary data, providing flexibility across diverse data types. These methods can be accessed via the function computeProximity(), which computes proximity matrices independently according to the chosen measure. For example, the code below shows how a column-wise Pearson correlation matrix can be generated from the SAPSSANS dataset, and the resulting proximity matrix is displayed in Figure 1(c).
Figure 1
GAPR visualization layout applied to the SAPSSANS dataset using the original (unsorted) data order. The proximity measures used in this example are Pearson correlation for variables and Euclidean distance for samples. (a) Data matrix, (b) row-wise proximity matrix, (c) column-wise proximity matrix, (d) Yd covariate annotation with the user-defined color palette, and (e) Xd covariate annotation with the Set1 palette.
proximity_matrix <- computeProximity( data = df_SAPSSANS, proxType = 1, # Pearson correlation side = 1, # Column-wise isContainMissingValue = 0 )
Seriation and flipping mechanism
Seriation is a key step in GAP, ensuring that similar elements are positioned adjacent to enhance pattern recognition. GAPR provides multiple seriation methods, including the R2E algorithm through ellipse_sort() (see Figure 2) and several variants of HCT, using hctree_sort(). When HCT methods are adopted, the corresponding dendrograms are constructed as additional. In addition, optional flipping strategies (e.g., R2E flipping or external-guide flipping) can adjust subtree orientations to improve visual symmetry.
Figure 2
Matrix layout after applying R2E seriation to the SAPSSANS dataset for both variables and samples. The figure shows clearer block structures compared to the original layout shown in Figure 1.
To further enhance interpretability, GAPR also supports a hybrid strategy known as HCT-R2E, which combines the local grouping ability of HCT with the global structural insight of R2E [19], producing smoother and more coherent layouts. The following code illustrates how R2E can first derive a global ordering that is then integrated into HCT with subtree flipping. This results in an adjusted ordering that balances local clustering with global structure:
r2e_order <- ellipse_sort(proximity_matrix) distance_matrix <- as.dist(1 - proximity_matrix) hctree_result <- hctree_sort( distance_matrix, externalOrder = r2e_order, orderType = 2, # Average-linkage flipType = 1 # Flip based on externalOrder ) avg_r2e_order <- hctree_result$order + 1
Evaluation metrics
While visual inspection is a powerful tool for identifying structure in matrix layouts, it is often subjective and sensitive to interpretation. To provide a more objective basis for evaluating the quality of seriation results, GAPR includes three structural evaluation metrics [19] that quantify the degree to which the reordered proximity matrix conforms to an ideal Robinson form [16]. A Robinson Matrix, denoted as R = [rij], is a symmetric matrix characterized by a monotonicity property where values decrease as they move away from the main diagonal [19, 20]. Formally, this satisfies rij ≤ rik if j < k < i and rij ≥ rik if i < j < k. Violations of this monotonicity condition are referred to as anti-Robinson events. In the context of GAPR, these deviations are quantified using metrics such as the anti-Robinson (AR) score, the generalized anti-Robinson (GAR) score, and the relative GAR (RGAR) score. These scores are computed using distance-based measures, wherein smaller values indicate higher similarity. The AR score calculates the number of triplets that violate the Robinson condition in a fully reordered proximity matrix. Lower values indicate closer conformity to a monotonic structure, making AR a suitable metric for evaluating the overall consistency of global ordering:
The GAR score evaluates local violations within a fixed-width window around each element. By adjusting the window size, GAR can emphasize local consistency or capture more global relationships:
The RGAR score expresses the GAR value relative to the total number of evaluated triplets, yielding a measure ranging from 0, representing no violations of the Robinson condition, to 1, representing all possible violations. By adjusting GAR in this manner, RGAR enables a fair comparison across different window sizes and provides greater resolution in the small-window region:
The following code illustrates how the three evaluation metrics can be computed from a similarity-based proximity matrix using GAPR:
proximity_matrix_sorted <- proximity_matrix[ r2e_order, r2e_order] proximity_matrix_sorted <- as.matrix(as.dist( 1 - proximity_matrix_sorted)) AR_score <- AR(proximity_matrix_sorted) GAR_score <- GAR(proximity_matrix_sorted, w = 5) RGAR_score <- RGAR(proximity_matrix_sorted, w = 5)
Customized and output options
GAPR offers a wide range of visualization and output options to help users tailor the appearance and output of matrix layouts based on their analysis needs. An important feature is color-mapping strategies: the package offers built-in palettes for continuous, categorical, and binary data, consistent with those provided in original GAP software [6]. Figure 3 summarizes the available palettes and their applicable parameters in GAPR. In addition, all palettes from the RColorBrewer package [21, 22] are also supported, offering further flexibility. For instance, Figure 1(e) shows the use of the Set1 palette to illustrate Xd covariate (positive (in red) vs. negative (in blue) symptoms group). Users may also define custom color palettes, as demonstrated in Figure 1(d), showing the Yd covariate with schizophrenia (in magenta) and bipolar disorder (in cyan) patient groups. Missing values can also be highlighted with a user-defined color and their presence tracked via logical parameters (isContainMissingValue).
Figure 3
Built-in color palettes provided by the GAPR package, their spectrum types, and the parameters they are typically used with. 2grayscale palette is a continuous grayscale gradient for binary data, with white = 0 and black = 1.
In addition, GAPR provides layout customization options to refine the clarity and presentation of matrix displays, such as setting label sizes, controlling spacing between the matrices and colorbars, and adjusting borders. The package also supports a variety of output options, allowing users to extract reordered indices, labels, as well as the data and proximity matrices for further analysis or evaluation. The code below illustrates how proximity computation and seriation can be combined with customized visualization and output, with the results shown in Figure 4, ensuring reproducibility and enabling structured evaluation, such as computing anti-Robinson scores from the reordered proximity matrix:
Figure 4
Matrix layout after applying the AVG-R2E seriation method to the SAPSSANS dataset. (a) Column-wise proximity matrix and (b) row-wise proximity matrix, shown as magnified views of selected regions. (c) Complete layout of GAP. Compared to the standard R2E result in Figure 2, this layout refines the ordering by subtree flipping.
magenta_cyan <- c(‘#ff00ff’, ‘#00FFFF’) SAPSSANS_result <- GAP( data = df_SAPSSANS, YdNum = 1, XdNum = 1, Xd.name = ’symptom’, row.prox = ’euclidean’, col.prox = ’pearson’, row.order = ’average’, col.order = ’average’, row.flip = ’r2e’, col.flip = ’r2e’, original.color = ‘Greys’, Xd.color = ’Set1’, Yd.color = magenta_cyan, colorbar.margin = .5, col.label.size = 2, row.label.size = 3, border = T, border.width = 1, exp.row_order = T, exp.column_order = T, exp.row_names = T, exp.column_names = T, exp.Yd_codebook = T, exp.Yd = T, exp.originalmatrix = T, exp.row_prox = T, exp.col_prox = T, PNGfilename = ’~path/SAPSSANS_plot.png’, PNGwidth = 3600, PNGheight = 2400, PNGres = 300, show.plot = T ) AR(SAPSSANS_result$row_prox)
Comparison with Existing R Packages
To assess the practical advantages of the seriation functionality implemented in GAPR, we compare our internal R2E and HCT routines with the corresponding methods available in the widely used seriation package [11, 12].
Although both implementations aim to produce similar ordering results, we focus on two aspects: computational efficiency and design integration. In terms of performance, GAPR is faster than the seriation package, particularly for medium- to large-scale datasets where matrix computations often become bottlenecks. As Table 1 shows, benchmarks on replicated iris datasets (600, 1500, and 10,000 rows) demonstrate that GAPR’s R2E implementation consistently runs faster while yielding identical orderings. All tests were conducted on a desktop with a 12th Gen Intel(R) Core(TM) i7-12700KF CPU, 64GB RAM, and Windows 11.
Table 1
Runtime comparison between GAPR’s C++-based R2E implementation and the R-based version in the seriation package. Benchmarks are conducted using datasets constructed by vertically replicating the iris dataset to create matrices with 600, 1,500, and 10,000 rows, respectively. Both methods yield identical ordering results.
| MATRIX SIZE | METHOD | RUNTIME (SEC) |
|---|---|---|
| 600 × 600 | GAPR::ellipse sort() | 0.14 |
| seriation::R2E | 1.42 | |
| 1500 × 1500 | GAPR::ellipse sort() | 2.37 |
| seriation::R2E | 31.21 | |
| 10000 × 10000 | GAPR::ellipse sort() | 896.45 |
| seriation::R2E | 84945.01 |
From an implementation perspective, we also compare GAPR’s hctree_sort() function with the widely used hclust() function in base R. Since both implementations are compiled—hclust() being written in C and GAPR’s hctree_sort() in C++—their runtime performance is largely comparable, with no substantial difference observed across datasets of similar size. However, the key distinction lies in functionality: GAPR supports flipping to control subtree orientations, refining the ordering so that closely related items are placed together, thereby enhancing the clarity and interpretability of the layout. Moreover, it is directly integrated into GAPR’s visualization pipeline, with dendrograms shown alongside reordered proximity matrices, unlike hclust() and the seriation package, which require external plotting tools. As Table 2 summarizes, GAPR offers a more comprehensive and integrated solution by combining efficient implementations with advanced features such as R2E seriation, flipping, and built-in visualization support. The ability to access both the ordering and full tree structures—together with seamless integration into the visualization pipeline—makes GAPR particularly well-suited for EDA that relies on interpretable MV.
Table 2
Functional comparison of GAPR and selected R packages. 1Seriation package provides HCT-based ordering but does not expose full tree structure for further use. 2These packages provide heatmap-based visualization for a single matrix but do not support an integrated GAP visualization framework with proximity matrices, dendrograms, and covariates.
| FEATURE/CAPABILITY | GAPR | seriation | hclust() | corrplot | pheatmap | ComplexHeatmap |
|---|---|---|---|---|---|---|
| R2E implementation | Yes (C++) | Yes (R) | No | No | No | No |
| HCT | Yes (C++) | Partial1 | Yes (C) | Yes | Yes | Yes |
| Flipping support | Yes | No | No | No | No | No |
| Integrated visualization | Yes | No | No | Partial2 | Partial2 | Partial2 |
Examples
The SAPSSANS dataset
Having demonstrated the main functionalities of GAPR with the SAPSSANS dataset, we now present the empirical results, focusing on the symptom clustering patterns and patient group separations revealed by the package. Proximity matrices are computed using Pearson correlation for variables (symptoms) and Euclidean distance for samples (patients). They are reordered through average-linkage hierarchical clustering with R2E-guided flipping, yielding the AVG-R2E strategy for more informative visualization.
As Figure 4(a) shows, several tightly connected clusters are evident in the column-wise proximity matrix. A positive symptom cluster (in red) (e.g., DL7, DL1, AH1–AH3) encompasses persecutory delusions, auditory hallucinations, and voices commenting. Another cluster (DL8–DL12) reflects cognitive intrusion symptoms such as thought broadcasting, thought insertion, and delusions of mind reading. Thought disorder symptoms (TH1–TH4) also cluster together, forming a coherent disorganization domain. Finally, negative symptoms (in blue) (NA1–NA7, NC1–NC3, ND1–ND4, NB1–NB4) are tightly grouped, including poor eye contact, decreased spontaneous movement, poverty of speech, and physical anergia. These clusters align with established clinical dimensions, illustrating how GAPR effectively captures latent co-expression patterns in psychiatric data.
In addition to revealing symptom co-occurrence patterns, the GAP visualization clearly separates patients by diagnostic status, with the row-wise proximity matrix closely matching the Yd covariate and dividing individuals with schizophrenia (Yd = 1) from those with bipolar disorder (Yd = 0). Notably, as Figure 4(b) shows, individuals with bipolar disorder (in cyan) are grouped more tightly together, indicating greater within-group similarity. If we further examine the column-wise proximity matrix in relation to the data matrix (Figure 4(c)), we observe that the previously mentioned positive symptom cluster (e.g., DL7, DL1, AH1–AH3) and the large cluster of negative symptoms both appear to play a significant role in distinguishing patients with schizophrenia (in magenta) from those with bipolar disorder. Overall, the visualization not only reveals meaningful symptom associations but also demonstrates GAPR’s capacity to differentiate diagnostic groups, underscoring its effectiveness in capturing clinically relevant patterns.
For evaluation, we used the AR, GAR, and RGAR metrics to compare different seriation strategies on the samples (patients), including the standard R2E method, its averaged variant (AVG-R2E), and two alternative algorithms from the seriation package (OLO Average and TSP). As Table 3 shows, the R2E method consistently yields lower AR and RGAR scores than AVG-R2E and other alternatives, indicating stronger preservation of the Robinson structure and producing smoother block patterns. This advantage is confirmed in Figures 5 and 6, where R2E maintains the lowest GAR and RGAR loss scores across window sizes, underscoring its robustness in local order preservation. The numerical superiority of R2E also aligns with the visual contrast between Figures 2 and 4(c), with the former showing clearer block segmentation and less structural noise.
Table 3
Anti-Robinson metrics comparing R2E and AVG-R2E on sample ordering using the SAPSSANS dataset.
| ORDERING METHOD | AR | GAR(w = 5) | RGAR |
|---|---|---|---|
| R2E | 62127 | 831 | 0.224 |
| AVG-R2E | 68466 | 609 | 0.247 |
| seriation::OLO Average | 84484 | 478 | 0.305 |
| seriation::TSP | 114388 | 435 | 0.413 |
Figure 5
Comparison of generalized anti-Robinson (GAR) loss scores across different seriation methods shown in Table 3. The results indicate that R2E consistently achieves lower GAR scores across increasing window sizes for global structure.
Figure 6
Comparison of relative generalized anti-Robinson (RGAR) loss scores across different seriation methods as demonstrated in Table 3. The R2E method consistently achieves the lowest RGAR scores as w increases.
The Wine Quality dataset
To further demonstrate the effectiveness of GAPR on larger datasets and its generalizability across different domains, we next apply it to the Wine Quality dataset from the UCI Machine Learning Repository [23]. The Wine Quality dataset consists of physicochemical measurements and sensory quality tests for red and white wine samples from the Vinho Verde region in northern Portugal. Two related datasets are provided, including 1,599 red wine samples and 4,898 white wine samples. Both datasets contain 11 physicochemical variables and a quality score evaluated by human experts, ranging from 0 to 10. To efficiently reveal the relationships between physicochemical variables and sensory quality, as well as the differences between red wine and white wine, we therefore combined these two datasets into an integrated large dataset. The resulting dataset contains 6,497 samples and 13 variables. Two sample-wise covariates—a discrete covariate (Yd) and a continuous covariate (Yc)—indicate the wine type (red or white) and the quality score. Moreover, since the physicochemical variables, including acidity, alcohol, sugar, density, and pH, are measured in different units and scales, we applied a rank transformation to those variables to ensure comparability and prevent any single variable from dominating the results. It is also possible to transform the data through standardization.
In this case, Pearson correlation is used to compute the column-wise proximity matrix for physicochemical variables (effectively Spearman correlation due to rank transformation), while Euclidean distance is applied to the row-wise proximity matrix for wine samples. Both matrices are reordered through average-linkage hierarchical clustering with R2E-guided flipping.
As Figure 7(a) shows, some physicochemical patterns and relationships among variables can be observed. For instance, sulfates, volatile acidity, chlorides, density, and fixed acidity are grouped together, indicating that these variables have similar variation patterns across wine samples. Moreover, residual sugar, total sulfur dioxide, and free sulfur dioxide form a more coherent cluster, highlighting stronger associations among these variables compared to others. In addition, density has a strong negative correlation with alcohol but a positive correlation with residual sugar. This pattern confirms the fundamental physicochemical principles.
Figure 7
Matrix layout after applying the AVG-R2E seriation method to the Wine Quality dataset. (a) Column-wise proximity matrix and (b) row-wise proximity matrix, shown as magnified views of selected regions. (c) Complete layout of GAP.
In terms of the samples, GAPR reveals a clear separation between red (in magenta) and white (in cyan) wines, together with the reordered row-wise proximity matrix well aligning with the Yd covariate. By considering the column-wise proximity matrix together with the data matrix, as shown in Figure 7(c), we find that our previously observed clusters both play a key role in separating red wines from white wines. Specifically, red wines exhibit higher levels of sulphates, volatile acidity, chlorides, and fixed acidity and lower sulfur dioxide levels, and white wines show the opposite trend. Among the red wine samples, they are further divided into two groups. A comparison between the two groups reveals clear differences in volatile acidity and citric acid, with the first (upper) subgroup showing significantly higher levels of citric acid and the other exhibiting notably lower levels. Similarly, there are two groups within the white wine samples. The first (upper) subgroup has higher alcohol content, lower density, and lower sulfur dioxide levels compared with the other subgroup. In addition, a smaller cluster can be observed within the first group, which has higher alcohol content and lower density than the rest of the first subgroup, and also exhibits relatively higher expert-rated quality scores, as revealed by the Yc covariate. This pattern indicates that higher alcohol content may contribute to improved wine quality, consistent with previous findings [24]. Taken together, the visualization reveals coherent physicochemical structures and meaningful sample-level separations, demonstrating GAPR’s ability to capture wine-type distinctions and quality-related patterns in an interpretable manner. The following code reproduces the results presented in Figure 7(c) and serves as a quick-start guide for the package. Please note that execution may take several minutes depending on your hardware; for reference, it took approximately 10 minutes in our environment due to the dataset size. The computational complexity is roughly O(n2) when using the AVG-R2E seriation method, as the algorithm first computes the R2E measure and subsequently applies it to guide the HCT for the final ordering.
The full source code and detailed implementation are publicly available on GitHub at: https://github.com/shuyyu/GAPR.
# load data df_red <- read.csv(“~path/winequality-red.csv”, sep = ‘;’, header = TRUE) df_red$color <- ‘red’ df_white <- read.csv(“~path/winequality-white.csv”, sep = ‘;’, header = TRUE) df_white$color <- ‘white’ df_wine <- rbind(df_red, df_white) # rank transformation ranked_wine <- as.data.frame( apply(df_wine[, 1:11], 2, function(x) rank(x, ties.method = “average”)) ) ranked_wine$quality <- df_wine$quality ranked_wine$color <- df_wine$color # apply GAP function GAP( data = ranked_wine, YdNum = 13, YcNum = 12, row.prox = ‘euclidean’, col.prox = ‘pearson’, row.order = ‘average’, col.order = ‘average’, row.flip = ‘r2e’, col.flip = ‘r2e’, original.color = ‘Greys’, Yd.color = magenta_cyan, Yc.color = ‘YlGnBu’, colorbar.margin = .5, col.label.size = 6, border = T, show.plot = T )
Quality Control
All functions in GAPR are subjected to systematic testing to ensure correctness, stability, and reproducibility. The whole workflow from data input to visualization was validated through benchmark datasets in R, such as iris and crabs data. This validation covered all functions in the package, including proximity computation, seriation and flipping mechanisms, evaluation metrics, and visualization customization and output options. Performance validation is further conducted using iris data, confirming that GAPR not only produces results identical to existing implementations but also achieves significant speed improvements on medium- to large-scale datasets.
Furthermore, the package has passed the standard R CMD check process on CRAN with no errors, warnings, or notes, ensuring compliance with the quality requirements of the R ecosystem. To enhance users’ understanding, the package includes detailed documentation and reproducible examples for each function. The Wine Quality dataset example provided in this paper can be directly reproduced by users to confirm the functionality of the package.
(2) Availability
Operating System
The package is cross-platform and has been tested on Windows, macOS, and Linux.
Programming Language
R (≥4.1.0)
Additional System Requirements
CPU: Modern multi-core processor (tested on Intel i7-12700KF)
Memory: At least 16 GB RAM for moderate datasets; 64 GB RAM recommended for large-scale analyses
Disk: Sufficient disk space for intermediate files and exported visualizations (several GB recommended)
Operating System: Windows, Linux, or macOS (tested on Windows 11)
Dependencies
The GAPR package depends on Rcpp, ComplexHeatmap, RColorBrewer, gridExtra, grid, dendextend, circlize, seriation, and magick. The MASS package is listed under Suggests. All dependencies are available from CRAN.
List of Contributors
The package was developed by Shu-Yu Lin (Academia Sinica), Chiun-How Kao (Tamkang University), and Chun-Houh Chen (Academia Sinica). Shu-Yu Lin led the package design, implementation, and documentation. Chiun-How Kao contributed to algorithm development, testing, and validation. Chun-Houh Chen first proposed the rank-2 ellipse (R2E) and the generalized association plots (GAP) framework.
Software Location
Archive Name: CRAN
Persistent identifier: https://CRAN.R-project.org/package=GAPR
Licence: MIT + file LICENSE
Publisher: Shu-Yu Lin
Version published: 0.1.5
Date published: 01/28/2026
Code repository (e.g. SourceForge, GitHub etc.) (required)
Name: GitHub
Persistent identifier: https://github.com/shuyyu/GAPR
Licence: MIT + file LICENSE
Date published: 05/11/2025
Language
English
(3) Reuse potential
The GAPR package can be reused by researchers in diverse domains, from survey sampling to medical and physicochemical datasets, in cases where continuous or ordinal data are analyzed. Its core strength lies in revealing structural patterns, making it suitable for EDA of complex datasets. Moreover, GAPR offers flexibility in various parts of the workflow. Users can provide custom flipping orders, user-defined color palettes, and specific row names to tailor the visualization to their analytical needs. In addition, the package’s output options, such as reordered matrices and indices, and covariate mappings, can be directly reused for downstream statistical modeling or visualization. Beyond the examples illustrated in this paper, GAPR can thus be adapted to different scientific contexts where interpretable ordering and MV are needed. For very large matrices, the performance of GAPR primarily depends on available memory and the computational cost of proximity computation and seriation. To evaluate the limits of GAPR, we conducted experiments using a vertically replicated iris dataset (with 32,000 rows and 4 columns) on a desktop equipped with a 12th Gen Intel(R) Core(TM) i7-12700KF CPU, 64 GB RAM, and Windows 11. Table 4 summarizes the runtime of the four main ordering methods from proximity computation to visualization. For reference, we also tested the same ordering methods on the standard iris dataset (150 rows and 4 columns). Our empirical evaluation also reveals several limitations in visualization. First, due to the fixed display resolution of the matrices, extremely large datasets cannot be fully represented, as each pixel may correspond to multiple rows. Correspondingly, when using HCT-based seriation, dendrogram structures are partially compressed, further reducing interpretability for very large matrices. Feature requests and feedback can be submitted through the GitHub repository.
Acknowledgements
The authors acknowledge Hai-Gwo Hwu for providing the psychosis disorder dataset (the SAPSSANS dataset) analyzed in this study.
Competing Interests
The authors have no competing interests to declare.