Type: Package
Title: Download and Process Data from the Paleobiology Database
Version: 1.0.0
Maintainer: Adrián Castro Insua <adrian.castro.insua@uvigo.gal>
Description: Includes functions to wrap most endpoints of the 'PaleobioDB' API and functions to visualize and process the fossil data. The API documentation for the Paleobiology Database can be found at https://paleobiodb.org/data1.2/.
License: GPL-2
URL: https://docs.ropensci.org/paleobioDB/, https://github.com/ropensci/paleobioDB
BugReports: https://github.com/ropensci/paleobioDB/issues
Imports: curl, graphics, grDevices, gtools, maps, rjson, terra
Suggests: roxygen2, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Encoding: UTF-8
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-02-28 10:18:18 UTC; aci
Author: Sara Varela ORCID iD [aut], Javier González Hernández [aut], Luciano Fabris Sgarbi ORCID iD [aut], Adrián Castro Insua ORCID iD [cre, ctb]
Repository: CRAN
Date/Publication: 2024-02-29 19:20:07 UTC

paleobioDB: An R-package for downloading, visualizing and processing data from the Paleobiology Database

Description

We have developed paleobioDB, an R-package designed to make easy and flexible queries of the Paleobiology Database, as well as to visualize and download selected data. This package will make it easy to access paleontological data in a way that should allow those data to be further analyzed, including via packages and libraries available in R.

Details

We programmed two different groups of functions. First, we developed a set of general and flexible functions to wrap the PaleobioDB API. These functions connect R with each of the endpoints of the PaleobioDB API. Second, based on these base functions, we programmed a second set of functions intended to explore and visualize the fossil occurrences in their geographic, temporal and taxonomic dimensions.

Author(s)

Sara Varela sara.varela@uvigo.gal

Javier Gonzalez javigzz@yahoo.es

Luciano Fabris Sgarbi luciano.f.sgarbi@gmail.com

References

Sara Varela, Javier González-Hernández, Luciano Fabris Sgarbi, Charles Marshall, Mark D. Uhen, Shanan Peters, Michael McClennen, 2015. paleobioDB: an R package for downloading, visualizing and processing data from the Paleobiology Database. Ecography, 38: 419-425. doi:10.1111/ecog.01154

See Also

https://paleobiodb.org

Examples

## Not run: 
canidae <- pbdb_occurrences(
  vocab = "pbdb",
  limit = "all",
  base_name = "canidae",
  interval = "Quaternary",
  show = c("coords", "classext", "ident")
)

## to explore the number of subtaxa
pbdb_subtaxa(canidae)

## to explore the temporal resolution of the fossil records
pbdb_temporal_resolution(canidae)

## returns a data frame and a plot with the temporal span
## of the species, genera, etc.
pbdb_temp_range(canidae, rank = "genus", names = FALSE)

## returns a data frame and a plot showing the species, genera, etc.
## richness across time
pbdb_richness(canidae, rank = "species", temporal_extent = c(0, 10), res = 1)

## returns a data frame and a plot showing the evolutionary
## and extinction rates across time

## evolutionary rates: orig_ext = 1
pbdb_orig_ext(
  canidae,
  rank = "species", temporal_extent = c(0, 10), res = 1,
  orig_ext = 1
)

## extinction rates: orig_ext = 2
pbdb_orig_ext(
  canidae,
  rank = "species", temporal_extent = c(0, 10), res = 1,
  orig_ext = 2
)

## maps the fossil occurrences
pbdb_map(canidae, main = "Canidae", pch = 19, cex = 0.7)

## maps the sampling effort
pbdb_map_occur(canidae, res = 5)

## maps the species, genera, etc. richness
pbdb_map_richness(canidae, rank = "species", res = 5)


## End(Not run)

Get information about a single collection record

Description

Returns information about a single collection record from the Paleobiology Database.

Usage

pbdb_collection(id, ...)

Arguments

id

Identifier of the collection. This parameter is required.

...

Additional arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/colls/single. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

  • show: Select additional blocks of information to be returned along with the basic record. Some possible values include:

    • "loc": Additional information about the geographic locality of the collection

    • "stratext": Detailed information about the stratigraphic context of collection.

    • "lithext": Detailed information about the lithological context of the collection.

Details

Go to pbdb_occurrences() to see an explanation about the main parameters.

Value

A data frame with a single occurrence.

Examples

## Not run: 
  pbdb_collection(id = 1003, vocab = "pbdb", show = c("loc", "stratext"))

## End(Not run)

Get information about multiple collections

Description

Returns information about multiple collections, selected according to the parameters you provide.

Usage

pbdb_collections(...)

Arguments

...

Additional arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/colls/list. Go to pbdb_occurrences() to see an explanation about the main filtering parameters.

