snvecR

Calculate Earth’s Obliquity and Precession in the Past

https://github.com/japhir/snvecr

Repository

Calculate Earth’s Obliquity and Precession in the Past

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
pth <- withr::local_tempdir(pattern = "snvecR")
withr::local_options(list(snvecR.cachedir = pth))
```

# snvecR


[![DOI](https://zenodo.org/badge/627092810.svg)](https://zenodo.org/badge/latestdoi/627092810)
[![CRAN status](https://www.r-pkg.org/badges/version/snvecR)](https://CRAN.R-project.org/package=snvecR)
[![](http://cranlogs.r-pkg.org/badges/grand-total/snvecR)](https://cran.r-project.org/package=snvecR)
[![GPL-3](https://img.shields.io/github/license/japhir/snvecR?logo=gnu&.svg)](https://github.com/japhir/snvecR/blob/master/LICENSE.md)
[![release](https://img.shields.io/github/v/release/japhir/snvecR.svg)](https://github.com/japhir/snvecR/releases)
[![R-CMD-check](https://github.com/japhir/snvecR/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/japhir/snvecR/actions/workflows/check-standard.yaml)
[![Launch binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/japhir/snvecR/main)


Easily calculate precession and obliquity from an astronomical solution (AS,
defaults to ZB18a from Zeebe and Lourens (2019)) and assumed or reconstructed
values for dynamical ellipticity (Ed) and tidal dissipation
(Td). This is a translation and adaptation of the C-code in the
supplementary material to Zeebe and Lourens (2022), with further details on the
methodology described in Zeebe (2022). The name of the C-routine is snvec,
which refers to the key units of computation: spin vector s and orbit normal
vector n.

## Installation

You can install snvecR like so:

```{r install, eval = FALSE}
install.packages("snvecR")
```

To use the development version of the package, use:

```{r install2, eval = FALSE}
remotes::install_github("japhir/snvecR")
```

Then load it with:
```{r libs}
library(snvecR)
```

## Loading Astronomical Solutions

The function `get_solution()` easily downloads astronomical solutions from
[Richard Zeebe's
website](https://www.soest.hawaii.edu/oceanography/faculty/zeebe_files/Astro.html)
and stores them locally so that they can be reused conveniently. Note that when
run interactively, the function will ask for confirmation to store the files to
the cache directory (which can be customized with `options(snvecR.cachedir =
"/path/to/cache")`). See the documentation for more information
(`?snvecR::get_solution`).

```{r sols}
# full solution needed for snvec below
sol <- get_solution("full-ZB18a")
# eccentricity solutions
ZB18a <- get_solution("ZB18a-300")
ZB20a <- get_solution("ZB20a")
# a pre-computed precession-tilt solution (PT)
ZB18a_1_1 <- get_solution("PT-ZB18a(1,1)")
```


```{r sols_big, eval = FALSE}
# the 3.5 Gyr solutions, e.g. number 5
ZB23.R05 <- get_solution("ZB23.R05")
#> ℹ The astronomical solution "ZB23.R05" has not been cached.
#> ℹ Reading 'ZB23.R05.dat' from website .
#> Downloading any of the ZB23.RXX solutions will take some time.
#> Zip files are about 154 MB.
#> Continue downloading and caching? (Yes/no/cancel)
#> ℹ The cache directory is '/home/japhir/.cache/R/snvecR'.
#> ℹ Saved astronomical solution with helper columns 'ZB23.R05.rds' to cache.
#> ℹ Future calls to `get_solution("ZB23.R05")` will read from the cache.
#> ! If you want to read from scratch, specify `force = TRUE`.
```

## Calculating Precession and Obliquity

Here's the `snvec()` function that calculates climatic precession and obliquity
from an orbital solution input and values for tidal dissipation (Td)
and dynamical ellipticity (Ed).

```{r example}
solution <- snvec(tend = -1000, # final timestep in kyr
                  ed = 1, # dynamical ellipticity, normalized to modern
                  td = 0, # tidal dissipation, normalized to modern
                  astronomical_solution = "full-ZB18a", # see ?full_ZB18a for details
                  tres = -0.4 # timestep resolution in kyr (so this is 400 years)
                  )
```

To quickly save out the results for further study to CSV[^1]:

[^1]: Actually I would recommend the [`readr` package](https://readr.tidyverse.org/) with `readr::write_csv()` instead.

```{r saveresults, eval = FALSE}
write.csv(solution, "ZB18a_ed-1.0_td-0.0.csv")
```

see `?snvec` for further documentation.

Here we create a quick plot of the obliquity:

```{r simpleplot, fig.width = 9, fig.height = 6}
plot(epl ~ time, data = solution, type = 'l')
```

Or if you want to make a slightly fancier plot of the calculated climatic precession with the eccentricity envelope:

```{r plot, fig.width = 9, fig.height = 6}
library(ggplot2)
solution |>
  ggplot(aes(x = time, y = cp)) +
  labs(x = "Time (kyr)", y = "(-)", colour = "Orbital Element") +
  # plot climatic precession
  geom_line(aes(colour = "Climatic Precession")) +
  # add the eccentricity envelope
  geom_line(aes(y = ee, colour = "Eccentricity"),
            data = get_solution() |> dplyr::filter(time > -1000)) +
  scale_color_discrete(type = c("skyblue", "black")) +
  theme(legend.position = "inside", legend.position.inside = c(.9, .95))
