diff --git a/NAMESPACE b/NAMESPACE index 413dae4..4a04b48 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -37,6 +37,8 @@ S3method(min_time,adm) S3method(plot,adm) S3method(plot,multiadm) S3method(plot,sac) +S3method(plot,stratlist) +S3method(plot,timelist) S3method(print,adm) S3method(print,multiadm) S3method(print,sac) diff --git a/NEWS.md b/NEWS.md index f24e1ae..0080edf 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,11 @@ # admtools (development version) +* removed dependency from `ape` package + +* defined S3 class `timelist` and `stratlist` for data assiciated with time/height + +* unified syntax for time-depth transformation + # admtools 0.2.0 * expanded documentation of defined S3 classes diff --git a/R/plot.stratlist.R b/R/plot.stratlist.R new file mode 100644 index 0000000..40f86ed --- /dev/null +++ b/R/plot.stratlist.R @@ -0,0 +1,29 @@ +plot.stratlist = function(x, orientation = "du", ord_name = "y", ...){ + + #' @export + #' + #' @title plot strat list + #' + #' @param x stratlist object + #' @param orientation charachter, either "du" (down-up) or "lr" (left-right). Orientation of plotting + #' @param ord_name name of the ordinate. Values plotted against time + #' @param ... further arguments passed to plot + #' + #' @description + #' plots a `stratlist`, i.e. a list of values associated with stratigraphic positions (typically returned by time_to_strat). will plot the element with matching `ord_name` against stratigraphic positions. + #' + #' + if (!(ord_name %in% names(x))){ + stop("no matching ordinate name found") + } + + if (orientation == "du"){ + plot(x[[ord_name]], x$h, ...) + return(invisible()) + } + if (orientation == "lr"){ + plot(x$h, x[[ord_name]], ...) + return(invisible()) + } + stop("Unknown option for \"orientation\". Use either \"ud\" or \"lr\".") +} diff --git a/R/plot.timelist.R b/R/plot.timelist.R new file mode 100644 index 0000000..236031d --- /dev/null +++ b/R/plot.timelist.R @@ -0,0 +1,10 @@ +plot.timelist = function(x, ...){ + #' @export + #' + #' @title plot time lists + #' + #' @param x a time list + #' @param ... other options passed to plot + #' + plot(x$t, x$y, ...) +} diff --git a/R/strat_to_time.list.R b/R/strat_to_time.list.R index a905fe7..05ca11f 100644 --- a/R/strat_to_time.list.R +++ b/R/strat_to_time.list.R @@ -17,7 +17,7 @@ strat_to_time.list = function(obj, x, ...){ #' #' @seealso [time_to_strat.list()] for the transformation from time to height domain, [get_time()] for the underlying procedure, [time_to_strat()] for the higher level function #' - #' @returns a list with one named element "t" instead of the element "h". This element contains the times of the stratigraphic positions in "h". + #' @returns a `timelist` (inherits from `list`). A list with one named element "t" instead of the element "h". This element contains the times of the stratigraphic positions in "h". #' #' @examples #' # see vignette("admtools") for an example @@ -35,5 +35,6 @@ strat_to_time.list = function(obj, x, ...){ li[["t"]] = get_time(adm, h = li[["h"]], ...) li = li[names(li) != "h" ] + class(li) = c("timelist", "list") return(li) } \ No newline at end of file diff --git a/R/time_to_strat.list.R b/R/time_to_strat.list.R index e2304ff..fbed198 100644 --- a/R/time_to_strat.list.R +++ b/R/time_to_strat.list.R @@ -16,7 +16,7 @@ time_to_strat.list = function(obj, x, ...){ #' #' @seealso [strat_to_time.list()] for the transformation from height to time domain, [time_to_strat.phylo()] and [time_to_strat.numeric()] for transformations of phylogenetic trees and vectors. See [get_height()] for the underlying procedure. #' - #' @returns a list with one named element "h" instead of the element "t", containing the stratigraphic positions corresponding to the times inf "t" + #' @returns a `stratlist` (inherits from `list`): A list with one named element "h" instead of the element "t", containing the stratigraphic positions corresponding to the times inf "t" #' #' @examples #' # see vignette("admtools") for an example @@ -34,6 +34,7 @@ time_to_strat.list = function(obj, x, ...){ li[["h"]] = get_height(adm, t = li[["t"]], ...) li = li[names(li) != "t" ] + class(li) = c("stratlist", "list") return(li) } diff --git a/man/plot.stratlist.Rd b/man/plot.stratlist.Rd new file mode 100644 index 0000000..3a59716 --- /dev/null +++ b/man/plot.stratlist.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plot.stratlist.R +\name{plot.stratlist} +\alias{plot.stratlist} +\title{plot strat list} +\usage{ +\method{plot}{stratlist}(x, orientation = "du", ord_name = "y", ...) +} +\arguments{ +\item{x}{stratlist object} + +\item{orientation}{charachter, either "du" (down-up) or "lr" (left-right). Orientation of plotting} + +\item{ord_name}{name of the ordinate. Values plotted against time} + +\item{...}{further arguments passed to plot} +} +\description{ +plots a \code{stratlist}, i.e. a list of values associated with stratigraphic positions (typically returned by time_to_strat). will plot the element with matching \code{ord_name} against stratigraphic positions. +} diff --git a/man/plot.timelist.Rd b/man/plot.timelist.Rd new file mode 100644 index 0000000..faf942c --- /dev/null +++ b/man/plot.timelist.Rd @@ -0,0 +1,16 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plot.timelist.R +\name{plot.timelist} +\alias{plot.timelist} +\title{plot time lists} +\usage{ +\method{plot}{timelist}(x, ...) +} +\arguments{ +\item{x}{a time list} + +\item{...}{other options passed to plot} +} +\description{ +plot time lists +} diff --git a/man/strat_to_time.list.Rd b/man/strat_to_time.list.Rd index a103bfd..dc80cb5 100644 --- a/man/strat_to_time.list.Rd +++ b/man/strat_to_time.list.Rd @@ -14,7 +14,7 @@ \item{...}{options passed to \code{get_time}} } \value{ -a list with one named element "t" instead of the element "h". This element contains the times of the stratigraphic positions in "h". +a \code{timelist} (inherits from \code{list}). A list with one named element "t" instead of the element "h". This element contains the times of the stratigraphic positions in "h". } \description{ Lists are useful to keep data closely associated. This function transforms a list that contains observations diff --git a/man/time_to_strat.list.Rd b/man/time_to_strat.list.Rd index 2a3e617..7f7b48d 100644 --- a/man/time_to_strat.list.Rd +++ b/man/time_to_strat.list.Rd @@ -14,7 +14,7 @@ \item{...}{options passed to \emph{get_height}} } \value{ -a list with one named element "h" instead of the element "t", containing the stratigraphic positions corresponding to the times inf "t" +a \code{stratlist} (inherits from \code{list}): A list with one named element "h" instead of the element "t", containing the stratigraphic positions corresponding to the times inf "t" } \description{ Lists are useful to keep data closely associated. This function transforms a list that contains observations diff --git a/vignettes/adm_plotting.Rmd b/vignettes/adm_plotting.Rmd index 43d210e..f1ad8bf 100644 --- a/vignettes/adm_plotting.Rmd +++ b/vignettes/adm_plotting.Rmd @@ -63,4 +63,8 @@ L_axis_lab(label = "Stratigraphic Height") By default, `multiadm` plots median ages in red and the 95 % envelope in blue. See also `?plot.multiadm`. +## Lists in time and stratigraphic domain + +`admtools` defines S3 classes `timelist` and `stratlist` that are lists with one element that contain time/stratigraphic information. They can be plotted as ordinary lists, see `?plot.timelist` and `?plot.stratlist` for details. + diff --git a/vignettes/admtools.Rmd b/vignettes/admtools.Rmd index f9aaecc..8f92ac5 100644 --- a/vignettes/admtools.Rmd +++ b/vignettes/admtools.Rmd @@ -278,12 +278,12 @@ t = seq(0, 2, by = 0.001) # times BM = function(t){ #" Simulate Brownian motion at times t li = list("t" = t, - trait_val = cumsum(c(0, rnorm(n = length(t) - 1, mean = 0, sd = sqrt(diff(t)))))) + "y" = cumsum(c(0, rnorm(n = length(t) - 1, mean = 0, sd = sqrt(diff(t)))))) + class(li) = c("timelist", "list") # assign class `timelist` for easy plotting, see ?plot.timelist return(li) } evo_list = BM(t) -plot(x = evo_list$t, - y = evo_list$trait_val, +plot(x = evo_list, xlab = "Time [Myr]", ylab = "Trait Value", type = "l") @@ -292,15 +292,15 @@ plot(x = evo_list$t, ```{r} strat_list = time_to_strat(obj = evo_list, x = my_adm) -plot(x = strat_list$h, - y = strat_list$trait_val, +plot(x = strat_list, + orientation = "lr", type = "l", xlab = "Stratigraphic Height [m]", ylab = "Trait Value", main = "Trait Evolution 2 km Offshore") ``` -Note the jump in traits generated by the erosional interval in `my_adm`. +Note the jump in traits generated by the erosional interval in `my_adm`. Both `time_to_strat` and `strat_to_time` return `stratlist` and `timelist` objects when applied to lists. These are like ordinary lists, but come with simplified plotting optinality, see `?plot.stratlist` and `plot.timelist` for details. #### Numeric vectors diff --git a/vignettes/admtools_doc.Rmd b/vignettes/admtools_doc.Rmd index da8d417..d23bfd7 100644 --- a/vignettes/admtools_doc.Rmd +++ b/vignettes/admtools_doc.Rmd @@ -221,6 +221,25 @@ The following functions transform `multiadm` objects into other S3 classes: - `split_multiadm` to split `multiadm` into list of `adm` objects - `mean_adm` , `median_adm` and `quantile_adm` to extract mean, median, and quantile age-depth model of `adm` class.m +### S3 classes `stratlist` and `timelist` + +`stratlist` and `timelist` inherit from the base `list`. They are list of stratigraphic positions or times, associated with other data (e.g. trait values, proxy values) + +### Description + +- `stratlist` is a list with one element named "h" +- `timelist` is a list with one element named "t" + +### Construction + +- `stratlist` is returned by `time_to_strat.list` +- `timelist` is retruned by `strat_to_time.list` + +### Representation + +- `plot.stratlist` for plotting `stratlist` +- `plot.timelist` for plotting `timelist` + ## Methods implemented for external S3 classes ### S3 class `list` @@ -252,6 +271,10 @@ The following functions are used for plotting: - `plot.sac` plotting for S3 class `sac` +- `plot.timelist` for plotting `timelist` + +- `plot.stratlist` for plotting `stratlist` + - `T_axis_lab` to annotate time axis - `L_axis_lab` to annotate length/depth axis