Value

A data frame with the collections that match the query.

Examples

## Not run: 
  pbdb_collections(base_name = "Cetacea", interval = "Miocene")

## End(Not run)

Get information about geographic clusters of collections

Description

This path returns information about geographic clusters of collections from the Paleobiology Database. These clusters are defined in order to facilitate the generation of maps at low resolutions. You can make a config request via https://paleobiodb.org/data1.2/config in order to get a list of the available summary levels.

Usage

pbdb_collections_geo(level, ...)

Arguments

level

An integer specifying a cluster level. Refer to https://paleobiodb.org/data1.2/config.txt?show=clusters for a list of available resolution levels ("cluster_level" column).

...

Documentation for all the parameters is available at https://paleobiodb.org/data1.2/colls/summary. Go to pbdb_occurrences() to see an explanation about the main filtering parameters.

Value

A data frame with the collections that match the query.

Examples

## Not run: 
  pbdb_collections_geo(
    level = 2,
    vocab = "pbdb",
    lngmin = 0.0, lngmax = 15.0, latmin = 0.0, latmax = 15.0
  )

## End(Not run)

Get information about a single interval

Description

Returns information about a single interval, selected by identifier.

Usage

pbdb_interval(...)

Arguments

...

Additional arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/intervals/single. Either name or id must be specified, but both cannot be used in the same query:

  • name: Returns the interval with the specified name.

  • id: Returns the interval corresponding to the specified identifier.

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from a single temporal interval.

Examples

## Not run: 
  pbdb_interval(id = 1, vocab = "pbdb")

## End(Not run)

Get information about multiple intervals

Description

Returns information about multiple intervals, selected according to the parameters you provide.

Usage

pbdb_intervals(...)

Arguments

...

arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/intervals/list. E.g.:

  • min_ma: Return only intervals that are at least this old.

  • max_ma: Return only intervals that are at most this old.

  • order: Return the intervals in order starting as specified. Possible values include "age", "name". Defaults to "age".

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from several temporal intervals.

Examples

## Not run: 
  pbdb_intervals(min_ma = 0, max_ma = 2, vocab = "pbdb")

## End(Not run)

Map the fossil records

Description

The function opens a new window with a map showing the distribution of the fossil records as points. These points are coloured according to the number of occurrences per cell.

Usage

pbdb_map(
  data,
  col_int = "white",
  pch = 19,
  col_ocean = "black",
  main = NULL,
  col_point = c("light blue", "blue"),
  do_plot = TRUE,
  ...
)

Arguments

data

Input data frame. This data frame is the output of the pbdb_occurrences() function using the argument show = "coords". See also Details and Examples.

col_int

The colour of the mainland.

pch

See par().

col_ocean

The colour of the ocean.

main

Title of the map. See par().

col_point

Two or more colours that are used to generate the colour gradient showing the number of occurrences per coordinate in the map.

do_plot

Logical. If TRUE, the function produces a plot in addition to returning a data frame with the occurrence counts.

...

Other parameters. See par() and map().

Details

The argument show = "coords" in the pbdb_occurrences() function is required. We recommend the use of a cairo device (X11()) for better visualization of the maps. See Examples.

Value

A data frame with the number of occurrences per coordinate.

See Also

See pbdb_occurrences(), map(), par() and colors() help pages.

Examples

## Not run: 
  data <- pbdb_occurrences(
    limit = "all", vocab = "pbdb", base_name = "Canis", show = "coords"
  )
  X11(width = 12, height = 8)
  pbdb_map(data)
  pbdb_map(data, pch = 1)
  pbdb_map(
    data,
    pch = 19,
    col_point = c("pink", "red"),
    col_ocean = "light blue",
    main = "Canis"
  )

## End(Not run)

Plot a raster showing the number of fossil occurrences

Description

Creates a SpatRaster object and a plot of the sampling effort (number of fossil records per cell).

Usage

pbdb_map_occur(
  data,
  res = 5,
  col_int = "white",
  col_ocean = "black",
  col_eff = c("light blue", "blue"),
  do_plot = TRUE,
  ...
)

Arguments

data

Input data frame. This data frame is the output of the pbdb_occurrences() function using the argument show = "coords". See also Details and Examples.

res

The resolution of the SpatRaster object (in decimal degrees). See terra::res().

col_int

The colour of the mainland.

col_ocean

The colour of the ocean.

col_eff

Two or more colours that are used to generate the colour gradient showing the number of occurrences per cell in the map.

do_plot

Logical. If TRUE, the function produces a plot in addition to returning a SpatRaster.

...

Other parameters. See par() and map()

Details

