Title: Reconstruct Paleoclimate and Paleoecology with Leaf Physiognomy
Version: 1.1.0
Description: Use leaf physiognomic methods to reconstruct mean annual temperature (MAT), mean annual precipitation (MAP), and leaf dry mass per area (Ma), along with other useful quantitative leaf traits. Methods in this package described in Lowe et al. (in review).
License: GPL (≥ 3)
URL: https://github.com/mjbutrim/dilp, https://mjbutrim.github.io/dilp/
BugReports: https://github.com/mjbutrim/dilp/issues
Depends: R (≥ 2.10)
Imports: dplyr, ggplot2, ggrepel, grDevices, magrittr, rlang, stats, stringr, tidyr, utils, vegan
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.1
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2024-04-05 23:38:40 UTC; UW-User
Author: Matthew J. Butrim [aut, cre, cph], Alexander J. Lowe [aut], Andrew G. Flynn [aut], Aly Baumgartner [aut], Daniel J. Peppe [aut], Dana L. Royer [aut]
Maintainer: Matthew J. Butrim <mbutrim@uwyo.edu>
Repository: CRAN
Date/Publication: 2024-04-05 23:53:07 UTC

dilp: Reconstruct Paleoclimate and Paleoecology with Leaf Physiognomy

Description

Use leaf physiognomic methods to reconstruct mean annual temperature (MAT), mean annual precipitation (MAP), and leaf dry mass per area (Ma), along with other useful quantitative leaf traits. Methods in this package described in Lowe et al. (in review).

Author(s)

Maintainer: Matthew J. Butrim mbutrim@uwyo.edu [copyright holder]

Authors:

See Also

Useful links:


Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling rhs(lhs).


McAbee Example Data

Description

Leaf physiognomic data of specimens collected from the McAbee Fossil Beds in British Columbia, Canada (Lowe et al. 2018).

Usage

McAbeeExample

Format

McAbeeExample

A data frame with 192 rows and 18 columns:

Site

Stratigraphic layer or locality

Specimen Number

Repository number for individual specimen

Morphotype

Morphotype the specimen belongs to

Measurer comments

Additional notes about the specimen or its measurements

Margin

Whether the margin is toothed (0) or entire (1)

Petiole Width

The width of the petiole at the basalmost point of insertion into the leaf lamina

Blade area

The reconstructed area of the leaf lamina, not including the petiole

Blade perimeter

The length of the perimeter of the leaf lamina, not including the petiole

Feret

The diameter of a circle with the same area as the leaf lamina, not including the petiole

Minimum Feret

The longest line that can be drawn between two points on the perimeter of a selection that is perpendicular to Feret length. Approximates blade width.

Raw blade area

The area of a leaf prepared for tooth measurements that still has its teeth.

Raw blade perimeter

The perimeter of a leaf prepared for tooth measurements that still has its teeth.

Internal raw blade area

The area of a leaf prepared for tooth measurements with teeth digitally removed.

Internal raw blade perimeter

The perimeter of a leaf prepared for tooth measurements with teeth digitally removed.

Length of cut perimeter

The total length of all segments of leaf removed from the leaf blade while removing damage during preparation of the leaf.

no. of primary teeth

The number of primary teeth along the undamaged perimeter

no. of secondary teeth

The number of secondary teeth along the undamaged perimeter

Source

Lowe et al. 2018

References


Generate leaf mass per area results

Description

calc_lma() will typically only be called internally by lma(). It provides the flexibility to use custom regression parameters to calculate leaf mass per area (LMA).

Usage

calc_lma(data, params, resolution = "species")

Arguments

data

Must include "petiole metric" or some combination of columns to calculate petiole metric such as "Blade Area", "Petiole Area", and "Petiole Width", or "Leaf Area" and "Petiole Width". If calculating morphospecies-mean LMA, must include "Site" and "Morphotype" columns. If calculating species-mean LMA, only needs to include a "Site' column.

params

A list of regression parameters. Must contain "stat" (= "mean" or = "variance"), "regression_slope", "y_intercept", "unexplained_mean_square", "sample_size_calibration" "mean_log_petiole_metric_calibration", "sum_of_squares_calibration", and "critical_value".

Pre-loaded sets of parameters:

"royer_species_mean_ma":
  • stat = "mean",

  • regression_slope = 0.382,

  • y_intercept = 3.070,

  • unexplained_mean_square = 0.032237,

  • sample_size_calibration = 667,

  • mean_log_petiole_metric_calibration = -3.011,

  • sum_of_squares_calibration = 182.1,

  • critical_value = 1.964

"royer_site_mean_ma":
  • stat = "mean",

  • regression_slope = 0.429,

  • y_intercept = 3.214,

  • unexplained_mean_square = 0.005285,

  • sample_size_calibration = 25,

  • mean_log_petiole_metric_calibration = -2.857,

  • sum_of_squares_calibration = 5.331,

  • critical_value = 2.069

"lowe_site_mean_ma":
  • stat = "mean",

  • regression_slope = 0.345,

  • y_intercept = 2.954,

  • unexplained_mean_square = 0.01212861,

  • sample_size_calibration = 70,

  • mean_log_petiole_metric_calibration = -2.902972,

  • sum_of_squares_calibration = 1.154691,

  • critical_value = 1.995469

"lowe_site_variance_ma":
  • stat = "variance",

  • regression_slope = 0.302,

  • y_intercept = 5.028,

  • unexplained_mean_square = 0.1713672,

  • sample_size_calibration = 70,

  • mean_log_petiole_metric_calibration = -5.97104,

  • sum_of_squares_calibration = 5.085184,

  • critical_value = 1.995469

resolution

Either "species" or "site". Informs whether the function should calculate morphospecies-mean LMA values ("species") or site-mean/site- variance LMA values ("site"). If resolution = "site", data must already be in the form of species-mean LMA.

Value

A table with LMA results

References

Examples

# Calculate morphospecies-mean LMA values with the parameters from Royer et al. (2007)
results <- calc_lma(McAbeeExample,
  params = list(
    stat = "mean",
    regression_slope = 0.382,
    y_intercept = 3.070,
    unexplained_mean_square = 0.032237,
    sample_size_calibration = 667,
    mean_log_petiole_metric_calibration = -3.011,
    sum_of_squares_calibration = 182.1,
    critical_value = 1.964
  ),
  resolution = "species"
)
results

# Calculate site-mean LMA values with the parameters from Lowe et al. (2024) entered from scratch
site_results <- calc_lma(results,
  params = list(
    stat = "mean",
    regression_slope = 0.345,
    y_intercept = 2.954,
    unexplained_mean_square = 0.01212861,
    sample_size_calibration = 70,
    mean_log_petiole_metric_calibration = -2.902972,
    sum_of_squares_calibration = 1.154691,
    critical_value = 1.995469
  ),
  resolution = "site"
)
site_results


Climate Calibration Data

Description

Temperature and precipitation data associated with the modern localities used to calibrate the DiLP model

Usage

climate_calibration_data

Format

climate_calibration_data

A data frame with 92 rows and 3 columns:

Site

Locality name

MAT

Mean Annual Temperature (celsius)

MAP

Mean Annual Precipitation (mm)

Source

Peppe et al. 2011

References


Generate DiLP results

Description

dilp() processes raw leaf physiognomic data, checks for common errors/outliers, and returns the processed data, keys to finding potential errors or outliers, and paleoclimate reconstructions.

Usage

dilp(specimen_data, params = "PeppeGlobal", subsite_cols = NULL)

Arguments

specimen_data

A data frame containing specimen level leaf physiognomic data. See Lowe et al. 2024 for more information on how to collect this data. A good reference for how to put together the data: McAbeeExample

Required columns:

  • site

  • specimen_number

  • morphotype

  • margin

  • feret

  • blade_area

  • raw_blade_perimeter

  • internal_raw_blade_perimeter

  • length_of_cut_perimeter

  • no_of_primary_teeth

  • no_of_subsidiary_teeth

Recommended columns:

  • petiole_width

  • petiole_area

  • blade_perimeter

  • minimum_feret

  • raw_blade_area

  • internal_raw_blade_area

params

Either a string referring to one of two preloaded parameter sets of a list of custom parameters (same format as the list below).

