PBDB Data Service 1.2 v2 > Fossil occurrences > Fossil diversity over time (quick computation)

DESCRIPTION

This operation returns a tabulation of fossil diversity over time, similar to that provided by occs/diversity. It returns results much more quickly, but returns only the basic counts of distinct taxa appearing in each time interval. This operation is intended for quick overview plots; if you want to do detailed diversity analyses, we suggest using the occs/diversity operation instead, or downloading a list of occurrences and performing your own procedure to tabulate the diversity of taxa over time.

USAGE

Here are some usage examples:

PARAMETERS

The following parameters specify what to count and at what temporal resolution:

count

This parameter specifies the taxonomic level at which to count. If not specified, it defaults to genera. The accepted values are:

genera

Count genera. You can also use the value genus.

families

Count families. You can also use the value family.

orders

Count orders. You can also use the value order.

time_reso

This parameter specifies the temporal resolution at which to count. If not specified, it defaults to stage. You can also use the parameter name reso. Accepted values are:

stage

Count by stage

epoch

Count by epoch

period

Count by period

era

Count by era

The following parameters select which occurrences to analyze. Except as noted below, you may use these in any combination. All of these parameters can be used with occs/list as well, to retrieve the list of occurrences used to compute this diversity tabulation. Note, however, that some occurrences may be skipped when tabulating diversity because they are imprecisely characterized temporally or taxonomically.

clust_id

Return only records associated with the specified geographic clusters. You may specify one or more cluster ids, separated by commas.

coll_match

A string which will be matched against the collection_name and collection_aka fields. Records will be returned only if they belong to a matching collection. This string may contain the wildcards % and _. In fact, it will probably not match anything unless you include a % at the beginning and/or the end.

coll_re

This is like coll_match, except that it takes a regular expression. You can specify two or more alternatives separated by the vertical bar character |, and you can use all of the other standard regular expression syntax including the backslash \.

base_name

Return only records associated with the specified taxonomic name(s), including all subtaxa and synonyms. You may specify multiple names, separated by commas. You may append one or more exclusions to any name, using the ^ character. For example, Osteichthyes^Tetrapoda would select the fish excluding the tetrapods.

taxon_name

Return only records associated with the specified taxonomic name(s), including any synonyms. You may specify multiple names, separated by commas. Names may include wildcards, but if more than one name matches then only the one with the largest number of occurrences in the database will be used.

match_name

Return only records associated with the specified taxonomic name(s). You may specify multiple names, separated by commas. Names may include the wildcards % and _, and occurrences associated with all matching names will be returned. Synonyms will be ignored. This is a syntactic rather than a taxonomic match.

immediate

You may specify this parameter along with base_name, base_id, or taxon_name. If you do, then synonyms of the specified name(s) will be ignored. No value is necessary for this parameter, just include the parameter name.

base_id

Return only records associated with the specified taxa, including all subtaxa and synonyms. You may specify multiple taxon identifiers, separated by commas. Note that you may specify at most one of taxon_name, taxon_id, base_name, base_id.

taxon_id

Return only records associated with the specified taxa, not including subtaxa or synonyms. You may specify multiple taxon identifiers, separated by commas.

exclude_id

Exclude any records whose associated taxonomic name is a child of the given name or names, specified by taxon identifier. This is an alternative to the use of the ^ character in names.

idreso

Select only occurrences that are identified to the specified taxonomic resolution, and possibly lump together occurrences of the same genus or family. Accepted values are:

species

Select only occurrences which are identified to a species.

genus

Select only occurrences which are identified to a genus or species.

family

Select only occurrences which are identified to a family, genus or species.

lump_genus

Select only occurrences identified as a genus or species, and also coalesce all occurrences of the same genus in a given collection into a single record.

lump_gensub

Select only occurrences identified as a genus or species, and also coalesce all occurrences of the same genus/subgenus in a given collection into a single record.

idtype

This parameter specifies how re-identified occurrences should be treated. Allowed values include:

latest

Select only the latest identification of each occurrence, and ignore any previous ones. This is the default.

orig

Select only the original identification of each occurrence, and ignore any later ones.

reid

Select all identifications of occurrences that have been reidentified, including the original. Ignore occurrences for which no reidentification has been entered in the database. This may result in multiple records being returned each occurrence. Note, however, that if you also specify a taxon name then identifications that do not fall under that name will be ignored. You can find these by specifically querying for the occurrences you are interested in by identifier, with idtype=all.

all

Select every identification that matches the other query parameters. This may result in multiple records being returned for a given occurrence. See also the note given for reid above.

idqual

This parameter selects or excludes occurrences based on their taxonomic modifiers. Allowed values include:

any

Select all occurrences regardless of modifiers. This is the default.

certain

Exclude all occurrences marked with any of the following modifiers: aff. / cf. / ? / "" / informal / sensu lato.

genus_certain

Like certain, but look only at the genus/subgenus and ignore species modifiers.

uncertain