The argument show = "coords" in the pbdb_occurrences() function is required. We recommend the use of a cairo device (X11()) for better visualization of the maps. See Examples.

Value

A SpatRaster object with the sampling effort (number of fossil records per cell). This SpatRaster object has the resolution that was specified in the res argument. The default is res = 5. Users that wish to work with objects of this type should load package terra.

See Also

See pbdb_occurrences(), map(), par() and colors() help pages

Examples

## Not run: 
  data <- pbdb_occurrences(
    limit = "all", vocab = "pbdb", base_name = "Canis", show = "coords"
  )
  X11(width = 13, height = 7.8)
  pbdb_map_occur(data, res = 2)
  ## Get the raster object without plotting it
  pbdb_map_occur(data, res = 3, do_plot = FALSE)

## End(Not run)

Plot a raster showing the richness of taxa

Description

Creates a SpatRaster object and a plot with richness of species, genera, families, etc. per cell.

Usage

pbdb_map_richness(
  data,
  rank = c("species", "genus", "family", "order", "class", "phylum"),
  do_plot = TRUE,
  res = 5,
  col_int = "white",
  col_ocean = "black",
  col_rich = c("light blue", "blue"),
  title = "Taxonomic richness",
  ...
)

Arguments

data

Input data frame. This data frame is the output of the pbdb_occurrences() function using the argument show = c("coords", "classext"). See also Details and Examples.

rank

Taxon rank for which richness is calculated. The options are: "species", "genus", "family", "order", "class" or "phylum". The default value is "species".

do_plot

Logical. If TRUE, the function produces a plot in addition to returning a SpatRaster.

res

The resolution of the SpatRaster object (in decimal degrees). See terra::res().

col_int

The colour of the mainland.

col_ocean

The colour of the ocean.

col_rich

Two or more colours that are used to generate the colour gradient showing the richness per cell in the map.

title

A title for the plot, to be positioned to the right of the legend.

...

Other parameters. See par() and map().

Details

The argument show = c("coords", "classext") in the pbdb_occurrences() function is required. We recommend the use of a cairo device (X11()) for better visualization of the graphs. See Examples.

Value

A SpatRaster object with the richness of the specified taxon rank per cell. This SpatRaster object has the resolution that was specified in the res argument. The default is res = 5. Users that wish to work with objects of this type should load package terra.

See Also

See pbdb_occurrences(), map(), par() and colors() help pages.

Examples

## Not run: 
  data <- pbdb_occurrences(
    limit = 1000, vocab = "pbdb", base_name = "mammalia",
    show = c("classext", "coords")
  )
  X11(width = 13, height = 7.8)
  pbdb_map_richness(data, res = 8, rank = "genus")
  pbdb_map_richness(data, res = 8, rank = "family")
  ## Get the raster object without plotting the map
  pbdb_map_richness(data, res = 8, rank = "family", do_plot = FALSE)

## End(Not run)

Get information about specimen measurements

Description

Returns information about the measurements associated with the selected fossil specimens.

Usage

pbdb_measurements(...)

Arguments

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/specs/measurements.

The following parameters can be used to retrieve measurements from a known list of specimens, occurrences, or collections. Only the records matching all specified parameters will be returned:

  • spec_id: A list of specimen identifiers.

  • occ_id: A list of occurrence identifiers.

  • coll_id: A list of collection identifiers.

It is possible to return additional information along with the basic record with the following parameter:

  • show: Possible values include:

    • "spec": Includes all of the core fields describing the specimen from which this measurement was taken.

    • "methods": Information about the collection methods used.

See the pbdb_occurrences() documentation for an explanation about more filtering parameters.

Value

A data frame with information about the measurements that match the query.

Examples

## Not run: 
  pbdb_measurements(
    spec_id = c(1505, 30050),
    show = c("spec", "class", "methods"),
    vocab = "pbdb"
  )

## End(Not run)

Get information about a single occurrence record

Description

Returns information about a single occurrence record from the Paleobiology Database.

Usage

pbdb_occurrence(id, ...)

Arguments

id

Identifier of the occurrence. This parameter is required.

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/occs/single. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

  • show: Select additional blocks of information to be returned along with the basic record. Some possible values include:

    • "class": The taxonomic classification of the occurence: phylum, class, order, family, genus.

    • "coords": The latitude and longitude of this occurrence.

    • "loc": Additional information about the geographic locality of the occurrence

    • "stratext": Detailed information about the stratigraphic context of the occurrence.

    • "lithext": Detailed information about the lithological context of the occurrence.

Details

Documentation for all the parameters is available at https://paleobiodb.org/data1.2/occs/single. In the parameter list above, we describe the most common filters that paleontologists and ecologists might use.

Value

A data frame with a single occurrence.

Examples

