diff --git a/CITATION.cff b/CITATION.cff index 7a06bf2..c94e5fd 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -15,7 +15,7 @@ authors: affiliation: Utrecht University identifiers: - type: doi - value: 10.5281/zenodo.15279284 + value: 10.5281/zenodo.15479049 description: Archived version on Zenodo repository-code: 'https://github.com/MindTheGap-ERC/admtools' url: 'https://mindthegap-erc.github.io/admtools/' @@ -28,5 +28,5 @@ keywords: - Stratigraphy - Sedimentology license: GPL-3.0 -version: 0.5.0 -date-released: '2025-04-24' +version: 0.6.0 +date-released: '2025-05-20' diff --git a/DESCRIPTION b/DESCRIPTION index ea2fa7f..9f22ddd 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: admtools Title: Estimate and Manipulate Age-Depth Models -Version: 0.5.0.9000 +Version: 0.6.0.9000 Authors@R: person("Niklas", "Hohmann", , "N.H.Hohmann@uu.nl", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-1559-1838")) @@ -14,7 +14,7 @@ Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.2 Depends: - R (>= 2.10), + R (>= 4.2), Imports: ape LazyData: true diff --git a/NAMESPACE b/NAMESPACE index a7de53d..1d9602d 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -68,6 +68,9 @@ S3method(plot,timelist) S3method(print,adm) S3method(print,multiadm) S3method(print,sac) +S3method(rev_dir,default) +S3method(rev_dir,fossils) +S3method(rev_dir,taxonomy) S3method(sed_rate_l,adm) S3method(sed_rate_l,multiadm) S3method(sed_rate_t,adm) @@ -148,6 +151,7 @@ export(plot_erosive_intervals) export(plot_sed_rate_l) export(plot_sed_rate_t) export(quantile_adm) +export(rev_dir) export(sac_to_adm) export(sed_rate_from_matrix) export(sed_rate_gen_from_bounds) diff --git a/NEWS.md b/NEWS.md index d2712e5..dcf358c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,11 @@ # admtools (development version) +# admtools 0.6.0 + +* transformation between age and time for integration with `FossilSim` + +* vignette for connection between `admtools` and `FossilSim` + # admtools 0.5.0 * new helper functions for estimation of age-depth models diff --git a/R/rev_dir.R b/R/rev_dir.R new file mode 100644 index 0000000..7668536 --- /dev/null +++ b/R/rev_dir.R @@ -0,0 +1,52 @@ +rev_dir = function(x, ref){ + #' @export + #' + #' @title reverse direction of time/depth axis + #' + #' @param x object to transform - typically a `fossil` or `taxonomy` object + #' @param ref reference point used for reversal + #' + #' @description + #' The `FossilSim` package simulates fossils, trees, and taxonomies using age + #' meaning 0 represents the present and larger numbers indicate older ages + #' To interact with `admtools`, the direction of time must be reversed + #' effectively replaces the time component `t` of an object by `ref - t` + #' + #' @examples + #' \dontrun{ + #' # for usage example, see + #' vignette("FossilSim_integration") + #' } + #' + #' + + UseMethod("rev_dir") +} + +rev_dir.default = function(x, ref){ + #' @export + .NotYetImplemented() +} + +rev_dir.fossils = function(x, ref){ + #' @export + #' + hmin = ref - x$hmin + hmax = ref - x$hmax + + x$hmin = hmin + x$hmax = hmax + return(x) +} + +rev_dir.taxonomy = function(x, ref){ + #' @export + + start1 = ref - x$start + end1 = ref - x$end + + x$start = start1 + x$end = end1 + + return(x) +} \ No newline at end of file diff --git a/README.md b/README.md index dbbf8cd..5b1f328 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ R package to estimate age-depth models from stratigraphic and sedimentological d [![R-CMD-check](https://github.com/MindTheGap-ERC/admtools/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/MindTheGap-ERC/admtools/actions/workflows/R-CMD-check.yaml) [![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) [![](https://www.r-pkg.org/badges/version/admtools?color=pink)](https://cran.r-project.org/package=admtools) -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13888709.svg)](https://doi.org/10.5281/zenodo.13888709) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15479049.svg)](https://doi.org/10.5281/zenodo.15479049) ## Authors @@ -85,7 +85,7 @@ For contribution guidelines see the CONTRIBUTING.md file To cite the package, use -* Hohmann, N. (2025). admtools (v0.5.0). Zenodo. https://doi.org/10.5281/zenodo.15279284 +* Hohmann, N. (2025). admtools (v0.6.0). Zenodo. https://doi.org/10.5281/zenodo.15479049 or run diff --git a/inst/CITATION b/inst/CITATION index 9bc89f5..49a54fd 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -3,8 +3,8 @@ bibentry( title = "admtools: R package for estimating age-depth models and transform data", author = "Niklas Hohmann", year = "2024", - doi ="10.5281/zenodo.15279284", + doi ="10.5281/zenodo.15479049", publisher = "Zenodo", - version = "v0.5.0", - url = "https://doi.org/10.5281/zenodo.15279284" + version = "v0.6.0", + url = "https://doi.org/10.5281/zenodo.15479049" ) diff --git a/man/rev_dir.Rd b/man/rev_dir.Rd new file mode 100644 index 0000000..37d0334 --- /dev/null +++ b/man/rev_dir.Rd @@ -0,0 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rev_dir.R +\name{rev_dir} +\alias{rev_dir} +\title{reverse direction of time/depth axis} +\usage{ +rev_dir(x, ref) +} +\arguments{ +\item{x}{object to transform - typically a \code{fossil} or \code{taxonomy} object} + +\item{ref}{reference point used for reversal} +} +\description{ +The \code{FossilSim} package simulates fossils, trees, and taxonomies using age +meaning 0 represents the present and larger numbers indicate older ages +To interact with \code{admtools}, the direction of time must be reversed +effectively replaces the time component \code{t} of an object by \code{ref - t} +} +\examples{ +\dontrun{ + # for usage example, see + vignette("FossilSim_integration") +} + + +} diff --git a/tests/testthat/test_rev_dir.R b/tests/testthat/test_rev_dir.R new file mode 100644 index 0000000..bf78761 --- /dev/null +++ b/tests/testthat/test_rev_dir.R @@ -0,0 +1,9 @@ +test_that("double transformation returns original object",{ + t = ape::rbdtree(birth = 3, death = 1, Tmax = 2) + # simulate taxonomy along the tree + s = FossilSim::sim.taxonomy(tree = t) + # simulate fossils based on taxonomy + f = FossilSim::sim.fossils.poisson(rate = 4, taxonomy = s) + expect_identical(f, f |> rev_dir( ref = 0) |> rev_dir( ref = 0)) + expect_identical(s, s |> rev_dir( ref = 0) |> rev_dir( ref = 0)) +}) diff --git a/vignettes/FossilSim_integration.Rmd b/vignettes/FossilSim_integration.Rmd index 5f44d32..51f15d9 100644 --- a/vignettes/FossilSim_integration.Rmd +++ b/vignettes/FossilSim_integration.Rmd @@ -22,7 +22,11 @@ This vignette explains the integration of `admtools` with the `FossilSim` and `p ## Integration with the `FossilSim` package -`admtools` can transform phylogenetic trees coded as `phylo` objects as well as `fossils` and `taxonomy` objects as defined by the `FossilSim` package. This allows to transform phylogenetic trees with their associated taxonomic information and fossil locations between the time and the stratigraphic domain. We give an example of this workflow +`admtools` can transform phylogenetic trees coded as `phylo` objects as well as `fossils` and `taxonomy` objects as defined by the `FossilSim` package. This allows to transform phylogenetic trees with their associated taxonomic information and fossil locations between the time and the stratigraphic domain. + +In contrast to `admtools`, `FossilSim` uses age (time before the present) instead of time. To successfully transform data generated by `FossilSim`, this must be reversed using `rev_dir`. + +We give an example of this workflow ```{r} set.seed(42) @@ -41,12 +45,25 @@ f = FossilSim::sim.fossils.poisson(rate = 4, taxonomy = s) FossilSim:::plot.fossils(f, tree = t, taxonomy = s, show.taxonomy = TRUE) ## transform everything into the strat domain -t_strat = time_to_strat(t, my_adm) -s_strat = time_to_strat(s, my_adm, destructive = FALSE) -f_strat = time_to_strat(f, my_adm, destructive = FALSE) +t_strat = time_to_strat(t, my_adm) # no transformation of time to age required +s_strat = s |> # taxonomy object in the time domain + rev_dir(ref = max_time(my_adm)) |> # convert age to time + time_to_strat( my_adm, destructive = FALSE) |> # transform using age-depth model + rev_dir(ref = max_height(my_adm)) # transform back into age +f_strat = f |> # same here + rev_dir(ref = max_time(my_adm)) |> + time_to_strat( my_adm, destructive = TRUE)|> # destroy fossils coinciding with gaps + rev_dir(ref = max_height(my_adm)) + FossilSim:::plot.fossils(f_strat, tree = t_strat, taxonomy = s_strat, show.taxonomy = TRUE) ``` +Important point are + +- `rev_dir` must be applied directly after data was generated and and directly before the data is further processed using `FossilSim`. As a principle, use `rev_dir` before data from FossilSim enters the `admtools` and `StratPal` ecosystem, and as it leaves the ecosystem. + +- By default, `FossilSim` plots have axis labels "Time before present", although the trees after the transformation can be trees in the stratigraphic domain. Because of this fixed reference point used, 0 in the above plot represents the uppermost height of the section, the axis units are lengths and not times, and the "Age" is stratigraphic position below the top of the section. + ## Integration with `paleotree` To combine the `admtools` package with the `paleotree` package, please convert the `paleotree` format into the `FossilSim` format as described in the `paleotree` vignette of the `FossilSim` vignette: @@ -59,7 +76,6 @@ After conversion you can proceed as described in the section *Integration with t ## References -* Barido-Sottani J, Pett W, O'Reilly JE, Warnock RCM. Fossilsim: An r package for simulating fossil occurrence data under mechanistic models of preservation and recovery. Methods Ecol Evol. 2019; 10: 835–840. -* Bapst, D.W. (2012), paleotree: an R package for paleontological and phylogenetic analyses of evolution. Methods in Ecology and Evolution, 3: 803-807. -* Warnock R, Barido-Sottani J, Pett W, Joseph O, Stolz U (2024). _FossilSim: Simulation and Plots for Fossil and Taxonomy Data_. R package version 2.4.1, - \ No newline at end of file +- Barido-Sottani J, Pett W, O'Reilly JE, Warnock RCM. Fossilsim: An r package for simulating fossil occurrence data under mechanistic models of preservation and recovery. Methods Ecol Evol. 2019; 10: 835--840. +- Bapst, D.W. (2012), paleotree: an R package for paleontological and phylogenetic analyses of evolution. Methods in Ecology and Evolution, 3: 803-807. +- Warnock R, Barido-Sottani J, Pett W, Joseph O, Stolz U (2024). *FossilSim: Simulation and Plots for Fossil and Taxonomy Data*. R package version 2.4.1,