Skip to main content

Introduction to the palaeoverse R package

r
data-preparation
data-exploration
data-viz
Authors

Lewis A. Jones

Bethany J. Allen

Published

November 19, 2026

View source file

1 Why use palaeoverse

Large datasets of fossil occurrences, often downloaded from online community-maintained databases (e.g. the Paleobiology Database), are a vital resource for understanding broad-scale evolutionary patterns, such as how biodiversity has changed through time and space. Such datasets, however, are often messy and must be ‘cleaned’ of inaccurate, incomplete, or duplicate data prior to analysis (see ‘ten rules’ Jones et al., 2025), as well as prepared and structured in a way that is suitable for the analysis being implemented.

Most palaeobiological analyses begin with routine but essential tasks, such as cleaning data, checking taxonomic names, binning occurrences in time or space, and reconstructing palaeogeographic distributions. The code to achieve such tasks is often rewritten from scratch for every project.

The palaeoverse R package aims to make such efforts more reusable, reproducible, and readable by:

  • replacing long, bespoke scripts with a few clear lines of code
  • using consistent function names, arguments, and outputs so that scripts are easy to follow and share
  • providing well-documented, tested, and peer-reviewed functions that are transparent and robust

2 Design

Three design choices shape how palaeoverse functions look and behave.

2.1 Built around occurrence data

Most functions in palaeoverse take an occurrence data.frame as input, so they directly fit the way many palaeobiologists already store their data.

NoteWhat is an occurrence dataset?

In an occurrence dataset, each row is a single record of something present at a particular place and time. That “something” is usually a taxon, but it does not have to be. For example, in palaeoverse’s in-built reefs dataset, each row is a fossil reef rather than a species.

Occurrence data typically include columns describing:

  • Identity, what the entity represents, such as taxonomy (e.g. accepted name, genus)
  • Age (e.g. maximum and minimum ages or named intervals)
  • Location (e.g. longitude and latitude)
  • Additional context (e.g. formation, collection, or reference)

It could look something a little like this:

occurrence_no accepted_name max_ma min_ma lng lat …
40163 Crocodylia 59.2 56 −74.68 39.97 …
40167 Gavialoidea 59.2 56 −74.68 39.97 …
40168 Gavialoidea 59.2 56 −74.68 39.97 …
… … … … … … …

2.2 Modular

Each function in palaeoverse does one job well. You can use one on its own, or chain several together into a full workflow:

# Load library
library(palaeoverse)
# Get example data
data(tetrapods)
# Get time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")
# Bin data temporally
tetrapods |>
  bin_time(bins = bins, method = "mid") |>
  # View first six rows
  head()
Output
  occurrence_no collection_no                        identified_name
1        146665         12943     n. gen. Anconastes n. sp. vesperus
2        147090         13004                     Gorgonopsia indet.
3        147521         13043 n. gen. Procolophon n. sp. trigoniceps
4        147523         13044       n. gen. Ophiodeirus n. sp. casei
5        147563         13046         Broiliellus n. sp. arroyoensis
6        147564         13048              Broiliellus n. sp. olsoni
  identified_rank           accepted_name accepted_rank early_interval
1         species     Anconastes vesperus       species     Missourian
2        suborder             Gorgonopsia      suborder     Capitanian
3         species Procolophon trigoniceps       species         Induan
4         species       Araeoscelis casei       species     Artinskian
5         species Broiliellus arroyoensis       species      Kungurian
6         species      Broiliellus olsoni       species       Wolfcamp
  late_interval max_ma min_ma   phylum        class              order
1      Gzhelian 305.90  298.9 Chordata Osteichthyes      Temnospondyli
2          <NA> 265.10  259.9 Chordata Osteichthyes       Cotylosauria
3     Olenekian 252.17  247.2 Chordata     Reptilia NO_ORDER_SPECIFIED
4          <NA> 290.10  279.3 Chordata     Reptilia      Araeoscelidia
5          <NA> 279.30  272.3 Chordata Osteichthyes      Temnospondyli
6          <NA> 296.40  268.0 Chordata Osteichthyes      Temnospondyli
           family       genus abund_value  abund_unit        lng       lat
1    Trematopidae  Anconastes           2   specimens -106.34778  36.30444
2            <NA>        <NA>           1   specimens   22.00000 -32.36667
3 Procolophonidae Procolophon          10   specimens   26.50972 -32.10611
4   Araeoscelidae Araeoscelis           2 individuals  -98.93361  33.61167
5   Dissorophidae Broiliellus           6   specimens  -99.20000  33.80972
6   Dissorophidae Broiliellus           2   specimens  -98.14778  33.82639
                   collection_name cc     formation stratgroup member
