Package {tRowel}

Version: 0.1.0
Date: 2026-10-18
Title: Cluster and Plot Soil, Sediment, and Paleoenvironmental Data
Depends: R (≥ 4.5)
Imports: ape (≥ 5.8-1), cluster (≥ 2.1.8.1), dplyr (≥ 1.1.4), factoextra (≥ 1.0.7), gawdis (≥ 0.1.5), ggplot2 (≥ 4.0.0), jpeg (≥ 0.1-11), magrittr (≥ 2.0.4), munsellinterpol (≥ 3.2-0), patchwork (≥ 1.3.2), png (≥ 0.1-8), rlang (≥ 1.3), tidyselect (≥ 1.2.1), tidyr (≥ 1.3.1)
Description: Functions to help geoarchaeologists, paleoenvironmental scientists, and geoscientists create clear, publication-ready figures of soil data without the need for additional licensed software. Functions allow users to cluster and visualize across multiple soil profiles, allowing geoarchaeologists to recognize and compare geomorphological and paleoenvironmental trends across entire landscapes.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
LazyData: true
Encoding: UTF-8
Suggests: knitr, rmarkdown, testthat
VignetteBuilder: knitr
URL: https://github.com/gwenolivier/tRowel
BugReports: https://github.com/gwenolivier/tRowel/issues
Config/roxygen2/version: 8.1.1
NeedsCompilation: no
Packaged: 2026-10-22 22:09:55 UTC; sam
Author: Gwen Olivier ORCID iD [aut, cre], Samuel R. Borstein ORCID iD [aut]
Maintainer: Gwen Olivier <gwen_olivier@txstate.edu>
Repository: CRAN
Date/Publication: 2026-11-08 17:00:02 UTC

Inambari Region Amazonian Dark Earths soil dataset

Description

Data ffor the Inambari Region from the Amazonian Dark Earths soil dataset of Demetrio et al. (2021).

Usage

InambariRegion

Format

A data frame of of 50 rows and 36 columns

References

Plots proxies with a bar plot

Description

Plots proxies with a bar plot

Usage

buriedBar(
  pollendata,
  proxies,
  depth,
  title = NULL,
  barcolors = NA,
  legendtitle = NULL,
  value_pos = TRUE,
  legend_pos = TRUE,
  measurement_lab,
  depth_lab = NA,
  depth_axis = TRUE,
  top_is_zero = TRUE,
  depth_intervals = 10,
  min_depth = 0,
  max_depth,
  min_measure = NA,
  max_measure = NA,
  measure_intervals = NA,
  panel_format = "single"
)

Arguments

pollendata

Dataframe of paleoenvironmental data.

proxies

Columns to be plotted.

depth

Character. Name of column containing starting depth data.

title

Character. Name of plot.

barcolors

Character Vector. Assigned colors for bar plot.

legendtitle

Character. Title of legend in plot.

value_pos

Boolean. TRUE places X-axis labels at the bottom of the plot

legend_pos

Boolean. TRUE places the legend at the top of plot

measurement_lab

Character. Label for the X-axis

depth_lab

Character. Label for the Y-axis. Default is the name of the depth column.

depth_axis

Should the depth axis be plotted. Default is TRUE.

top_is_zero

Boolean. If TRUE, the top of the plot will have a depth of 0. If FALSE, the top of plot will be max depth.

depth_intervals

Numeric. Sets the intervals for the Y-axis. Default is 10.

min_depth

Numeric. Minimum depth of the dataset. Default is 0.

max_depth

Numeric. Required maximum depth for the Y-axis. Allows the user to extend the graph to match other depths in paleoPanel(). For a shorter graph, the user must filter the data.

min_measure

Numeric. Adjusts X-axis min number.

max_measure

Numeric. Adjusts X-axis max number.

measure_intervals

Numeric. Adjusts X-axis intervals.

panel_format