```

# Contributing

Contributions are more than welcome! If something doesn't work the way you
expect and you don't know how to fix it, [write an
issue](https://github.com/japhir/snvecR/issues). If you do know how to fix it,
feel free to [create a pull request](https://github.com/japhir/snvecR/pulls)!


# References
Zeebe, R. E., & Lourens, L. J. (2019). Solar System chaos and the
  Paleocene–Eocene boundary age constrained by geology and astronomy.
  _Science_, 365(6456), 926–929.
  [doi:10.1126/science.aax0612](https://doi.org/10.1126/science.aax0612).

Zeebe, R. E., & Lourens, L. J. (2022). A deep-time dating tool for
  paleo-applications utilizing obliquity and precession cycles: The role of
  dynamical ellipticity and tidal dissipation. _Paleoceanography and
  Paleoclimatology_, e2021PA004349.
  [doi:10.1029/2021PA004349](https://doi.org/10.1029/2021PA004349).

Zeebe, R. E. (2022). Reduced Variations in Earth’s and Mars’ Orbital
  Inclination and Earth’s Obliquity from 58 to 48 Myr ago due to Solar
  System Chaos. _The Astronomical Journal_, 164(3),
  [doi:10.3847/1538-3881/ac80f8](https://doi.org/10.3847/1538-3881/ac80f8).

Wikipedia page on Orbital Elements:
  

Owner

Citation (CITATION.cff)

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!

cff-version: 1.2.0
title: >-
  snvecR: Calculate Earth’s Obliquity and Precession in the
  Past
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - family-names: Kocken
    given-names: Ilja
    email: ikocken@hawaii.edu
    orcid: 'https://orcid.org/0000-0003-2196-8718'
  - family-names: Zeebe
    given-names: Richard
    email: zeebe@soest.hawaii.edu
    orcid: 'https://orcid.org/0000-0003-0806-8387'
identifiers:
  - type: doi
    value: 10.5281/zenodo.7865279
    description: Zenodo
repository-code: 'https://github.com/japhir/snvecR'
url: 'https://japhir.github.io/snvecR/'
repository-artifact: 'https://zenodo.org/record/7865280'
abstract: >-
  Easily calculate precession and obliquity from an astronomical solution (defaults to ZB18a from Zeebe and Lourens (2019)) and assumed or reconstructed values for dynamical ellipticity (Ed) and tidal dissipation (Td). This is a translation and adaptation of the 'C'-code in the supplementary material to Zeebe and Lourens (2022), with further details on the methodology described in Zeebe (2022). The name of the 'C'-routine is 'snvec', which refers to the key units of computation: spin vector s and orbit normal vector n.
keywords:
  - orbital forcing
  - precession
  - obliquity
  - tilt
  - tidal dissipation
  - dynamical ellipticity
  - astronomical solution
  - Milankovitch
  - snvec
  - cyclostratigraphy
  - palaeoceanography
  - peleoceanography
  - paleoclimate
  - earth sciences
  - marine sciences
license: GPL-3.0-or-later
version: 3.9.4
date-released: '2024-05-28'
references:
- authors:
  - family-names: Zeebe
    given-names: Richard E.
  - family-names: Lourens
    given-names: Lucas J.
  year: 2019
  title: "Solar System chaos and the Paleocene–Eocene boundary age constrained by geology and astronomy."
  journal: Science
  volume: 365
  issue: 6456
  pages: 926-929
  doi: 10.1126/science.aax0612
  type: article
- authors:
  - family-names: Zeebe
    given-names: Richard E.
  - family-names: Lourens
    given-names: Lucas J.
  year: 2022
  title: "A deep-time dating tool for paleo-applications utilizing obliquity and precession cycles: The role of dynamical ellipticity and tidal dissipation."
  journal: "Paleoceanography and Paleoclimatology"
  doi: 10.1029/2021PA004349
  type: article
- authors:
  - family-names: Zeebe
    given-names: Richard E.
  year: 2022
  title: "Reduced Variations in Earth’s and Mars’ Orbital Inclination and Earth’s Obliquity from 58 to 48 Myr ago due to Solar System Chaos."
  journal: "The Astronomical Journal"
  volume: 164
  issue: 3
  doi: 10.3847/1538-3881/ac80f8
  type: article

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago

Packages