1                  El Cobre Canyon US        Cutler       <NA>   <NA>
2            Hottentotsrivier Farm ZA Abrahamskraal   Beaufort   <NA>
3 Donnybrook (Queenstown District) ZA       Katberg   Beaufort   <NA>
4            Mouth of Godwin Creek US        Nocona    Wichita   <NA>
5               Broiliellus pocket US        Arroyo Clear Fork   <NA>
6                    Thaxton Ranch US          <NA>    Wichita   <NA>
                       zone   lithology1        environment
1                      <NA>    siltstone     dry floodplain
2 Tapinocephalus Assemblage    sandstone       "floodplain"
3                      <NA>     mudstone     fluvial indet.
4                      <NA> conglomerate terrestrial indet.
5                      <NA> not reported terrestrial indet.
6                      <NA> not reported terrestrial indet.
             pres_mode               taxon_environment        motility
1                 body brackish,freshwater,terrestrial actively mobile
2 body,mold/impression                     terrestrial actively mobile
3                 body                     terrestrial actively mobile
4                 body                     terrestrial actively mobile
5                 body brackish,freshwater,terrestrial actively mobile
6                 body brackish,freshwater,terrestrial actively mobile
       life_habit      diet id n_bins bin_assignment bin_midpoint
1 ground dwelling carnivore  1      2             39      301.300
2            <NA> carnivore  2      1             46      262.100
3            <NA>      <NA>  3      3             50      249.200
4            <NA>      <NA>  4      2             42      286.800
5 ground dwelling carnivore  5      2             43      278.225
6 ground dwelling carnivore  6      6             43      278.225

2.3 Flexible

Functions in palaeoverse are not tied to a single source such as the Paleobiology Database. Column names are arguments rather than fixed requirements. Therefore, data from any source can be used with ease providing you have the right data available.

# Load library
library(palaeoverse)
# Get example data
data(tetrapods)
# Get unique species
tetrapods |>
  tax_unique(genus = "genus", family = "family", order = "order", 
             class = "class", name = "accepted_name") |>
  # View first six rows
  head()
Output
         class         order            family              genus
1 Osteichthyes  Dicynodontia              <NA>           Abajudon
2 Osteichthyes  Cotylosauria Charassognathidae          Abdalodon
3     Reptilia          <NA>  Nyctiphruretidae        Abyssomedon
4 Osteichthyes Temnospondyli      Zatracheidae   Acanthostomatops
5 Osteichthyes Temnospondyli      Derwentiidae          Acerastea
6     Reptilia      Eosuchia              <NA> Acerosodontosaurus
                 genus_species                  unique_name
1              Abajudon kaayai              Abajudon kaayai
2      Abdalodon diastematicus      Abdalodon diastematicus
3        Abyssomedon williamsi        Abyssomedon williamsi
4       Acanthostomatops vorax       Acanthostomatops vorax
5             Acerastea wadeae             Acerastea wadeae
6 Acerosodontosaurus piveteaui Acerosodontosaurus piveteaui

3 Applications

palaeoverse can be used for initial data exploration, as well as preparation for a wide range of downstream analyses, including diversity dynamics, macroevolution, macroecology and biogeography.

Minimal examples of potential applications are provided below, but the module tutorials (Tutorial 1: Phanerozoic reefs, Tutorial 2: Tetrapod biodiversity) will expose you to the broader functionality and use cases of palaeoverse functions.

3.1 Exploring and summarising data

palaeoverse includes functions to help users explore and understand their data better, such as calculating temporal (palaeoverse::tax_range_time()) and geographic ranges (palaeoverse::tax_range_space()):

# Load library
library(palaeoverse)
# Get example data
data(tetrapods)
# Estimate temporal range of taxa
tetrapods |>
  # Drop NAs
  subset(!is.na(order)) |>
  # Plot temporal range
  tax_range_time(name = "order", plot = TRUE) |>
  # View first six rows
  head()
Output

Temporal range of Carboniferous to Early Triassic tetrapods.
Output
            taxon taxon_id max_ma min_ma range_myr n_occ
1  Trilophosauria        1  251.2  247.2       4.0     1
2 Eosauropterygia        2  251.3  247.2       4.1     8
3     Hupehsuchia        3  251.3  247.2       4.1     4
4     Nothosauria        4  251.3  247.2       4.1     1
5      Testudines        5  251.3  247.2       4.1     3
6  Thalattosauria        6  251.3  247.2       4.1     3

3.2 Cleaning and harmonising data

palaeoverse includes functions to support the cleaning and harmonising of data such as removing duplicates (palaeoverse::tax_unique()), standardising ages (palaeoverse::look_up()), and checking taxonomic names for potential misspellings (palaeoverse::tax_check()):

# Load library
library(palaeoverse)
# Get example data
data(tetrapods)
# Check for potential misspellings
tax_check(tetrapods, name = "genus")
Output
$synonyms
  group     greater     lesser count_greater count_lesser