Select only occurrences marked with one of the following modifiers: aff. / cf. / ? / "" / informal / sensu lato.

new

Select only occurrences marked with one of the following: n. gen. / n. subgen. / n. sp.

idmod

This parameter selects or excludes occurrences based on any combination of taxonomic modifiers. You can use this parameter and/or idgen and idspc if you need to select a combination of modifiers not available through idqual. You can specify one or more of the following codes, separated by commas. If the first one is preceded by ! then they are excluded. otherwise, only occurrences marked with at least one are included:

ns

n. sp.

ng

n. gen. or n. subgen.

af

aff.

cf

cf.

sl

sensu lato

if

informal

eg

ex gr.

qm

question mark (?)

qu

quotes ("")

idgenmod

This parameter selects or excludes occurrences based on any combination of taxonomic modifiers on the genus and/or subgenus name. See idmod above.

idspcmod

This parameter selects or excludes occurrences based on any combination of taxonomic modifiers on the species name. See idmod above.

abundance

This parameter selects only occurrences that have particular kinds of abundance values. Accepted values are:

count

Select only occurrences with an abundance type of 'individuals', 'specimens' 'grid-count', 'elements', or 'fragments'

coverage

Select only occurrences with an abundance type of '%-...'

any

Select only occurrences with some type of abundance information

You may also append a colon followed by a decimal number. This will select only occurrences whose abundance is at least the specified minimum value.

lngmin
lngmax

Return only records whose present longitude falls within the given bounds. If you specify one of these parameters then you must specify both. If you provide bounds outside of the range -180° to 180°, they will be wrapped into the proper range. For example, if you specify lngmin=270 & lngmax=360, the query will be processed as if you had said lngmin=-90 & lngmax=0 . In this case, all longitude values in the query result will be adjusted to fall within the actual numeric range you specified.

latmin

Return only records whose present latitude is at least the given value.

latmax

Return only records whose present latitude is at most the given value.

loc

Return only records whose present location (longitude and latitude) falls within the specified shape, which must be given in WKT format with the coordinates being longitude and latitude values.

plate

Return only records located on the specified geological plate(s). If the value of this parameter starts with !, then all records on the specified plates are instead excluded. If the value of this parameter continues with G, then the values will be interpreted as plate numbers from the GPlates model. If S, then they will be interpreted as plate numbers from the Scotese model. Otherwise, they will be interpreted according to the value of the parameter pgm. The remainder of the value must be a list of plate numbers.

pgm

Specify which paleogeographic model(s) to use when evaluating paleocoordinates. You may specify one or more from the following list, separated by commas. If you do not specify a value for this parameter, the default model is gplates.

scotese

Use the paleogeographic model defined by C. R. Scotese (2002), which is the one that this database has been using historically.

gplates

Use the paleogeographic model defined by the GPlates software from the EarthByte group. By default, the coordinates for each collection are calculated at the midpoint of its age range.

gp_early

Use the GPlates model, calculating the rotations at the early end of each collection's age range

gp_mid

A synonym for the value gplates.

gp_late

Use the GPlates model, calculating the rotations at the late end of each collection's age range

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. 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. For example:

ATA,AU

Select occurrences from Antarctica and Australia

NOA,SOA,^AR,^BO

Select occurrences from North and South America, but not Argentina or Bolivia

!EUR,^IS

Exclude occurrences from Europe, except those from Iceland

continent

Return only records whose geographic location falls within the specified continent or continents. The value of this parameter should be a comma-separated list of continent codes. This parameter is deprecated; use cc instead.

strat

Return only records that fall within the named geological stratum or strata. You may specify more than one, separated by commas. Names may include the standard SQL wildcards % and _, and may be followed by any of 'fm', 'gp', 'mbr'. If none of these suffixes is given, then all matching stratigraphic names will be selected. If the parameter value begins with !, then records associated with this stratum or strata are excluded instead of included. Note that this parameter is resolved through string matching only. Stratigraphic nomenclature is not currently standardized in the database, so misspellings may occur.

formation

Return only records that fall within the named stratigraphic formation(s). This parameter is deprecated; use strat instead.

stratgroup

Return only records that fall within the named stratigraphic group(s). This parameter is deprecated; use strat instead.

member

Return only records that fall within the named stratigraphic member(s). This parameter is deprecated; use strat instead.

lithology

Return only records recorded as coming from any of the specified lithologies and/or lithology types. If the paramter value string starts with ! then matching records will be excluded instead. If the symbol ^ occurs at the beginning of any lithology name, then all subsequent values will be subtracted from the filter. Example: carbonate,^bafflestone.

envtype

Return only records recorded as belonging to any of the specified environments and/or environmental zones. If the parameter value string starts with ! then matching records will be excluded instead. If the symbol ^ occurs at the beginning of any environment code, then all subsequent values will be subtracted from the filter. Examples: terr,^fluvial,lacustrine or !slope,^carbonate. You may specify one or more of the following values, as a comma-separated list:

terr

