simulateFossilAssemblageSeries {paleoAM} | R Documentation |
Simulate Time-Series of Successive Fossil Assemblages
Description
Given a set of parameters and models describing species abundance, stochastically models changes in an underlying biotic gradient and simulates ecological change and a sequence of samples representing change in recovered fossil assemblages over that interval, including estimating the recovered gradient.
Usage
simulateFossilAssemblageSeries(
kdeRescaled,
probSpeciesOccur,
origAbundData,
eventChangeScale,
bgGradientValue,
fullGradientRange,
eventSampleWidthRatio = NULL,
sampleWidth = NULL,
eventDuration = NULL,
sedRatePerTimestep = NULL,
samplingCompleteness,
transitionDurationRatio,
bioturbDepthRatio,
bioturbIntensity,
nEvents,
nSpecimens,
specimensPerTimestep = 10000,
halfGradientOnly = FALSE,
useTransformedRelAbundance = TRUE,
projectIntoOrigDCA = TRUE,
powerRootTransform = 1,
maxSampleTimeStep = 500,
minSampleTimeStep = 3,
includeInitialBackgroundPhase = FALSE,
plot = FALSE,
thinOutput = FALSE
)
Arguments
kdeRescaled |
The list of modeled KDEs for species abundance, output from |
probSpeciesOccur |
The output from |
origAbundData |
The original matrix of abundance data, to be used to project the simulated data into the same detrended correspondence analysis (DCA) space. |
eventChangeScale |
A value indicating the amount relative to
the background value ( |
bgGradientValue |
The gradient value expected during background intervals during which no notable excursion is occurring on that environmental gradient. |
fullGradientRange |
A vector of two values giving the minimum and maximum gradient values observed in the empirical data. |
eventSampleWidthRatio |
How long should an event be relative to the amount of time (or sediment) captured within a sedimentary sample? This parameter is used for simulating event duration, sample width and sedimentation rate where any two of these three are defined and the third is not defined. This value is referred to as Resolution Potential in Belanger & Bapst (2023). |
sampleWidth |
The 'width' of a sample relative to core depth or outcrop height, usually given in linear units (usually centimeters). For taking sediment samples from a core, this is straightforward (how thick is each sediment sample taken?) but for outcrops this may be more difficult to determine (what is the thickness of a horizon in a shale unit?). |
eventDuration |
The duration (in time-units) of a simulated event during which the environmental gradient is at an excursion 'peak' level. |
sedRatePerTimestep |
The rate of sedimentation, given as a
ratio of sediment thickness (given in linear dimensions,
in the same units as |
samplingCompleteness |
The relative completeness of stratigraphic
sampling. For example, if two-centimeter wide samples of sediment are
taken from a sediment core, every ten centimeters, then the
|
transitionDurationRatio |
The ratio of how long the transition
between peak and background intervals should be, relative to the
length of the peak 'event' duration ( |
bioturbDepthRatio |
The ratio of the sediment depth to which
bioturbation occurs, made relative to the width of a
sediment sample ( |
bioturbIntensity |
The degree of mixing within the bioturbation zone, as a value between 0 and 1. When intensity is 1, a given sample will consist only |
nEvents |
Number of events to occur in a simulated sequence of gradient change. |
nSpecimens |
The number of specimens selected in each individual sample. |
specimensPerTimestep |
The number of specimens returned in a
given time-step by |
halfGradientOnly |
Whether to simulate only half of
a background-event sequence, either beginning or terminating
the simulation at the peak value.
Only a single event can be simulated, so |
useTransformedRelAbundance |
Should the DCA be analyzed |
projectIntoOrigDCA |
Should the new simulated data be projected in the DCA generated by analyzing the original data? This is |
powerRootTransform |
The power-root transform to be used on the abundance data before applying the DCA. By default this is 1, which means the data is not transformed at all. Note that the power-root transform is only performed if |
maxSampleTimeStep |
The maximum number of individual time-steps used for simulating a sample. |
minSampleTimeStep |
The minimum number of individual time-steps used for simulating a sample. |
includeInitialBackgroundPhase |
A logical indicating whether to include a lengthy background phase, for use in calibrating a simulation. This function is mainly for diagnostic purposes and may be removed in future updates. |
plot |
Should the simulated time-series of fossil assemblages
be shown as a sequence of generating and recovered gradient values
against time? Default is |
thinOutput |
Should the output be thinned to just the sample properties and intrinsic variables? Default is FALSE. |
Details
Different parameterizations may be given as input,
allowing different parameters to be unspecified.
Missing parameters are then calculated from the specified
ones using calculateImplicitParameters
.
Value
Returns a list, which by default has seven components:
implicitParameters
, the full list of parameters used for generating the simulated data;
simGradientChangeOut
, the simulated time-series of gradient change output by setupSimulatedGradientChange
;
maxTime
, the total duration of the entire simulated time-series from start to end;
simTimeVar
, a data frame specifying time-steps, sedimentary depth and environmental gradient values for simulating a time-series of sampled fossil assemblages, used as input in sampleFossilSeries
;
fossilSeries
, a list containing the simulated time-series of sampled fossil assemblages from sampleFossilSeries
,
ecology
, the recovered ecological variables for each simulated sample,
as returned by internal function quantifyCommunityEcology
,
and sampleProperties
, a list containing a number of variables specific to individual .
If thinList = TRUE
is used, then the output list
contains only two components:
sampleProperties
and implicitParameters
.
The implicitParameters
component is the same as in the full output,
but the sampleProperties
component only contains information on when
(in both time and sedimentary depth) a given sample is located in the
simulated time-series, and the variable scoreDCA1_recovered
.
References
Belanger, Christina L., and David W. Bapst. 2023. "Simulating our ability to accurately detect abrupt changes in assemblage-based paleoenvironmental proxies." Palaeontologia Electronica 26 (2), 1-32
See Also
Examples
# an example with Gulf of Alaska data
# load data
data(gulfOfAlaska)
alaskaKDEs <- getSpeciesSpecificRescaledKDE(
gradientOrigDCA = DCA1_GOA,
origAbundData = abundData_GOA,
abundanceFloorRatio = 0.5,
nBreaksGradientHist = 20,
modeledSiteAbundance = 10000
)
alaskaProbOccur <- getProbOccViaPresAbs(
gradientOrigDCA = DCA1_GOA,
origAbundData = abundData_GOA
)
# Run the simulation of fossil assemblages
# simulateFossilAssemblageSeries has lots of arguments...
# below they are broken up into groups, seperate by #
# matches scenarios from fig 13 of Belanger & Bapst
fossilSeriesOut <- simulateFossilAssemblageSeries(
# inputs
kdeRescaled = alaskaKDEs,
probSpeciesOccur = alaskaProbOccur,
origAbundData = abundData_GOA,
fullGradientRange = c(min(DCA1_GOA), max(DCA1_GOA)),
# let's make it relatively mild event
# with a long transition
eventChangeScale = 0.5,
bgGradientValue = -1,
transitionDurationRatio = 1,
# don't need to define eventSampleWidthRatio
# - only need to define three of eventSampleWidthRatio,
# sampleWidth, eventDuration, sedRatePerTimestep
sampleWidth = 3,
eventDuration = 100,
sedRatePerTimestep = 0.1,
# sample every third sample-width worth of core
samplingCompleteness = 1/3,
# no bioturbation
bioturbDepthRatio = 0,
bioturbIntensity = 0,
nEvents = 1,
nSpecimens = 100,
# let's plot it
plot = TRUE
)