Merge pull request #35 from MindTheGap-ERC/dev

Dev

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)

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

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\".")
+}

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, ...)
+}

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)
 }

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)
 
 }

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.
+
 

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
 

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