Preloaded parameter sets are "PeppeGlobal" and "PeppeNH" which are calibrated based on global and northern hemisphere data respectively. Allen et al. (2020) illustrates a situation in which the northern hemisphere parameters may be preferable. The "PeppeNH" parameters only estimate MAT. Use "PeppeGlobal" for all MAP estimates. Defaults to "PeppeGlobal" as follows (Peppe et al. 2011):

  • MAT.MLR.M = 0.21,

  • MAT.MLR.FDR = 42.296,

  • MAT.MLR.TC.IP = -2.609,

  • MAT.MLR.constant = -16.004,

  • MAT.MLR.error = 4,

  • MAT.SLR.M = 0.204,

  • MAT.SLR.constant = 4.6,

  • MAT.SLR.error = 4.9,

  • MAP.MLR.LA = 0.298,

  • MAP.MLR.TC.IP = 0.279,

  • MAP.MLR.PR = -2.717,

  • MAP.MLR.constant = 3.033,

  • MAP.MLR.SE = 0.6,

  • MAP.SLR.LA = 0.283,

  • MAP.SLR.constant = 2.92,

  • MAP.SLR.SE = 0.61

subsite_cols

A vector or list of columns present in specimen_data to calculate paleoclimate estimates for. A completely optional parameter - allows different groupings of specimens to be tested, or comparisons of paleoclimate estimates at different levels of grouping. Adds additional estimates to $results.

Value

A list of tables that includes all pertinent DiLP information:

References

Examples

dilp_results <- dilp(McAbeeExample)
dilp_results$processed_leaf_data
dilp_results$processed_morphotype_data
dilp_results$processed_site_data
dilp_results$errors
dilp_results$outliers
dilp_results$results

Test if site leaf physiognomy falls within the physiognomic space of the DiLP calibration dataset

Description

dilp_cca plots a canonical correspondence analysis (CCA) ordination of the leaf physiognomic space represented in the calibration dataset of Peppe et al. (2011). The fossil sites being tested are placed along the CCA axes. If a fossil site falls outside of the plotted calibration space, paleoclimate reconstructions for that fossil site should be treated with caution.

Usage

dilp_cca(
  dilp_table,
  physiognomy_calibration = physiognomyCalibration,
  climate_calibration = climateCalibration
)

Arguments

dilp_table

The results of a call to dilp()

physiognomy_calibration

A physiognomic calibration dataset. Defaults to an internal version of physiognomy_calibration_data.

climate_calibration

A climate calibration dataset. Defaults to an internal version of climate_calibration_data.

Value

A ggplot2 plot

References

Examples

results <- dilp(McAbeeExample)
dilp_cca(results)


Check for common errors in DiLP measurements

Description

dilp_errors() will typically only be called internally by dilp(). However, it can be used on its own to evaluate errors that commonly occur during the data collection and processing steps. A dilp_errors() call will nearly always follow a dilp_processing() call. Returns a data frame.

Usage

dilp_errors(specimen_data)

Arguments

specimen_data

Processed specimen level leaf physiognomic data. The structure should match the structure of the output from dilp_processing()

Value

A 7 by X data frame. Each row shows a common error, and which specimens from the input dataset are tripping it.

Examples

# Check for errors in the provided McAbeeExample dataset.
dilp_dataset <- dilp_processing(McAbeeExample)
dilp_errors <- dilp_errors(dilp_dataset)
dilp_errors

Identify outlier specimens

Description

dilp_outliers() will typically only be called internally by dilp(). However, it can be used on its own to locate specimens that may have been misreported or measured incorrectly. dilp_outliers() returns a data frame listing specimens that have unusually high or low values for the four key parameters used in DiLP analyses. If flagged, it may be worth taking a look at the raw measurements and evaluating if the specimen should be used.

Usage

dilp_outliers(specimen_data)

Arguments

specimen_data

Processed specimen level leaf physiognomic data. The structure should match the structure of the output from dilp_processing()

Value

A 4 by X data frame. Each row represents one of the DiLP parameters, and the specimens that are outliers for that parameter.

Examples

# Check for outliers in the provided McAbeeExample dataset. Each
# of these outliers has been manually re-examined and was found acceptable.
dilp_dataset <- dilp_processing(McAbeeExample)
dilp_outliers <- dilp_outliers(dilp_dataset)
dilp_outliers

Process raw leaf physiognomic data

Description