Format for plotting. Can be either panel or single. If single, elements are all plotted on the same plot. If panel, the plot will be constructed as a facet plot. Default is single.

Details

This function plots a side-by-side bar graph to analyze and compare the quantity of pollen (or other proxy) by depth.

Value

A bar plot of pollen amounts.

Author(s)

Gwen Olivier

Examples

# example code
data("testPit")
#filter for one profile, in this case profile 5
testPitP5 <- dplyr::filter(testPit, ProfileID == "Profile_5")
buriedBar(testPitP5, proxies = c("Ca","Mg"),depth = "Depth_cm_Start", measurement_lab = "PPM",
max_depth = 140, top_is_zero = TRUE, barcolors = c("blue","green"))

#plot each element in its own panel
buriedBar(testPitP5, proxies = c("Ca","Mg"),depth = "Depth_cm_Start", measurement_lab = "PPM",
max_depth = 140, top_is_zero = TRUE, barcolors = c("blue","green"), panel_format = "panel",
title = "Panel Plot")

Statistically cluster (Gower's or Euclidean) and graphically display soil/sediment data as a profile

Description

Statistically cluster (Gower's or Euclidean) and graphically display soil/sediment data as a profile

Usage

clastCluster(
  dirtdata,
  distance,
  depthStart,
  depthEnd,
  profile = NULL,
  ordination = FALSE,
  minK = 2,
  maxK = 10,
  nstart = 50,
  plot = TRUE,
  depthticks = 10,
  minDepth = 0,
  maxDepth = NULL,
  clusterColors = c("#DCC7AA", "#A68A6D", "#6E5A48", "#D29F6C", "#E8D3A1", "#4F4336",
    "#AAB8B4", "#4A615D", "#B3A79E", "#8B3A1C", "#C15629"),
  profileOrder = NULL,
  profileName = NULL,
  plotTitle = NULL,
  labelOrientation = 45,
  scaleData = TRUE,
  weight = "equal",
  groups = NULL
)

Arguments

dirtdata

Data frame containing soil characteristic data for clustering.Should have unique rownames.

distance

Character. Either Euclidean or Gower. If you have only numeric data, use Euclidean. If your data contains a mix of data types, use Gower.

depthStart

Character. Name of the column in dirtdata containing information on the starting depth of sample.

depthEnd

Character. Name of the column in dirtdata containing information on the ending depth of sample.

profile

Character. Name of column containing profile IDs if multiple soil profiles exist in dirtdata. If a single profile, set to Null. Default is NULL (i.e. a single profile).

ordination

Logical. Should an ordination of the data be performed and plotted. Default is FALSE. If distance = Euclidean, Principle Component Analysis (PCA) is performed. If distance = Gower, a Principle Co-ordinate Analysis (PCoA) is performed.

minK

Numeric. Minimum number of clusters to try. Default is 2.

maxK

Numeric. Maximum number of clusters to try. Must be less than the number of rows in dirtdata. Default is 10.

nstart

Numeric. Number of random starts to be used in clustering algorithm.

plot

Logical. Should profile cluster plots be generated. Default is TRUE.

depthticks

Numeric. Interval for plotting depth. Default is 10.

minDepth

Numeric. Minimum depth to be used in plotting. Default is 0.

maxDepth

Numeric. Maximum depth to be used in plotting. Default is NULL.

clusterColors

Character. Colors to be used in plotting. Default is random soil-like colors.

profileOrder

Character. Order in which to plot profiles if multiple soil profiles are present in dirtdata.

profileName

Character. If a single profile. What should profile be named? Default is Null.

plotTitle

Character. Title for ordination plots. Default is NULL.

labelOrientation

Numeric. Controls angle of orientation of axis labels.

scaleData

Logical. For Euclidean, should data be scaled prior to clustering.

weight

Character. Type of weighting to be used if distance is Gower. See options in gawdis::gawdis. Default is equal to handle NA values.

groups

Numeric vector. Vector of trait groupings that are considered to represent related soil information (i.e. L, a, b). By default each trait is treated separately (groups = NULL). In order to define groups use the same values, e.g. groups = c(1,2,2,2,3,3) in case of 6 variables attributed to 3 groups, with the length of vector that should be the same as the number of variables in the dataset.

Value

A list Containing the data and plots.

Author(s)

Gwen Olivier, Samuel R. Borstein

Examples



data("testPit")
#Prep data
testPit_withMun <- munsling(testPit, munsellCol = "Munsell")
testPitM <- testPit_withMun
testPitM <- select(testPitM, -c(Munsell) )
#Example using Euclidean distance and PCA
EuclidExample <- clastCluster(dirtdata = testPitM, distance = "E", depthStart = "Depth_cm_Start",
 depthEnd = "Depth_cm_End", profile = "ProfileID", ordination = TRUE, plot = TRUE, maxDepth = 150,
  depthticks = 10)

#Example using Gower's distance and PCoA
GowerExample <- clastCluster(dirtdata = testPitM, distance = "G",depthStart = "Depth_cm_Start", 
  depthEnd = "Depth_cm_End", minK = 2, maxK=8, profile = "ProfileID", ordination = TRUE, 
  plot = TRUE, plotTitle="Cluster Analysis of Arroyo Profiles", maxDepth = 150, depthticks = 10,
  weight = "optimized", groups = c(1,1,1,2,2,3,3,4,5,5,5,5,5,5,5,5,5,5,5,6,6,6))

Prepare your soil/sediment picture for use in paleoPanel

Description

This function saves your soil/sediment pic as a ggplot object, so when you can combine it with other plots in paleoPlot.

Usage

groundTruth(imagefile, imageformat = "png", width, height, WHratio)

Arguments

imagefile

Name of file containing a picture of the soils/sediment

imageformat

File format of imagefile. Should be either png or jpg.

width

Numeric. Width for scaling picture for ggplot plotting

height

Numeric. Width for scaling picture for ggplot plotting

WHratio

the width to height ratio of your image. tRowel recommends you look up the pixel width and height of the actual image description

Value

Plot containing selected image to be used in paleoPanel.

Author(s)

Gwen Olivier, Samuel R. Borstein

Examples

file_path <- system.file("extdata", "groundTruth.png", package = "tRowel")
groundTruth(file_path, imageformat = "png", width = 10, height = 10, WHratio = 1)

Plots composition of sand, silt, and clay in soil

Description

Plots composition of sand, silt, and clay in soil

Usage

loamRanger(
  dirtdata,
  depth,
  sand,
  silt,
  sandcolor,
  siltcolor,
  claycolor,
  depth_title = NA,
  depth_intervals = 10,
  mindepth = 0,
  maxdepth = NA,
  title = NA
)

Arguments

dirtdata

Dataframe of soil data.

depth

Character. Name of column containing starting depth data.

sand

Character. Name of column containing sand composition data.

silt

Character. Name of column containing silt composition data.

sandcolor

Character. Color to represent sand in plot.

siltcolor

Character. Color to represent silt in plot.

claycolor

Character. Color to represent clay in plot.

depth_title

Character. Label for axis representing depth. Default is NA.

depth_intervals

Numeric. Interval for plotting depths. This default value of this argument is 10.

mindepth

Numeric. Starting depth for the plot. The default value is 0.

maxdepth

Numeric. Sets maximum depth for the plot. Default is NA.

title

Character. Title to be added to the plot.

Details

This function plots the composition of soils by the percent representation of clay, silt, and sand. The user needs to specify a dataframe with column names containing the data and then specify the columns that contain the percent composition for sand and silt. Clay is caluclated as the remainder.

Value

A plot of the soil composition with the percent representation of clay, silt, and sand.

Author(s)

Gwen Olivier

Examples

# example code
data("testPit")
testPit2 <- testPit[testPit$ProfileID == "Profile_1",]
loamRanger(testPit2, depth = "Depth_cm_Start", sand = "Sand_pct", silt = "Silt_pct", 
  sandcolor = "blue" ,siltcolor = "green", claycolor = "purple", mindepth=0, title = "Texture")

Converts a Munsell specification to CIE Lab coordinates for clustering

Description

Converts a Munsell specification to CIE Lab coordinates for clustering

Usage

munsling(dirtData, munsellCol, whiteVal = "D65")

Arguments

dirtData

A dataframe with a column that has Munsell colors (i.e., 10YR 2/1)

munsellCol

The column name with Munsell colors (must be a character and properly formatted (i.e., 10YR 2/1 NOT 10YR2/1)

whiteVal

XYZ for the source white - a numeric 3-vector with scaling irrelevant. white can also be a numeric 2-vector; which is interpreted as xy chromaticity and converted to XYZ with Y=100. white can also be the name of any standard illuminant recognized by spacesXYZ::standardXYZ() which is scaled so that Y=100. The default 'D65' is converted to c(95.047,100,108.883). see MunsellToLab::munsellinterpol.

Details

This function saves the columns to your original dataframe stored in R. Your new df will look the exact same with three new columns (L, a, b). L, a, and b represent the values for CIE colors with L for perceptual lightness and a and b for the four unique colors of human vision.

Value

This function will return the original dataframe with new L, a, b columns

Author(s)

Gwen Olivier, Samuel R. Borstein

Examples

data(testPit)
MunsellClusterData <- munsling(dirtData = testPit, munsellCol = "Munsell")

Plots multiple existing figures/plots to create a panel of figures

Description

Plots multiple existing figures/plots to create a panel of figures

Usage

paleoPanel(
  ...,
  profile = NULL,
  rows = 1,
  cols,
  label_angle = 0,
  border = FALSE,
  bordercolor = "darkgrey",
  marginsize = 0,
  plotwidths = NULL
)

Arguments

...

fig. This argument provides unlimited space to upload as many figure/plot names as needed. They plot in the order that they are uploaded.

profile

fig. Input the figure name created in groundTruth to add a stratigraphic photo to the front of the panel figure

rows

Numeric. Number of rows for the panel figure, defaults to 1 row.

cols

Numeric. Number of columns to format the panel figure. If you are using 1 row, make sure this is equal to the number of plots inputted

label_angle

Numeric. The angle of X axis labels

border

Boolean. If TRUE, the panel figure will have a border

bordercolor

Character. If border = TRUE, what color should plotted border be. Default is darkgrey.

marginsize

Numeric. Adjusts the margin size between the figures

plotwidths

Numeric Vector. Assists in adjusting the spacing when the profile argument is not NA. Input two numbers (i.e., plotwidths = c(1,5)), the first number reflects the width of the profile argument, and the second number reflects the width of panel figures.

Details

This function plots multiple existing figures/plots to create a multi-figure panel plot. The user needs to upload figure names (with correct y-axis labels [i.e., some may only want the first figure label to have depth]) If adding a profile figure, the groundTruth function must be performed first

Value

A figure that formats multiple plots

Author(s)

Gwen Olivier

Examples

#Make groundTruth figure
file_path <- system.file("extdata", "groundTruth.png", package = "tRowel")
GT.fig <- groundTruth(file_path, imageformat = "png", width = 10, height = 10, WHratio = 1)

#Make buriedBar
data("testPit")
#filter for one profile, in this case profile 5
testPitP5 <- dplyr::filter(testPit, ProfileID == "Profile_5")

buriedP5 <- buriedBar(testPitP5, proxies = c("Ca","Mg"),depth = "Depth_cm_Start", 
  measurement_lab = "PPM", max_depth = 140, top_is_zero = TRUE, barcolors = c("blue","green"))

#Make terrTrend plot
terraP5 <- terraTrend(testPitP5, depth = "Depth_cm_Start", linecolors = c("red","purple"), 
              max_depth = 140, proxies = c("Ca","Mg"), measurement_lab = "PPM",legendtitle = 
              "Elements", depth_lab = "Depth (cm)")

#plot with soil picture included
paleoPanel(terraP5,buriedP5,cols = 2, profile = GT.fig, plotwidths = c(1,2))

#plot without soil picture included
paleoPanel(terraP5,buriedP5,cols = 2)

Calculate Element Ratios

Description

Calculate Element Ratios

Usage

ratioRustler(df, numerator, denominator, new_col = NULL, removeNAs = TRUE)

Arguments

df

A data frame

numerator

Vector or list of vectors. Column(s) in the numerator (if user selects multiple columns, the function takes the sum of all columns). If provided as a list, multiple ratios can be calculated.

denominator

Vector or list of vectors. Column(s) in the denominator (if user selects multiple columns, the function takes the sum of all columns). If provided as a list, multiple ratios can be calculated. If the denominator value is zero, it'll place an NA

new_col

Character. Option to add a name for the new ratio column. If NULL, the function will generate a name. If lists are provided for ratio calculations, new_col must be the same length. Default is NULL (i.e. function generates names for you).

removeNAs

Logical - defaults to TRUE (meaning it will remove any NAs from the selected columns)

Value

A copy of your data frame with the new ratio column. Save the function to a data frame to save the data in your environment (i.e., df_with_ratio <- ratioRustler(df, numerator, denominator))

Author(s)

Gwen Olivier, Samuel R. Borstein

Examples

#Example with list input
nums <- list(c("Fe","Ca"),"Al", "Si")
denoms <- list("K","P",c("Sr","Fe"))
data("testPit")
ratioRustler(df = testPit, numerator = nums, denominator = denoms, new_col = NULL, 
removeNAs = TRUE)

#Example with vector input while specifying name of new column
ratioRustler(df = testPit, numerator = "Fe",denominator = "Ca", new_col = "MyRatio", 
removeNAs = TRUE)

Plot proxy trends

Description

Plot proxy trends

Usage

terraTrend(
  dirtdata,
  depth,
  title = NULL,
  linecolors = NA,
  legendtitle = NA,
  value_pos = TRUE,
  legend_pos = TRUE,
  measurement_lab,
  depth_lab = NA,
  depth_axis = TRUE,
  top_is_zero = TRUE,
  depth_intervals = 10,
  min_depth = 0,
  max_depth,
  min_measure = NA,
  max_measure = NA,
  measure_intervals = NA,
  proxies
)

Arguments

dirtdata

Dataframe of soil/sediment/geologic data.

depth

Character. Name of depth column in dirtdata.

title

Character. Name for the title of the plot. Default = NULL.

linecolors

Character. Specified line colors for the plotted trends. Must be the same length as proxies. Default is NA, in which random colors will be assigned.

legendtitle

Character. Name for the title of the legend. Default = NA.

value_pos

Logical. This argument is set to TRUE, so the x axis and labels will be at the bottom. If you want it at the top, change it to value_pos = FALSE

legend_pos

Logical. This argument is set to TRUE, so it will place the legend at the top. If you want it at bottom, change it to legend_pos = FALSE

measurement_lab

Character. Sets the label for the x-axis.

depth_lab

Character. This argument is set to NA, so it will put the name of your depth column here. However, if you want to change it you can type depth_lab = “Depth(cm)” or whatever you’d like.

depth_axis

Logical. This argument is set to TRUE, so your plot will have the depth label and axis ticks. If you’d like to remove it for a future multipanel plot, then set it to FALSE.

top_is_zero

Logical. This argument is set to TRUE, so 0 is at the top of the graph, and max depth is at the bottom. If you’d like to switch it, type top_is_zero = FALSE.

depth_intervals

Numeric. Interval for plotting depths. The default value of this argument is 10.

min_depth

Numeric. Starting depth for the plot. The default value is 0.

max_depth

Numeric. Sets maximum depth for the y axis of the plot. You must provide a value.

min_measure

Numeric. Adjusts x-axis minimum number.

max_measure

Numeric. Adjusts x-axis maximum number.

measure_intervals

Numeric. Adjusts x-axis intervals.

proxies

Character. Proxies to be plotted. These should be column names in dirtdata and must match exactly.

Value

A plot of soil proxy trends.

Author(s)

Gwen Olivier, Samuel R. Borstein

Examples

#filter for one profile, in this case profile 5
data(testPit) 
testPitP5 <- dplyr::filter(testPit, ProfileID == "Profile_5")
terraP5 <- terraTrend(testPitP5, depth = "Depth_cm_Start", linecolors = c("red","purple"), 
              max_depth = 140, proxies = c("Ca","Mg"), measurement_lab = "PPM",legendtitle = 
              "Elements", depth_lab = "Depth (cm)")

Plots clastCluster data with landscape elevation

Description

Plots clastCluster data with landscape elevation

Usage

terraceWrangler(
  clastData,
  elevData,
  surfaceElevM,
  profileClast,
  profileElev,
  depthticksM = 1,
  clusterColors = c("#DCC7AA", "#A68A6D", "#6E5A48", "#D29F6C", "#E8D3A1", "#4F4336",
    "#AAB8B4", "#4A615D", "#B3A79E", "#8B3A1C", "#C15629"),
  title = NULL,
  xLabel = NULL,
  yLabel = "Depth (m)"
)

Arguments

clastData

Enter clastCluster data from the saved clastCluster list in environment

elevData

Data frame. Name of the df containing Profile Name and Elevation columns

surfaceElevM

Name of the column containing elevation (meters only) in elevData

profileClast

Name of the profile ID column in clastData

profileElev

Name of the profile ID column in elevData

depthticksM

Numeric. The displayed numeric intervals of the depth axis, the default is 1 meter

clusterColors

Character. Colors to be used in plotting. Default is random soil-like colors.

title

Character. Title of plot

xLabel

Character. Title of profile axis

yLabel

Character. Title of depth axis, the default is "Depth (m)"

Details

This function plots the data from clastCluster with elevation. You must complete clastCluster before using this function.

Value

A cluster plot demonstrating clusters by depth while including the elevation

Author(s)

Sam Borstein, Gwen Olivier

Examples



data("testPit")#load testPit data
#Prep data
testPit_withMun <- munsling(testPit, munsellCol = "Munsell")
testPitM <- testPit_withMun
testPitM <- select(testPitM, -c(Munsell) )
#Example using Euclidean distance and PCA
EuclidExample <- clastCluster(dirtdata = testPitM, distance = "E", depthStart = "Depth_cm_Start",
  depthEnd = "Depth_cm_End", profile = "ProfileID", ordination = TRUE, plot = TRUE, maxDepth = 150,
  depthticks = 10)
 
data(testElevation)# load elevation data

#Plot using terraceWrangler to incorporate clustering with elevation
terraceWrangler(clastData = EuclidExample$data, elevData = testElevation, 
  surfaceElevM = "surfaceElevM", profileClast = "ProfileID", profileElev = "ProfileID")

Example elevation dataset

Description

An example dataset of soil measurements used in examples.

Usage

testElevation

Format

A data frame of of 5 rows and 2 columns

Example soil dataset

Description

An example dataset of soil measurements used in examples.

Usage

testPit

Format

A data frame of of 60 rows and 23 columns

Example qualitative soil dataset

Description

An example dataset of qualitative soil measurements used in examples.

Usage

testQual

Format

A data frame of of 22 rows and 11 columns

mirror server hosted at Truenetwork, Russian Federation.