1     D Dvinosaurus Dinosaurus            23            2
2     V   Varanopus   Varanops             5            3

$non_letter_name
NULL

$non_letter_group
NULL

3.3 Preparing data for analyses

palaeoverse includes functions to help prepare data for downstream analyses, such as reconstructing palaeogeographic distributions (palaeoverse::palaeorotate()) or temporally (palaeoverse::time_bins(), palaeoverse::bin_time()) and spatially (palaeoverse::lat_bins_area(), palaeoverse::bin_lat()) binning data:

# Load library
library(palaeoverse)
# Get example data
data(reefs)
# Generate equal-area latitudinal bins
bins <- lat_bins_area(n = 12, plot = TRUE)
Output

12 approximately equal-area latitudinal bins.
# Bin data
reefs |> 
  bin_lat(bins = bins) |>
  head()
Output
  r_number               name             formation   system         series
1        1   Tilkideligi Tepe                       Triassic Upper Triassic
2        2              Hydra Pantokrator Limestone Triassic Upper Triassic
3        3 Shiraho, W-Pacific                        Neogene       Holocene
4        4 Aksu-Terziler area                       Triassic Upper Triassic
5        5    Adnet, Salzburg                       Triassic Upper Triassic
6        6          Rotelwand                       Triassic Upper Triassic
        interval   biota_main       biota_sec      lng     lat country
1   lower Norian Calcisponges Stromatoporoids  30.3833 37.0333  Turkey
2  upper Carnian       Corals    Calcisponges  23.6333 37.3833  Greece
3         Recent       Corals           Algae 124.2500 24.3333 Pacific
4       Tuvalian Calcisponges Stromatoporoids  31.0333 37.8000  Turkey
5 upper Rhaetian       Corals    Calcisponges  13.1667 47.7000 Austria
6       Rhaetian       Corals    Calcisponges  13.1833 47.7000 Austria
                              authors
1                          Riedel, P.
2   Schafer, P., Senowbari-Daryan, B.
3 Kayanne, H., Suzuki, A. & Saito, H.
4                          Riedel, P.
5                         Schafer, P.
6                         Schafer, P.
                                                                                                                                                  title