Any terrestrial environment

marine

Any marine environment

carbonate

Carbonate environment

silicic

Siliciclastic environment

unknown

Unknown or indeterminate environment

lacust

Lacustrine zone

fluvial

Fluvial zone

karst

Karst zone

terrother

Other terrestrial zone

marginal

Marginal marine zone

reef

Reef zone

stshallow

Shallow subtidal zone

stdeep

Deep subtidal zone

offshore

Offshore zone

slope

Slope/basin zone

marindet

Marine indeterminate zone

interval_id

Return only records whose temporal locality falls within the given geologic time interval or intervals, specified by numeric identifier. If you specify more than one interval, the time range used will be the contiguous period from the beginning of the earliest to the end of the latest specified interval.

interval

Return only records whose temporal locality falls within the named geologic time interval or intervals, specified by name. You may specify more than one interval, separated by either commas or a dash. If you specify more than one interval, the time range used will be the contiguous period from the beginning of the earliest to the end of the latest specified interval.

min_ma

Return only records whose temporal locality is at least this old, specified in Ma.

max_ma

Return only records whose temporal locality is at most this old, specified in Ma.

timerule

Resolve temporal locality according to the specified rule, as listed below. This rule is applied to determine which occurrences, collections, and/or taxa will be selected if you also specify an age range using any of the parameters listed immediately above. For diversity output, this rule is applied to place each occurrence into one or more temporal bins, or to ignore the occcurrence if it does not match any of the bins. The available rules are:

contain

Select only records whose temporal locality is strictly contained in the specified time range. This is the most restrictive rule. For diversity output, this rule guarantees that each occurrence will fall into at most one temporal bin, but many occurrences will be ignored because their temporal locality is too wide to fall into any of the bins.

major

Select only records for which at least 50% of the temporal locality range falls within the specified time range. For diversity output, this rule also guarantees that each occurrence will fall into at most one temporal bin. Many occurrences will be ignored because their temporal locality is more than twice as wide as any of the overlapping bins, but fewer will be ignored than with the contain rule. This is the default timerule unless you specifically select one.

buffer

Select only records whose temporal locality overlaps the specified time range and also falls completely within a 'buffer zone' around this range. This buffer defaults to 12 million years for the Paleozoic and Mesozoic and 5 million years for the Cenozoic. You can override the buffer width using the parameters timebuffer and late_buffer. For diversity output, some occurrences will be counted as falling into more than one bin. Some occurrences will still be ignored, but fewer than with the above rules.

overlap

Select only records whose temporal locality overlaps the specified time range by any amount. This is the most permissive rule. For diversity output, every occurrence will be counted. Many will be counted as falling into more than one bin.

timebuffer

Override the default buffer period when resolving temporal locality. The value must be given in millions of years. This parameter is only relevant if timerule is set to buffer.

latebuffer

Override the default buffer period for the end of the time range when resolving temporal locality. This allows the buffer to be different on the late end of the interval than on the early end. The value must be given in millions of years. This parameter is only relevant if timerule is set to buffer.

You can also use any of the special parameters with this request

METHODS

This data service accepts the following HTTP methods: GET, HEAD

RESPONSE

The response to an HTTP request with this operation will consist of fields from the following list.

Field nameBlockDescription
pbdbcom
interval_no oid basic

The identifier of the time interval represented by this record

interval_name nam basic

The name of the time interval represented by this record

max_ma eag basic

The beginning age of this interval, in Ma

min_ma lag basic

The ending age of this interval, in Ma

sampled_in_bin dsb basic

The number of distinct taxa found in this interval. By default, distinct genera are counted. You can override this using the parameter count.

n_occs noc basic

The total number of occurrences that are resolved to this interval

FORMATS

The following response formats are available for this operation. You must select the desired format for a request by adding the appropriate suffix to the URI path.

FormatSuffixDocumentation
JSON .json

JSON format

Comma-separated text .txt

Text formats

Comma-separated text .csv

Text formats

Tab-separated text .tsv

Text formats

VOCABULARIES

The following response vocabularies are available for this operation. If you wish your responses to be expressed in a vocabulary other than the default for your selected format, you can use the vocab parameter with the appropriate vocabulary name.

VocabularyNameDefault forDescription
PaleobioDB field names pbdb txt, csv, tsv

The PBDB vocabulary is derived from the underlying field names and values in the database, augmented by a few new fields. For the most part any response that uses this vocabulary will be directly comparable to downloads from the PBDB Classic interface. This vocabulary is the default for text format responses.

Compact field names com json

The Compact vocabulary is a set of 3-character field names designed to minimize the size of the response message. This is the default for JSON format responses. Some of the field values are similarly abbreviated, while others are conveyed in their entirety. For details, see the documentation for the individual response fields.

 

This service is provided by the Paleobiology Database, hosted by the Department of Geoscience at the University of Wisconsin-Madison.

If you have questions about this data service, or wish to report a bug, please contact the database administrator at admin@paleobiodb.org