Title:	Stratigraphic Data Processing and Section Plots
Version:	0.1.1
Description:	Data processing and generating stratigraphic sections for volcanic deposits and tephrastratigraphy. Package was developed for studies on Alaska volcanoes ("av") where stratigraphic ("strat") figures are needed for interpreting eruptive histories, but the methods are applicable to any sediment stratigraphy project. Plotting styles inspired by "SedLog" (Zervas et al. 2009) <doi:10.1016/j.cageo.2009.02.009> but with more customizable outputs and flexible data input based on best practice recommendations for the tephra community (Wallace et al. 2022) <doi:10.1038/s41597-022-01515-y>.
License:	CC0
Copyright:	This software is in the public domain because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of the Interior.
BugReports:	https://code.usgs.gov/vsc/tephra/tools/avstrat/-/issues
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	dplyr, tidyr, ggplot2 (≥ 4.0), grid, patchwork, rlang, shiny, leaflet
Suggests:	knitr, readxl, rmarkdown, testthat (≥ 3.0.0), tibble, withr
Depends:	R (≥ 4.1.0)
LazyData:	true
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-02-02 05:49:06 UTC; mloewen
Author:	Matthew Loewen [aut, cre]
Maintainer:	Matthew Loewen <mloewen@usgs.gov>
Repository:	CRAN
Date/Publication:	2026-02-04 18:20:02 UTC

Required stratigraphic categories

Description

These are the canonical categories that all stratigraphic palettes must cover. They are used by validate_stratpal() to ensure palettes are complete.

Usage

.required_strat_categories

Format

An object of class character of length 30.

Internal list of stratigraphic palettes

Description

This list collects all palettes so they can be looked up by name. Add new palettes here as you create them.

Usage

.stratpalettes

Format

An object of class list of length 2.

Add standardized depth information to stratigraphic layer data

Description

add_depths() takes a data frame of stratigraphic layer information and calculates standardized thickness and depth values. It ensures required columns are present, converts thickness and depth units to centimeters, derives a plotting thickness, and computes top, bottom, and middle depths for each layer within a stratigraphic section. The function is designed to handle input where layers are defined either by order and thickness or with absolute start and stop depth values.

Usage

add_depths(df)

Arguments

Details

The function groups data by stratsection_name and orders layers according to stratlayer_order_start_at_top. Depths are computed cumulatively if only thickness is provided, or taken directly from absolute depth columns if available.

Value

A tibble with the original data plus:

• thickness_min_cm, thickness_max_cm: thickness values converted to cm.

• depth_top_cm, depth_bottom_cm: depth values converted to cm.

• thickness_plot: representative thickness used for plotting.

• thickness_plot_warning: message if no thickness was available.

• Depth_top, Depth_bottom, Depth_middle: calculated depths (cm). Rows without sufficient information are dropped.

Examples

# Example data is included with the package
data("example_data_strat", package = "avstrat")

# Order + thickness method (section "fake1")
df1 <- subset(example_data_strat, stratsection_name == "fake1")
add_depths(df1)

# Start/stop depth method (section "fake3")
df2 <- subset(example_data_strat, stratsection_name == "fake3")
add_depths(df2)

Reformat stratigraphic layer data for polygon plotting

Description

add_layer_width() reshapes stratigraphic layer grainsize data into a "long" format suitable for plotting polygons in a stratigraphic section diagram. It constructs left/right grain size boundaries, gathers them into long format, assigns depth coordinates, and converts grain size text labels into numeric values for plotting with ggstrat().

Usage

add_layer_width(df, grainsize_direction = c("increasing", "decreasing"))

Arguments

Value

A tibble in long format with original data plus:

• size_loc: identifier for polygon vertex locations.

• size_text: original grain size text.

• depth: numeric depth coordinate.

• grainsize: numeric grain size code for plotting.

Examples