1                                                 Riffbiotope im Karn und Nor (Obertrias) der Tethys: Entwicklung, Einschnitte und Diversitatsmuster. -
2                                                The Upper Triassic Pantokrator Limestone of Hydra (Greece): An example of a prograding reef complex. -
3                                                                      Diurnal changes in the partial pressure of carbon dioxide in coral reef water. -
4                                                 Riffbiotope im Karn und Nor (Obertrias) der Tethys: Entwicklung, Einschnitte und Diversitatsmuster. -
5  Fazielle Entwicklung und palokologische Zonierung zweier obertriadischer Riffstrukturen in den Nordlichen Kalkalpen (Oberrhat"-Riff-Kalke, Salzburg)
6 Fazielle Entwicklung und palokologische Zonierung zweier obertriadischer Riffstrukturen in den Nordlichen Kalkalpen (Oberrhat"-Riff-Kalke,  Salzburg)
  year lat_bin  lat_max  lat_mid  lat_min
1 1990       3 41.81031 35.90516 30.00000
2 1982       3 41.81031 35.90516 30.00000
3 1995       4 30.00000 24.73561 19.47122
4 1990       3 41.81031 35.90516 30.00000
5 1979       2 56.44269 49.12650 41.81031
6 1979       2 56.44269 49.12650 41.81031

4 Reference guide

You can see all available functions and their documentation via the package’s dedicated website reference guide.
NoteWhere does palaeoverse fit?

Think of palaeoverse as the bridge between raw occurrence data and the analytical methods you want to apply, supporting the development of a full data prepration and exploration pipeline (see ‘ten rules’ Jones et al., 2025).

5 Getting help

Everyone gets stuck with using new tools from time-to-time, and knowing where to look for help is one of the most useful skills to develop. As with most R packages, palaeoverse has several layers of support, from built-in documentation to wider community support.

The palaeoverse website (https://palaeoverse.palaeoverse.org) hosts documentation for every function available, as well as vignettes (tutorials) demonstrating possible applications, and updates on new releases. It is a searchable resource and can be easier to navigate than the help pages in R.

If you are familiar with GitHub, you can search existing issues in the palaeoverse repository to see whether someone has previously encountered the issue you are facing and whether it has already been addressed. If you cannot find an answer, you are welcome to open an issue and include a minimal reproducible example (see guidance on writing one).

If you would like to request a new feature to be added to palaeoverse, or you think you have discovered a bug, you are invited to submit an issue on GitHub, following our contribution guide.

NoteJoin Zulip

GitHub can be a daunting place if you have not used it before. You are welcome to join our Zulip and create a topic under “Help”.

You can join palaeoverse’s Zulip and ask for help if you are still stuck after reading the package documentation.

5.1 References

Jones, L. A., Dean, C. D., Allen, B. J., Drage, H. B., Flannery‐Sutherland, J. T., Gearty, W., Chiarenza, A. A., Dillon, E. M., Farina, B. M., & Godoy, P. L. (2025). Ten simple rules to follow when cleaning occurrence data in palaeobiology. Palaeontology, 68(5), e70028. DOI: 10.1111/pala.70028.



Session info
─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.6.2 (2026-10-29)
 os       Ubuntu 26.04.1 LTS
 system   x86_64, linux-gnu
 ui       X11
 language (EN)
 collate  C.UTF-8
 ctype    C.UTF-8
 tz       UTC
 date     2026-11-19
 pandoc   3.7.0.2 @ /usr/bin/pandoc
 quarto   1.11.9 @ /usr/local/bin/quarto

─ Packages ───────────────────────────────────────────────────────────────────
 ! package     * version date (UTC) lib source
   ape           5.8-1   2024-12-16 [1] RSPM
   askpass       1.2.1   2024-10-04 [1] RSPM
   class         7.3-24  2026-08-03 [2] CRAN (R 4.6.2)
   classInt      0.4-11  2025-01-08 [1] RSPM
   cli           3.6.6   2026-04-09 [1] RSPM
 R cpp11         <NA>    <NA>       [?] <NA>
   curl          8.1.0   2026-10-14 [1] RSPM
   DBI           1.3.0   2026-02-25 [1] RSPM
   digest        0.6.39  2025-11-19 [1] RSPM
   dplyr         1.2.1   2026-04-03 [1] RSPM
   e1071         1.7-17  2025-12-18 [1] RSPM
   generics      0.1.4   2025-05-09 [1] RSPM
   geojsonsf     2.0.5   2025-11-26 [1] RSPM
 R geometries    <NA>    <NA>       [?] <NA>
   geosphere     1.6-8   2026-04-05 [1] RSPM
   glue          1.8.1   2026-04-17 [1] RSPM
   h3jsr         1.3.1   2023-01-21 [1] RSPM
   httr          1.4.9   2026-09-01 [1] RSPM
 R jsonify       <NA>    <NA>       [?] <NA>
   jsonlite      2.0.0   2025-03-27 [1] RSPM
   KernSmooth    2.23-27 2026-08-12 [2] CRAN (R 4.6.2)
   lattice       0.23-1  2026-08-12 [2] CRAN (R 4.6.2)
   lifecycle     1.0.5   2026-01-08 [1] RSPM
   magrittr      2.0.5   2026-04-04 [1] RSPM
   mime          0.13    2025-03-17 [1] RSPM
   nlme          3.1-171 2026-09-01 [2] CRAN (R 4.6.2)
   openssl       2.6.0   2026-11-17 [1] RSPM
   palaeoverse   1.5.0   2026-06-11 [1] RSPM
   pbapply       1.7-5   2026-09-01 [1] RSPM
   pillar        1.11.1  2025-09-17 [1] RSPM
   pkgconfig     2.0.3   2019-09-22 [1] RSPM
   proxy         0.4-29  2025-12-29 [1] RSPM
   purrr         1.2.2   2026-04-10 [1] RSPM
   R6            2.6.1   2025-02-15 [1] RSPM
 R rapidjsonr    <NA>    <NA>       [?] <NA>
   Rcpp          1.1.2   2026-07-05 [1] RSPM
   rlang         1.3.0   2026-07-05 [1] RSPM
   s2            1.1.13  2026-09-28 [1] RSPM
   sf            1.1-3   2026-09-11 [1] RSPM
 R sfheaders     <NA>    <NA>       [?] <NA>
   stringdist    0.9.17  2026-01-16 [1] RSPM
   stringi       1.8.9   2026-08-04 [1] RSPM
   stringr       1.6.0   2025-11-04 [1] RSPM
   sys           3.4.3   2024-10-04 [1] RSPM
   tibble        3.3.1   2026-01-11 [1] RSPM
   tidyr         1.3.2   2025-12-19 [1] RSPM
   tidyselect    1.2.1   2024-03-11 [1] RSPM
   units         1.0-1   2026-03-11 [1] RSPM
   utf8          1.2.6   2025-06-08 [1] RSPM
   V8            8.2.1   2026-10-26 [1] RSPM
   vctrs         0.7.3   2026-04-11 [1] RSPM
   withr         3.0.3   2026-06-19 [1] RSPM
   wk            0.9.5   2025-12-18 [1] RSPM

 [1] /home/runner/work/_temp/Library
 [2] /opt/R/4.6.2/lib/R/library

 R ── Package was removed from disk.

──────────────────────────────────────────────────────────────────────────────