Type: Package
Title: Scatter Plot Combined with Ridgelines in 'ggplot2'
Version: 1.1.0
Date: 2025-09-17
Maintainer: Matthieu Bourgery <matthieu.bourgery@gmail.com>
Imports: ggplot2, cowplot, ggridges, ggrepel, vegan, RColorBrewer
Description: The function combines a scatter plot with ridgelines to better visualise the distribution between sample groups. The plot is created with 'ggplot2'.
License: GPL-3
URL: https://github.com/matbou85/ggScatRidges,
BugReports: https://github.com/matbou85/ggScatRidges/issues
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-09-17 11:53:51 UTC; matt
Author: Matthieu Bourgery ORCID iD [aut, cre]
Depends: R (≥ 4.1.0)
Repository: CRAN
Date/Publication: 2025-09-17 13:50:02 UTC

Scatter Plot Combine with Ridgelines

Description

‘ggScatRidges' is a simple function combining a scatter plot generated in ’ggplot2' to a ridgeline plot from 'ggridges' to visualise the disparities of the data points. This helps visualising the distribution of different groups in the data.

Usage

ggScatRidges(
  x,
  y = NULL,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  xlim = NULL,
  ylim = NULL,
  group = NULL,
  color = "Set1",
  ridges = TRUE,
  base_size = 15,
  size = 2,
  pch = NULL,
  draw = TRUE,
  density_2d = TRUE,
  legend = TRUE,
  label = FALSE,
  legend.title = NULL,
  stats = FALSE,
  stats_method = "eu",
  anno_size = 6,
  anno_pos = "Up",
  text = NULL
)

Arguments

x

As input data. If a dataframe was provided, the dataframe should contain no less than three columns. If no dataframe was supplied, a x vector should be set as an input. The vector should #' contain numerical values.

y

As input data. If no dataframe was provided, a y vector should be set as an input along with a x vector. The vector should contain numerical values.

xlab

To give a title for the xlab can be given here.

ylab

To give a title for the ylab can be given here.

title

To give a title for the plot can be given here.

xlim

To set scale limits on the xaxis.

ylim

To set scale limits on the yaxis.

group

The user should provide here the grouping of the rows if a dataframe was provided, otherwise a vector.

color

The user can choose from 'display.brewer.all()'. Default = "Set1".

ridges

The user can choose to plot, or not, the ridgelines. Default = TRUE.

base_size

The overall size of the text in the plot. Default = 15.

size

The size of the dots in the plot. Default = 3.

pch

The user can change the shape of the points by providing a vector length equal to the number of groups.

draw

If the user wants to directly draw the plot. Default = TRUE.

density_2d

If the user wants to add density contours around group of points on the plot. Default = TRUE.

legend

If the user wants to add or remove the legend. Default = TRUE.

label

If the user wants to add custom labels for each point. Default = FALSE.

legend.title

The user can provide its own title.

stats

If the user wants to add a permanova statistical test. Default = FALSE.

stats_method

The user can choose the method from 'vegan::vegdist' to calculate pairwise distances. Default = "eu.

anno_size

To set the font size of the statistical test results. Default = 6.

anno_pos

To define where the statistical test results will be displayed on the graph. Default = "Up".

text

The user can give a vector to add labels or directly provide it as a fourth column from a dataframe.

Value

A ggplot object if draw set to 'TRUE' otherwise a grob table is returned but set to invisible.

Examples

# The following example is based on the iris dataset:

## Example 1
ggScatRidges(x = iris$Sepal.Length, y = iris$Sepal.Width, group = iris$Species,
             color = "Set3", ridges = TRUE, title = "plot iris", legend.title = "Grouping",
             xlab = "Sepal.Length", ylab = "Sepal.Width", base_size = 15, size = 2, 
             draw = TRUE, density_2d = TRUE, legend = TRUE, label = FALSE, text = NULL,
             stats = FALSE)

## Example 2
iris2 <- iris[,c(1,2,5)] #The 1st column will be used as 'x', the 2nd as 'y', and the 3rd as group.
ggScatRidges(x = iris2, 
             color = "Set2", ridges = TRUE, title = "plot iris",
             xlab = "Sepal.Length", ylab = "Sepal.Width", size = 2, draw = TRUE,
             density_2d = FALSE, legend = TRUE, label = FALSE, stats = TRUE)