library(dplyr)
library(tidyr)
df <- tidyr::tibble(
stratlayer_order = c(1,2),
grainsize_top = c("clay", "coarse sand/ash"),
grainsize_bottom = c( "silt", "medium sand/ash"),
Depth_top = c(0, 10),
Depth_bottom = c(10, 20)
)
add_layer_width(df)

Example stratigraphic data from individual tables

Description

A dataset created by loading example inputs with load_stratdata_indiv(). This demonstrates the structure of stratigraphic data when stations, sections, layers, and samples are provided as separate tables and then merged. It shares many column definitions with example_data_strat but contains a reduced set of fields.

Usage

example_data_indiv

Format

example_data_indiv

A data frame with 244 rows and 23 columns:

stratsection_name

Character. Name/identifier of the stratigraphic section.

stratlayer_name

Character. Name/identifier of the stratigraphic layer.

stratlayer_desc

Character. Free‑text description of the layer.

stratlayer_order

Integer. Order of the layer within the section.

thickness_units

Character. Units for thickness (e.g., "millimeters", "centimeters", "meters").

thickness_typical

Numeric. Typical thickness of the layer.

thickness_min

Numeric. Minimum thickness of the layer.

thickness_max

Numeric. Maximum thickness of the layer.

depth_units

Character. Units for depth (see thickness_units).

depth_top

Numeric. Absolute depth to the top of the layer.

depth_bottom

Numeric. Absolute depth to the bottom of the layer.

layer_type

Character/Factor. Lithology or depositional type of the layer (e.g., "tephra fall", "soil").

stratlayer_color

Character. Color description.

grainsize_top

Numeric/Character. Grain size at the top of the layer.

grainsize_bottom

Numeric/Character. Grain size at the bottom of the layer.

volcano_name

Character. Source volcano name. If multiple, separated by "|".

station_id

Character. Station identifier (links back to station metadata).

stratmeasuremethod

Character. Method used for stratigraphic measurement.

stratlayer_order_start_at_top

Logical. Whether ordering starts at the top.

Latdd

Numeric. Latitude in decimal degrees.

Longdd

Numeric. Longitude in decimal degrees.

stratlayer_sample

Character. Collapsed sample identifiers per layer, separated by "|".

SampleID

List. Nested list column of sample IDs per layer.

See Also

example_data_strat for a more complete dataset including additional descriptive fields.

Example GeoDIVA forms data

Description

A dataset of forms loaded with load_geodiva_forms(). Useful for demonstrating plotting and analysis functions in this package.

Usage

example_data_strat

Format

example_data_strat

A data frame with 244 rows and 39 columns:

stratsection_name

Character. Name/identifier of the stratigraphic section.

stratlayer_name

Character. Name/identifier of the stratigraphic layer.

date_described

Date. Date the section was described.

date_described_timezone

Character. Time zone of the description date.

stratlayer_desc

Character. Free‑text description of the layer.

stratlayer_order

Integer. Order of the layer within the section.

thickness_units

Character. Units for thickness (e.g., "millimeters", "centimeters", "meters").

thickness_typical

Numeric. Typical thickness of the layer.

thickness_min

Numeric. Minimum thickness of the layer.

thickness_max

Numeric. Maximum thickness of the layer.

depth_units

Character. Units for depth (see thickness_units).

depth_top

Numeric. Absolute depth to the top of the layer.

depth_bottom

Numeric. Absolute depth to the bottom of the layer.

depth_uncertainty_top

Numeric. Uncertainty in top depth.

depth_uncertainty_bottom

Numeric. Uncertainty in bottom depth.

layer_type

Character/Factor. Lithology or depositional type of the layer (e.g., "tephra fall", "soil").

stratlayer_color

Character. Color description.

grainsize_top

Numeric/Character. Grain size at the top of the layer.

grainsize_bottom

Numeric/Character. Grain size at the bottom of the layer.

stratlayer_grading

Character. Grading description (e.g. normal, reverse).

contact_lower

Character. Description of the lower contact.

contact_upper

Character. Description of the upper contact.

stratlayer_sorting

Character. Sorting description.

