isProximityMatrix
If isProximityMatrix = TRUE, you may directly provide a proximity matrix as the input data.
In this case, only row-based settings will be applied, such as row.order, row.flip, and row.externalOrder.
Note that correlation matrices (e.g., "pearson") must be converted to distance matrices before being used,
and the selected color scheme must also be one of the supported diverging palettes (e.g., "GAP_Blue_White_Red", "BrBG", "PiYG", "PRGn", "PuOr", "RdBu", "RdGy").
XdNum, XcNum, YdNum, YcNum
These parameters are used to specify which columns in data should be treated as covariates
on the X or Y axes. Provide the column indices (e.g., XdNum = c(3, 5)) of discrete or continuous variables.
Xd.name, Xc.name
If not provided, the default labels will be a sequence of numbers based on the number of selected variables (e.g., "1", "2", ..., up to the length of XdNum or XcNum).
row.name
This parameter can be:
A character vector providing custom row names.
An integer (column index) indicating a column in data to be used as row names.
If row.name = NULL, the row names will be automatically generated as 1:nrow(data).
row.prox, col.prox
Available proximity methods for row.prox and col.prox include:
For binary data, the following methods are supported:
"hamman"
"jaccard"
"phi"
"rao"
"rogers"
"simple"
"sneath"
"yule"
show.row.prox, show.col.prox
If set to TRUE, the corresponding proximity matrix will be visualized.
If set to FALSE, the proximity matrix will not be shown, but the associated proximity and ordering methods will still be applied.
In such cases, the dendrogram (tree structure) will appear alongside the original plot, reflecting the proximity-based ordering.
row.order, col.order
The ordering method determines how the rows or columns are reordered. Supported options include:
"original" — Use the original data order.
"random" — Randomly permute the order.
"reverse" — Reverse the original order.
"r2e" — Rank-two ellipse ordering.
"single" — Single-linkage hierarchical clustering.
"complete" — Complete-linkage hierarchical clustering.
"average" — Average-linkage hierarchical clustering (UPGMA).
any method name from the seriation package — such as "TSP", "Spectral", "ARSA", etc.
If the ordering method is "original", "random", or "reverse", then proximity matrices are not required,
and the parameters row.prox or col.prox may be left unset.
For all other ordering methods, a proximity matrix must be computed first.
Therefore, row.prox or col.prox must be specified accordingly.
Note: it is necessary to explicitly specify one of the valid ordering options; the function does not assume a default.
row.flip, col.flip
Supported flipping methods include:
"r2e" — Flip using the rank-two ellipse (R2E) method.
"uncle" — Apply uncle-flipping based on tree structure.
"grandpa" — Apply grandpa-flipping based on tree structure.
Usage restrictions:
Flipping is only applicable when a hierarchical clustering tree is generated.
Therefore, if row.order or col.order is set to "original", "random", "reverse", "r2e", or a seriation method,
tree structures are not built and flipping cannot be applied.
When using "r2e" as the ordering method, only "r2e" flipping is allowed. "uncle" or "grandpa" flipping will be ignored.
Do not specify both externalOrder and flip at the same time. These options are mutually exclusive. If both are provided, the function will throw an error.
row.externalOrder, col.externalOrder
External orders are used as references when flipping the hierarchical clustering tree.
If a tree is available, the external order guides the flipping of the dendrogram’s leaf nodes to better match a predefined sequence.
Important:
Do not use externalOrder together with flip; they are mutually exclusive.
Color settings
The function supports a variety of color palette options for visualizing the original matrix, proximity matrices, and covariate matrices.
Supported built-in palettes include:
"GAP_Rainbow"
"GAP_Blue_White_Red"
"GAP_d"
"grayscale_palette"
You may also specify any palette name from the RColorBrewer package.
However, note that some palettes—such as those under the "Qualitative" category—are not suitable for visualizing continuous data like proximity matrices.
All palette names must be passed as character strings (e.g., "GAP_Rainbow", "Set1").
original.color:
The system will automatically determine the appropriate default color palette based on data type.
If the input data is binary, the default is a grayscale palette; otherwise, it defaults to "GAP_Rainbow".
row.color, col.color:
The system chooses a default palette based on the proximity method used.
For distance-based methods (e.g., "euclidean", "city-block"), the default is "GAP_Rainbow".
For correlation-based methods (e.g., "pearson", "spearman"), the default is "GAP_Blue_White_Red".
Xd.color, Yd.color (discrete covariates):
The default color palette is "GAP_d", which supports up to 16 distinct categories.
If there are more than 16 unique levels, a custom palette should be provided by the user.
Label size settings
Font sizes for axis labels and covariate matrices can be customized individually.
Default values are:
row.label.size: 2
col.label.size: 8
Xd.label.size, Xc.label.size, Yd.label.size, Yc.label.size, Xc.label.size: 8
You may increase or decrease these values to improve readability depending on figure size and resolution.
Export-related options (exp.*)
When any of the exp.* parameters are set to TRUE, the corresponding data will be stored in a list and returned by the function.
This allows users to programmatically retrieve the order, reordered matrix, proximity matrices, covariate data, or codebooks after plotting.
PNG output settings
The following parameters control the export of the PNG image:
PNGfilename: The name of the PNG file to be saved.
The file extension .png must be included manually (e.g., "myplot.png").
If no file path is specified, the image will be saved in a system-generated temporary directory (via tempdir()) using the default filename "output_plot.png".
To save the image to a specific location, provide the full path (e.g., "C:/.../myplot.png").
PNGwidth: Width of the output image in pixels. Default = 1800.
PNGheight: Height of the output image in pixels. Default = 1200.
PNGres: Resolution (dots per inch, DPI). Default = 150.