Visualise distance matrices using polar area plots from ggplot2. Due to the nature of polar area plots, it is impossible to visualise all distances on the same plot. So the output of the function will be a number of polar area plots, one for each sample in the input matrix. Each plot visualises a distance from the specific samples to other samples in the dataset.

  .by = NA,
  .meta = NA,
  .ncol = NA,
  .which = NA,
  .errorbars = c(0.025, 0.975), = F,
  .expand = c(0.25, 0),
  .title = NA,
  .subtitle = NULL,
  .legend = F,
  .leg.title = NULL,



Input matrix.


Pass NA if you want to plot samples without grouping.

You can pass a character vector with one or several column names from ".meta" to group your data before plotting. In this case you should provide ".meta".

You can pass a character vector that exactly matches the number of samples in your data, each value should correspond to a sample's property. It will be used to group data based on the values provided. Note that in this case you should pass NA to ".meta".


A metadata object. An R dataframe with sample names and their properties, such as age, serostatus or hla.


An integer number of columns to display. Provide NA (by default) if you want the function to automatically detect the optimal number of columns.


A character vector with sample names. Samples not presented in the vector will be filtered out and will not be displayed in the resulting plot.


A numeric vector of length two with quantiles for error bars on sectors. Disabled if "" is TRUE.

If TRUE then plot CI bars for distances between each group. Disabled if no group passed to the ".by" argument.


Passed to ggplot2's scale_y_continuous argument "expand".


The text for the title of the plot.


The text for the subtitle of the plot. Provide NULL if you want to remove it.


If TRUE then plots the legend, otherwise removes the legend from the plot.


The text for the legend of the plot. Pass NULL if you want to remove it.


Do not provide anything here.