stratlayer_support

Character. Support description (matrix or clast).

tephra_concentration

Numeric/Character. Tephra concentration.

stratlayer_unit

Character. Stratigraphic unit designation.

tephra_name

Character. Formal tephra name.

tephra_guess

Character. Tentative tephra identification.

volcano_name

Character. Source volcano name. If multiple source volcanoes separated by "|".

eruption_name

Character. Source eruption name.

stratlayer_sample

Character. Sample identifier. If multiple samples separated by "|".

station_id

Character. Station identifier.

stratmeasuremethod

Character. Method used for stratigraphic measurement.

stratlayer_order_start_at_top

Logical. Whether ordering starts at the top.

section_notes

Character. Free‑text notes about the section.

Latdd

Numeric. Latitude in decimal degrees.

Longdd

Numeric. Longitude in decimal degrees.

LocationDesc

Character. Location description.

SampleID

List. Nested list column of sample IDs per layer.

Source

<doi.org/10.14509/31084>

<doi.org/10.14509/31090>

Extract unnested samples with stratigraphic depths

Description

extract_sample_depths() takes a stratigraphic dataset that has already been merged (e.g. from load_geodiva_forms() or load_stratdata_indiv()) and applies add_depths() to compute absolute depths. It then expands a nested sample column (by default "SampleID") so that each sample is represented as its own row, and drops rows where the chosen column is missing. Optionally, you can strip away all other layer metadata and return only the sample IDs and depth columns. Can be used on any nested or unested column.

Usage

extract_sample_depths(
  strat_data,
  sample_column = "SampleID",
  remove_layer_metadata = FALSE
)

Arguments

Value

A data frame with one row per sample, including the depth information and associated layer metadata (unless remove_layer_metadata = TRUE).

Examples

# Default: expand the SampleID column
extract_sample_depths(example_data_strat)

# Expand a different column (here "stratlayer_sample")
extract_sample_depths(example_data_strat, sample_column = "stratlayer_sample")

# Return only SampleID and depth columns
extract_sample_depths(example_data_strat, remove_layer_metadata = TRUE)

Plot a grainsize-depth stratigraphic section

Description

Uses ggplot2 to create a grainsize vs. depth stratigraphic section plot.

Usage

ggstrat(
  df,
  section_name,
  grainsize_direction = c("increasing", "decreasing"),
  grainsize_labs = gs_volc_abbr,
  use_theme = NULL,
  xlim = c(-1, 10),
  ylim = NULL,
  depth_units = c("cm", "m"),
  ybreaks = 7,
  layer_fill = "layer_type",
  layer_fill_color = "stratpal_rpg",
  layer_border_color = "black",
  layer_border_linewidth = 0.2
)

Arguments

Value

A ggplot object

Examples

example_data_strat |>
 add_depths() |>
 ggstrat(section_name = "21LSHD02")

Bulk save stratigraphic plots for all uploaded sections

Description