dilp_processing() will typically only be called internally by dilp(). However, it can be used on its own to generate and view a processed DiLP dataset that includes raw and derived physiognomic values useful for DiLP and other physiognomic analyses. Returns a data frame.

Usage

dilp_processing(specimen_data)

Arguments

specimen_data

A data frame containing specimen level leaf physiognomic data. A good reference for how to put together the data: McAbeeExample

Value

A data frame containing cleaned and processed specimen level leaf physiognomic data. New variables calculated are:

Examples

dilp_dataset <- dilp_processing(McAbeeExample)
dilp_dataset

Generate a suite of leaf mass per area results

Description

lma() takes either raw or processed leaf physiognomic data and returns leaf mass per area (LMA) reconstructions of species-mean, site-mean, and site- variance.

lma() calls calc_lma() multiple times with different sets of parameters. See calc_lma() for more control over LMA reconstructions.

Usage

lma(specimen_data)

Arguments

specimen_data

A table that must include "Site", "Morphotype", and either "Petiole Metric", or "Blade Area", "Petiole Area", and "Petiole Width".

Value

A list of tables containing leaf mass per area reconstructions.

References

Examples

results <- lma(McAbeeExample)
results

Physiognomy Calibration Data

Description

Leaf physiognomic data taken from the modern localities used to calibrate the DiLP model

Usage

physiognomy_calibration_data

Format

physiognomy_calibration_data

A data frame with 92 rows and 12 columns:

Site

Locality name

Leaf.area

Average leaf area at site

FDR

Feret diameter:Feret length. Describes leaf linearity compared to a circle

Perimeter.ratio

Ratio - Raw blade perimeter:Internal raw blade perimeter

TC.P

Ratio - Tooth count:Perimeter

TC.IP

Ratio - Tooth count:Internal perimeter

Avg.TA

Average area of a primary tooth

TA.BA

Ratio - Tooth area:Blade area

TA.P

Ratio - Tooth area:Perimeter

TA.IP

Ratio - Tooth area:Internal perimeter

TC.BA

Ratio - Tooth count:Blade area

Margin

Percentage of untoothed species at the site

Source

Peppe et al. 2011

References


Estimate precipitation with simple linear regression

Description

precip_slr() will produce estimates of mean annual precipitation and standard error using leaf area analysis.

Usage

precip_slr(
  data,
  regression = "Peppe2018",
  slope = NULL,
  constant = NULL,
  error = NULL
)

Arguments

data

A data frame that must include the columns "morphotype", "leaf_area", and "specimen_number". Must be species level data.

regression

A string representing one of the following pre-loaded regressions:

  • "Peppe2018" - for global precipitation estimates

  • "Peppe2011" - The Americas, Japan, and Oceania

  • "Jacobs2002" - Africa

  • "Wilf1998" - The Americas and Africa

slope

Slope, if using a custom regression

constant

Constant, if using a custom regression

error

Standard error, if using a custom regression

Value

A table with MAP estimates for each site

References

Examples

precip_slr(McAbeeExample, regression = "Peppe2011")

Estimate temperature with simple linear regression

Description

temp_slr() will produce estimates of mean annual temperature and standard error using leaf margin analysis.

Usage

temp_slr(
  data,
  regression = "Peppe2018",
  slope = NULL,
  constant = NULL,
  error = NULL
)

Arguments

data

A data frame that must include the columns "morphotype" and "margin". Can be species or site level data.

regression

A string representing one of the following pre-loaded regressions:

  • "Peppe2018" - for global temperature estimates

  • "Peppe2011" - The Americas, Japan, and Oceania

  • "Peppe2011NH" - Peppe 2011 (Northern Hemisphere only)

  • "Miller2006" - North and Central America

  • "WingGreenwood" - East Asia - original leaf margin analysis regression

  • "Wilf1997" - The Americas

slope

Slope, if using a custom regression

constant

Constant, if using a custom regression

error

Standard error, if using a custom regression

Value

A table with MAT estimates for each site

References

Examples

temp_slr(McAbeeExample, regression = "Peppe2011")

View preloaded regressions

Description

View preloaded regressions

Usage

view_regressions(type)

Arguments

type

Must be either "dilp", "lma", temp", or "precip".

Value

A data frame containing the parameters for each available regression of the selected type.

Examples

view_regressions("dilp")