## Not run: 
  pbdb_occurrence(id = 1001)
  pbdb_occurrence(id = 1001, vocab = "pbdb", show = c("class", "coords"))

## End(Not run)

Get information about fossil occurrence records

Description

Returns information about fossil occurrence records stored in the Paleobiology Database.

Usage

pbdb_occurrences(...)

Arguments

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/occs/list.

  • limit: Limits the number of records returned. The value may be a positive integer, zero, or "all".

  • taxon_name: Return only records associated with the specified taxonomic name(s). You may specify multiple names.

  • base_name: Return records associated with the specified taxonomic name(s) and any of their children (e.g. base_name = "Canis" will return "Canis", "Canis lupus", "Canis mosbachensis", etc.)

  • lngmin: Numeric. The longitude boundaries will be normalized to fall between -180 and 180. Note that if you specify lngmin then you must also specify lngmax. Returns only records whose geographic location falls within the given bounding box (defined by lngmin, lngmax, latmin, latmax). It generates two adjacent bounding boxes if the range crosses the antimeridian.

  • lngmax: Numeric. The longitude boundaries will be normalized to fall between -180 and 180.

  • latmin: Numeric value between -90 and 90. Note that if you specify latmin then you must also specify latmax.

  • latmax: Numeric value between -90 and 90.

  • min_ma: Return only records whose temporal locality is at least this old, specified in millions of years.

  • max_ma: Return only records whose temporal locality is at most this old, specified in millions of years.

  • interval: Return only records whose temporal locality falls within the named geologic time interval (e.g. "Miocene").

  • cc: Return only records whose location falls within the specified geographic regions. The value of this parameter should be one or more two-character country codes and/or three-character continent codes as a comma-separated list (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 and https://paleobiodb.org/data1.2/config.txt?show=continents). If the parameter value starts with !, then records falling into these regions are excluded instead of included. Any country codes starting with ^ are subtracted from the filter.

  • show: Show extra variables (e.g. "coords", "classext", "ident").

Details

Documentation for all the parameters is available at https://paleobiodb.org/data1.2/occs/list. We describe the most common filters that paleontologists and ecologists might use in the parameter list above.

Be aware that depending on the query, some columns may not be returned by the API if those are empty across all the rows.

Value

A data frame with the fossil occurrences.

Examples

## Not run: 
  pbdb_occurrences(id = c(10, 11), show = c("coords", "classext", "ident"))
  pbdb_occurrences(
    limit = "all", vocab = "pbdb", taxon_name = "Canis",
    show = c("coords", "classext", "ident")
  )
  pbdb_occurrences(
    limit = "all", vocab = "pbdb", base_name = "Canidae",
    show = c("coords", "classext", "ident")
  )

## End(Not run)

Get information about a single taxonomic opinion

Description

Returns information about a single taxonomic opinion, selected by identifier.

Usage

pbdb_opinion(id, ...)

Arguments

id

Identifier of the opinion. This parameter is required.

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/opinions/single. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

  • show: Additional information to be shown along with the basic record. Some possible values include:

    • basis: The basis of the opinion, which can be "stated with evidence", "stated without evidence", "implied", or "second hand".

    • entname: The names of the people who authorized, entered and modified this record.

    • refattr: The author(s) and year of publication of the reference from which the opinion was entered.

Value

A data frame with a single taxonomic opinion.

Examples

## Not run: 
  pbdb_opinion(id = 1000, vocab = "pbdb", show = "full")

## End(Not run)

Get information about multiple taxonomic opinions

Description

Returns information about multiple taxonomic opinions, selected according to criteria other than taxon name. This function could be used to query for all of the opinions attributed to a particular author, or to show all of the recently entered opinions.

Usage

pbdb_opinions(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/opinions/list. E.g.:

  • id: Selects the opinions corresponding to the specified identifier(s). You may provide more than one.

  • op_author: Selects only opinions attributed to the specified author. Note that the opinion author(s) may be different from the author(s) of the reference from which the opinion was entered. This parameter accepts last names only, no first initials. You can specify more than one author name, in which case all opinions which match any of these will be selected.

  • ops_created_before: Select only records associated with taxa that were created before the specified date or date/time. See https://paleobiodb.org/data1.2/datetime for documentation on how to specify date/time values.

  • ops_created_after: Select only records associated with taxa that were created on or after the specified date or date/time. See https://paleobiodb.org/data1.2/datetime for documentation on how to specify date/time values.

  • op_type: You can use this parameter to retrieve all opinions, or only the classification opinions, or only certain kinds of opinions. The default is all opinions. Accepted values include: "all" (the default), "class", "valid", "accepted", "junior", "invalid".

Value

A data frame with information about the taxonomic opinions that match the query.

Examples

## Not run: 
  pbdb_opinions(op_pubyr = 1818)

## End(Not run)

Get taxonomic opinions about taxa

Description

Returns information about the taxonomic opinions used to build the taxonomic hierarchy. From all of the opinions entered into the database about a particular taxon, the most recent opinion that is stated with the most evidence is used to classify that taxon. The others are considered to be superseded and are ignored.

Usage

pbdb_opinions_taxa(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/taxa/opinions.

Value

A data frame with information about the taxonomic opinions that match the query.

Examples

## Not run: 
  pbdb_opinions_taxa(base_name = "Canis")

## End(Not run)

Appearance of new taxa and extinctions across time

Description

Returns a data frame with the appearance of new taxa and their last appearances across time in the provided data and optionally produces a plot from it, showing the new appearances or last appearances.

Usage

pbdb_orig_ext(
  data,
  rank = c("species", "genus", "family", "order", "class", "phylum"),
  temporal_extent,
  res,
  orig_ext = 1,
  colour = "#0000FF30",
  bord = "#0000FF",
  ylab = NULL,
  do_plot = TRUE
)

Arguments

data

Data frame from a query to PaleobioDB as returned by pbdb_occurrences(). Important: it is required to show the name of the families, orders, etc. in the data frame, to do that set: show = c("classext", "ident") (see Examples).

rank

The taxon rank to be analyzed. Its default value is "species".

temporal_extent

Vector to set the temporal extent (min, max)

res

Numeric. Sets the intervals of the temporal extent.

orig_ext

Set to 1 to plot the number new appearances, or to 2 to plot the number of extinctions.

colour

Colour of the area of the polygon in the plot.

bord

Colour of the border of the polygon.

ylab

A label for the y axis.

do_plot

Logical value indicating whether to produce a plot (TRUE by default).

Value

A data frame with the number of first appearances and extinctions of the selected taxon rank across time.

Examples

## Not run: 
  canidae <- pbdb_occurrences(
    limit = "all", vocab = "pbdb",
    base_name = "Canidae", show = "classext"
  )

  # Plot of the evolutionary rates
  pbdb_orig_ext(
    canidae,
    rank = "genus",
    orig_ext = 1,
    temporal_extent = c(0, 10), res = 1
  )

  # Plot of the extinction rates
  pbdb_orig_ext(
    canidae,
    rank = "genus",
    orig_ext = 2,
    temporal_extent = c(0, 10), res = 1
  )

## End(Not run)

Get references from which collection data were entered

Description

Returns information about the references from which the selected collection data were entered.

Usage

pbdb_ref_collections(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/colls/refs. E.g.:

  • id: List of collection identifiers.

  • ref_author: Select only references for which any of the authors matches the specified name.

  • ref_pubyr: Select only references published in the specified year.

  • pub_title: Select only references that involve the specified publication.

  • order: Specifies the order in which the results are returned. You can specify multiple values separated by commas, and each value may be appended with .asc or .desc. Accepted values are: "author", "pubyr", "reftitle", "pubtitle", "pubtype", "created", "modified", "rank".

Value

A data frame with the information about the references that match the query.

Examples

## Not run: 
  pbdb_ref_collections(
    base_name = "Canidae",
    interval = "Quaternary",
    cc = "ASI"
  )

## End(Not run)

Get references associated with fossil occurrences

Description

Returns information about the bibliographic references associated with fossil occurrences from the database.

Usage

pbdb_ref_occurrences(...)

Arguments

...

arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/occs/refs

  • ref_author: Select only references for which any of the authors matches the specified name.

  • ref_pubyr: Select only references published in the specified year.

  • pub_title: Select only references that involve the specified publication.

Details

Go to pbdb_occurrences() to see an explanation about the main filtering parameters.

Value

A data frame with the information about the references that match the query.

Examples

## Not run: 
  pbdb_ref_occurrences(vocab = "pbdb", base_name = "Canis", ref_pubyr = 2000)

## End(Not run)

Get references for fossil specimens

Description

Returns information about the bibliographic references associated with the selected fossil specimens.

Usage

pbdb_ref_specimens(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/specs/refs. E.g.:

  • spec_id: List of specimen identifiers.

  • base_name: Return only records associated with the specified taxonomic name(s), including all subtaxa and synonyms.

  • ref_author: Select only references for which any of the authors matches the specified name.

  • ref_pubyr: Select only references published in the specified year.

  • pub_title: Select only references that involve the specified publication.

Value

A data frame with the information about the references that match the query.

Examples

## Not run: 
pbdb_ref_specimens(spec_id = c(1505, 30050))

## End(Not run)

Get references for taxonomic names

Description

Returns information about the source references associated with taxa in the Paleobiology Database. You can use the same parameters that are available with pbdb_taxa, but reference records are returned instead of taxon records. One record is returned per reference, even if it is associated with multiple taxa.

Usage

pbdb_ref_taxa(...)

Arguments

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/taxa/refs

  • name: Returns information about the most fundamental taxonomic name matching this string. The % and _ characters may be used as wildcards.

  • id: Returns information about the taxonomic name corresponding to this identifier. You may not specify both name and id in the same query.

  • show: Show extra variables.

  • rel: Set rel = "synonyms" to select all synonyms of the base taxon or taxa; rel = "children" to select the taxa immediately contained within the base taxon or taxa; rel = "all_children" to select all taxa contained within each matching taxon and within all synonymous taxa; rel = "all_parents" to select all taxa that contain any of the matching taxa.

  • extant: Logical indicating whether to select only extant or non-extant taxa.

Value

A data frame with references from a list of taxa.

Examples

## Not run: 
  pbdb_ref_taxa(
    name = "Canidae", vocab = "pbdb", show = c("both", "comments")
  )

## End(Not run)

Get information about a single reference

Description

Returns information about a single reference, selected by identifier.

Usage

pbdb_reference(id, ...)

Arguments

id

Identifier of the reference. This parameter is required.

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/refs/single. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

  • show: Additional information to be shown along with the basic record. Some possible values include:

    • counts: Report the number of taxonomic names, opinions, occurrences, specimens, and collections derived from this reference that have been entered into the database.

    • both: Show both the formatted reference and the individual fields.

Value

A data frame with a single reference.

Examples

## Not run: 
  pbdb_reference(id = 1003, vocab = "pbdb", show = "both")

## End(Not run)

Get information about multiple references

Description

Returns information about multiple references, selected according to the parameters you provide.

Usage

pbdb_references(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/refs/list. E.g.:

  • ref_author: Select only references for which any of the authors matches the specified name.

  • ref_pubyr: Select only references published in the specified year.

  • pub_title: Select only references that involve the specified publication.

  • order: Specifies the order in which the results are returned. You can specify multiple values separated by commas, and each value may be appended with .asc or .desc. Accepted values are: "author", "pubyr", "reftitle", "pubtitle", "pubtype", "created", "modified", "rank".

Value

A data frame with the information about the references that match the query.

Examples

## Not run: 
  pbdb_references(ref_author = "Polly")

## End(Not run)

Temporal variation in taxon richness

Description

Returns a data frame of temporal variation in taxon richness in the indicated temporal extent and resolution from the provided occurrence data and optionally produces a plot from it.

Usage

pbdb_richness(
  data,
  rank = c("species", "genus", "family", "order", "class", "phylum"),
  res = 1,
  temporal_extent = c(0, 10),
  colour = "#0000FF30",
  bord = "#0000FF",
  ylab = "Richness",
  do_plot = TRUE
)

Arguments

data

Data frame from a query to PaleobioDB as returned by pbdb_occurrences(). Important: it is required to have information about the taxonomic classification of the occurrences in the data frame, to do that set the show parameter to "class" or "classext" (see Examples).

rank

The taxon rank to be analyzed. The default value is "species".

res

Numeric. Sets the duration of the intervals in the temporal extent.

temporal_extent

Numeric vector to set the temporal extent (min, max).

colour

Colour of the area of the polygon in the plot.

bord

Colour of the border of the polygon.

ylab

A label for the y axis.

do_plot

Logical indicating whether to produce a plot (TRUE by default).

Value

A data frame with the richness aggregated by the taxon rank in the specified temporal extent and resolution.

Examples

## Not run: 
  data <- pbdb_occurrences(
    limit = "all",
    vocab = "pbdb",
    base_name = "Canidae",
    show = "class"
  )
  pbdb_richness(data, rank = "species", res = 0.2, temporal_extent = c(0, 3))

## End(Not run)

Get information about a single time scale

Description

Returns information about a single time scale, selected by identifier.

Usage

pbdb_scale(id, ...)

Arguments

id

Identifier of the temporal interval. This parameter is required.

...

Additional arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/scales/single. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from a single scale.

Examples

## Not run: 
  pbdb_scale(id = 1, vocab = "pbdb")

## End(Not run)

Get information about multiple time scales

Description

Returns information about multiple time scales.

Usage

pbdb_scales(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/scales/list. E.g.:

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from the selected scales.

Examples

## Not run: 
  ## Get a data frame with all the scales available in PBDB
  ## by setting no ids
  pbdb_scales()

## End(Not run)

Get information about a single fossil specimen

Description

Returns information about a single fossil specimen, identified either by name or by identifier.

Usage

pbdb_specimen(id, ...)

Arguments

id

The identifier of the specimen. This parameter is required.

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/specs/single.

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

  • show: Select additional blocks of information to be returned along with the basic record. Some possible values include:

    • "loc": Additional information about the geographic locality of the associated occurrence, if any.

    • "stratext": Detailed information about the stratigraphic context of the associated occurrence.

    • "lithext": Detailed information about the lithological context of the associated occurrence.

    • "refattr": The author(s) and year of publication of the reference from which this data was entered. If no reference is recorded for this specimen, the information from the associated occurrence or collection reference is returned instead.

Value

A data frame with information about a single specimen.

Examples

## Not run: 
pbdb_specimen(id = 30050, show = c("class", "loc", "refattr"))

## End(Not run)

Get information about multiple fossil specimens

Description

Returns information about multiple fossil specimens, selected according to the parameters you provide. Depending upon which output blocks you select (show parameter), the response will contain some fields describing the specimens and some describing the occurrences and collections (if any) with which they are associated.

Usage

pbdb_specimens(...)

Arguments

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/specs/list. See the pbdb_occurrences() documentation for an explanation about the main filtering parameters.

Value

A data frame with the fossil specimens that match the query.

Examples

## Not run: 
  pbdb_specimens(base_name = "Cetacea", interval = "Miocene", vocab = "pbdb")

## End(Not run)

Get information about geological strata

Description

Returns information about geological strata, selected by name, rank, and/or geographic location.

Usage

pbdb_strata(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/strata/list. E.g.:

  • name: A full or partial name. You can use % and _ as wildcards.

  • rank: Returns only strata of the specified rank: "formation", "group" or "member".

  • lngmin: Numeric. The longitude boundaries will be normalized to fall between -180 and 180. Note that if you specify lngmin then you must also specify lngmax. Returns only records whose geographic location falls within the given bounding box (defined by lngmin, lngmax, latmin, latmax). It generates two adjacent bounding boxes if the range crosses the antimeridian.

  • lngmax: Numeric. The longitude boundaries will be normalized to fall between -180 and 180.

  • latmin: Numeric between -90 and 90. Note that if you specify latmin then you must also specify latmax.

  • latmax: Numeric between -90 and 90.

  • loc: Return only strata associated with some occurrence whose geographic location falls within the specified geometry, specified in WKT format.

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from the selected strata.

Examples

## Not run: 
  pbdb_strata(
    lngmin = 0, lngmax = 15, latmin = 0, latmax = 15,
    rank = "formation", vocab = "pbdb"
  )

## End(Not run)

Get a list of strata matching a given prefix or partial name

Description

Returns a list of strata matching the given prefix or partial name. This can be used to implement auto-completion for strata names, and can be limited by geographic location if desired.

Usage

pbdb_strata_auto(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/strata/auto. E.g.:

  • name: A full or partial name. It must have at least 3 significant characters, and may end in a space followed by either 'g' or 'f' to indicate that you are looking for a group or formation.

  • rank: Return only strata of the specified rank: "formation" or "group". This may be overridden by a suffix on the value of name.

  • lngmin: Numeric. The longitude boundaries will be normalized to fall between -180 and 180. Note that if you specify lngmin then you must also specify lngmax. Returns only records whose geographic location falls within the given bounding box (defined by lngmin, lngmax, latmin, latmax). It generates two adjacent bounding boxes if the range crosses the antimeridian.

  • lngmax: Numeric. The longitude boundaries will be normalized to fall between -180 and 180.

  • latmin: Numeric between -90 and 90. Note that if you specify latmin then you must also specify latmax.

  • latmax: Numeric between -90 and 90.

  • vocab: Set to "pbdb" to show the complete name of the variables (by default variables have short 3-letter names).

Value

A data frame with information from the strata that match the name parameter.

Examples

## Not run: 
  pbdb_strata_auto(name = "Pin", vocab = "pbdb")

## End(Not run)

Count number of taxa in an occurrence data frame

Description

Count the number of taxa (species, genera, families, orders, classes, and phyla) in an occurrence data frame.

Usage

pbdb_subtaxa(data, do_plot = TRUE, col = "#0000FF")

Arguments

data

Data frame from a query to PaleobioDB as returned by the pbdb_occurrences() function using the argument show = "class" or show = "classext".

do_plot

Logical indicating whether to produce a plot (TRUE by default).

col

Colour of the histogram.

Value

A data frame with the number of subtaxa in the data.

Examples

## Not run: 
  canidae_quat <- pbdb_occurrences(
    limit = "all", base_name = "Canidae",  interval = "Quaternary",
    show = c("coords", "classext", "ident"), vocab = "pbdb"
  )
  pbdb_subtaxa(canidae_quat)

## End(Not run)

Get information about multiple taxonomic names

Description

Returns information about multiple taxonomic names. This function can be used to query for all of the children or parents of a given taxon, among other operations.

Usage

pbdb_taxa(...)

Arguments

...

Arguments passed to the API. See all available arguments at https://paleobiodb.org/data1.2/taxa/list.

  • name: Returns information about the most fundamental taxonomic name matching this string. The % and _ characters may be used as wildcards.

  • id: Return information about the taxonomic name corresponding to this identifier. You may not specify both name and id in the same query.

  • show: Show extra variables. Some examples include: "attr" the attribution of this taxon (author and year); "app" the age of first and last appearance of this taxon from the occurrences recorded in this database; "size" the number of subtaxa appearing in this database.

  • rel: Set rel = "synonyms" to select all synonyms of the base taxon or taxa; rel = "children" to select the taxa immediately contained within the base taxon or taxa; rel = "common" to select the most specific taxon that contains all of the base taxa.

  • extant: Logical indicating whether to select only extant or non-extant taxa.

Value

A data frame with information from a list of taxa.

Examples

## Not run: 
  pbdb_taxa(name = "Canidae", rel = "all_parents", vocab = "pbdb",
            show = c("attr", "app", "size", "class"))
  pbdb_taxa(id = c(10, 11), vocab = "pbdb",
            show = c("attr", "app", "size", "class"))
  pbdb_taxa(
    id = c(10, 11), vocab = "pbdb",
    show = c("attr", "app", "size", "class"), rel = "common"
  )

## End(Not run)

Get a list of taxonomic names matching a prefix or partial name

Description

Returns a list of taxonomic names matching the given prefix or partial name.

Usage

pbdb_taxa_auto(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/taxa/auto. E.g.:

  • name: A partial name or prefix. It must have at least 3 significant characters, and may include both a genus (possibly abbreviated) and a species.

  • limit: Set the limit to the number of matches.

Value

A data frame with information about the matches (taxon rank and number of occurrences in the database).

Examples

## Not run: 
  pbdb_taxa_auto(name = "Cani", limit = 10)

## End(Not run)

Get information about a single taxonomic name

Description

Returns information about a single taxonomic name, identified either by name or by identifier.

Usage

pbdb_taxon(...)

Arguments

...

Arguments passed to the API. See documentation for accepted parameters at https://paleobiodb.org/data1.2/taxa/single. One of the following parameters must be specified (but not both):

  • name: Returns information about the most fundamental taxonomic name matching this string. The % and _ characters may be used as wildcards.

  • id: Returns information about the taxonomic name corresponding to the specified identifier. The value can have different forms (see the API documentation in the link above).

Value

A data frame with information from a single taxon.

Examples

## Not run: 
  pbdb_taxon(name = "Canis", vocab = "pbdb",
             show = c("attr", "app", "size"))

## End(Not run)

Temporal range of taxa

Description

Returns a data frame with the temporal range of the taxa within a selected rank (species, genera, families, etc.), and optionally generates a plot from it.

Usage

pbdb_temp_range(
  data,
  rank = c("species", "genus", "family", "order", "class", "phylum"),
  col = "#0000FF",
  names = TRUE,
  do_plot = TRUE
)

Arguments

data

Data frame from a query to PaleobioDB as returned by pbdb_occurrences(). Important: it is required to have information about the taxonomic classification of the occurrences in the data frame, to do that set the show parameter to "class" or "classext" (see Examples).

rank

The taxon rank to be analyzed. The default value is "species".

col

Colour of the bars in the plot.

names

Logical indicating whether to include the name of the taxa in the plot (TRUE by default).

do_plot

Logical value indicating whether to produce a plot (TRUE by default).

Value

A data frame with the time span of the taxa selected (species, genera, etc.).

Examples

## Not run: 
  canis_quaternary <- pbdb_occurrences(
    limit = "all", base_name = "Canis", interval = "Quaternary",
    show = c("coords", "classext"), vocab = "pbdb"
  )
  pbdb_temp_range(canis_quaternary, rank = "species", names = FALSE)

## End(Not run)

Temporal resolution of fossil data

Description

Shows the temporal resolution of the fossil data.

Usage

pbdb_temporal_resolution(data, do_plot = TRUE)

Arguments

data

Data frame from a query to PaleobioDB as returned by pbdb_occurrences().

do_plot

Logical. If TRUE, the function creates a frequency plot of the data.

Value

A list with a summary of the temporal resolution of the data (min, max, 1st and 3rd quartiles, median and mean), and the temporal resolution of each fossil record (Ma).

Examples

## Not run: 
  data <- pbdb_occurrences(taxon_name = "Canidae", interval = "Quaternary")
  pbdb_temporal_resolution(data)

## End(Not run)