Generate and save a series of stratigraphic plots, one per unique stratigraphic section in the input data frame. The user can supply any plotting function that returns a ggplot object (e.g. one of the package's plotting functions, or a custom function).

Usage

ggstrat_bulk_save(
  df,
  plotfunction = ggstrat,
  outdir = NULL,
  file_type = "png",
  dpi = 300,
  width = 4,
  height = 8,
  units = "in",
  ask = TRUE,
  ...
)

Arguments

Value

Invisibly returns NULL. Called for its side effect of saving plot files to disk.

Examples

# Save plots for each section using the default ggstrat() function
td <- tempdir()
ggstrat_bulk_save(example_data_strat, outdir = td)

# Save plots using a different plotting function
ggstrat_bulk_save(example_data_strat,
                  plotfunction = ggstrat_column,
                  outdir = td)

# Save plots with higher resolution
ggstrat_bulk_save(example_data_strat,
                  outdir = td,
                  dpi = 600)

# Optional cleanup
unlink(list.files(td, full.names = TRUE))

Plot a simple stratigraphic column

Description

Uses ggplot2 to create a simple depth-only stratigraphic section plot with no variable mapped to the x-axis. Each layer is drawn as a fixed-width rectangle.

Usage

ggstrat_column(
  df,
  section_name,
  use_theme = NULL,
  ylim = NULL,
  depth_units = c("cm", "m"),
  ybreaks = 7,
  layer_fill = "layer_type",
  layer_fill_color = "stratpal_rpg",
  layer_border_color = "black",
  layer_border_linewidth = 0.2
)

Arguments

Value

A ggplot object showing a schematic stratigraphic column.

Examples

example_data_strat |>
  ggstrat_column(section_name = "21LSHD02")

Plots text lables alongside a stratigraphic section

Description

Uses ggplot2 to plot any character column associated with stratigraphic data such as SampleID at the correct depths for their corresponding layers. Connecting lines extend to the left of the plot to point to plotted layers. It is designed to be combined with a stratigraphic section plot created by ggstrat() using the patchwork::patchwork framework for arranging multiple ggplot objects.

Usage

ggstrat_label(
  df,
  section_name,
  use_theme = NULL,
  label = "stratlayer_sample",
  ylim = NULL,
  ybreaks = 7
)

Arguments

Value

A ggplot object showing SampleIDs plotted by depth in section.

Examples

# Example 1: Basic usage
example_data_strat |>
  ggstrat_label(section_name = "21LSHD02",
              label = "SampleID")

# Example 2: Combine with a stratigraphic section plot using patchwork
if (requireNamespace("patchwork", quietly = TRUE)) {
  stratsection <- example_data_strat |>
    ggstrat(section_name = "21LSHD02")

  samples <- example_data_strat |>
    ggstrat_label(section_name = "21LSHD02",
              label = "SampleID")

  stratsection + samples
}

A combined grainsize-depth and sample label stratigraphic plot

Description

Combines a grainsize–depth plot and sample label plot into a single composite figure using the patchwork::patchwork framework. The two plots are aligned and legends are collected at the bottom.

Usage

ggstrat_samples(
  df,
  section_name,
  label = "stratlayer_sample",
  use_theme = NULL,
  ylim = NULL,
  depth_units = c("cm", "m"),
  ybreaks = 7
)

Arguments

Value

A patchwork/ggplot object combining the stratigraphic plot and sample labels. This object can be further modified with ggplot2::theme() or additional patchwork operators.

Examples

example_data_strat |>
  ggstrat_samples(section_name = "21LSHD02")

Load stratigraphic data from GeoDIVA upload forms

Description

load_geodiva_forms() processes and cleans stratigraphic data from GeoDIVA upload forms, specifically a form that includes Station and Sample data and another form that includes the Layer data. It merges these datasets, resolves any conflicts in key fields, and prepares a consolidated dataset for further analysis. The function also extracts and, optionally, prints a list of unique stratigraphic sections.

Usage

load_geodiva_forms(station_sample_upload, layer_upload, verbose = TRUE)

Arguments

Value

A data frame containing the merged and cleaned stratigraphic data, ready for further analysis.

Examples

# Locate the example Excel files shipped with the package
path_samples <- system.file("extdata", "example_samples_stations_upload_2024.xlsx",
  package = "avstrat"
)
path_layers <- system.file("extdata", "example_layers_upload_2024.xlsx",
  package = "avstrat"
)

# Read them with readxl
library(readxl)
  station_sample_upload <- readxl::read_xlsx(path_samples, sheet = "Data")
  layer_upload <- readxl::read_xlsx(path_layers, sheet = "Data")

  result <- load_geodiva_forms(station_sample_upload, layer_upload)
  head(result)  # result is a data frame

Load stratigraphic data from individual tables

Description

load_stratdata_indiv() loads necessary data for avstrat from separate station (location), section (section metadata), stratlayer, and sample data. Allows upload of smaller number of tables if data are already joined together (e.g., stations-sections combined, or layers-samples combined). The function also extracts and, optionally, prints a list of unique stratigraphic sections.

Usage

load_stratdata_indiv(
  stations_upload,
  sections_upload,
  layers_upload,
  samples_upload = NULL,
  verbose = TRUE
)

Arguments

Value

A data frame of layers joined with section and station metadata, plus collapsed sample information:

• stratlayer_sample: concatenated SampleIDs per layer (separated by "|").

• SampleID: list column of SampleIDs per layer.

Examples

# Locate the example Excel files shipped with the package
path <- system.file("extdata", "example_inputs.xlsx",
  package = "avstrat"
)

# Read them with readxl
library(readxl)
  stations <- readxl::read_xlsx(path, sheet = "stations")
  sections <- readxl::read_xlsx(path, sheet = "sections")
  layers <- readxl::read_xlsx(path, sheet = "layers")
  samples <- readxl::read_xlsx(path, sheet = "samples_layer")

  load_stratdata_indiv(stations_upload = stations,
                       sections_upload = sections,
                       layers_upload = layers,
                       samples_upload = samples)

Launch the interactive map with stratigraphy plots

Description

This function launches a Shiny app that displays an interactive map locations with stratigraphic data. If you click on a station it will generate a stratigraphic plot with the plotting function of your choice (default is ggstrat_samples()). You can also adjust the height of the plot using the slider below the map.

Usage

run_ggstrat_app(df, plot_fun = ggstrat_samples)

Arguments

Value

A Shiny app object.

Examples

if (interactive()) {
# Use your default plotting function
run_ggstrat_app(example_data_strat)

# Or swap in a custom plotting function
run_ggstrat_app(example_data_strat, plot_fun = ggstrat_column)
}

Stratigraphic fill scale

Description

A ggplot2 fill scale that uses one of the built-in stratigraphic palettes.

Usage

scale_fill_stratpal(
  palette = c("stratpal_rpg", "stratpal_grays"),
  overrides = NULL,
  allow_na = FALSE,
  na_color = "gray90",
  ...
)

Arguments

Value

A ggplot2 scale object.

Examples

library(ggplot2)
ggplot(mtcars, aes(factor(cyl), fill = factor(cyl))) +
  geom_bar() +
  scale_fill_stratpal("stratpal_rpg")

# Override one color
scale_fill_stratpal("stratpal_rpg", overrides = c("volcanic" = "orange"))

# Allow missing categories to be filled with gray
scale_fill_stratpal("stratpal_grays", allow_na = TRUE)

Stratigraphic palettes

Description

Named character vectors of hex colors for stratigraphic plotting. These palettes can be passed to scale_fill_stratpal().

Usage

stratpal_rpg

stratpal_grays

Format

Named character vectors

An object of class character of length 30.

An object of class character of length 30.

Examples

stratpal_rpg["volcanic"]
stratpal_grays["soil"]

Custom theme for stratigraphic plots

Description

A ggplot2 theme designed to work well with typical plot ouput from avstrat, and matching the author's preferred aesthetics.

Usage

theme_avstrat(base_size = 11, base_family = "arial")

Arguments

Value

A ggplot2::theme() object.

Examples

# Apply a custom theme to one plot
ggstrat(df = example_data_strat, section_name = "21LSHD02") +
  theme_avstrat()

# Set the custom theme as default for all plots
ggplot2::theme_set(theme_avstrat())
ggstrat(df = example_data_strat, section_name = "21LSHD02")

Validate a stratigraphic palette

Description

Ensures that a palette covers all required categories. By default, missing categories trigger an error. If allow_na = TRUE, missing categories are filled with a default color instead.

Usage

validate_stratpal(pal, allow_na = FALSE, na_color = "gray90")

Arguments

Value

A complete palette (named character vector) ordered to match the required categories.

Examples

# A complete palette passes validation
validate_stratpal(stratpal_rpg)

# Allow missing categories to be filled with gray
validate_stratpal(stratpal_grays, allow_na = TRUE)