Skip to contents

Get popularity for a set of ott IDs

Source: R/popularity.R
popularity.Rd

Retrieve popularity indices from onezoom for a set of Open Tree of Life IDs. See https://www.onezoom.org/popularity for full methodology.

Usage

popularity(
  otts,
  maxtaxa = NA,
  expand = FALSE,
  spread_evenly = FALSE,
  taxon_names = FALSE,
  include_raw = FALSE,
  sort = NA,
  rate = 5,
  key = NA,
  basereq = NA
)

Arguments

otts

a numeric ID or numeric vector of ott ids indicating the particular taxa to evaluate.

maxtaxa

An integer giving the maximum number of taxa to return. By default this is equivalent to the number of OTTs passed in: if expand_taxa is TRUE, you may wish to set this to a higher value. There is an upper limit on the maximum number of taxa you can ask for, which is determined by your API key.

expand

Include all species which are descendants of the given OTTs (i.e. higher level taxa are "expanded" into their constituent species, and the returned taxa are all at the species level). You can mix OTTs for species and higher taxa in a single call: only higher taxa will be expanded. If the parameter is FALSE or not given, do not expand taxa and simply return data on the OTTs that have been passed in (note that higher level taxa will not contain popularity_rank information, which is only valid for species).

spread_evenly

Divide the maximum number of taxa to return (e.g. as given by the max parameter) so that each of the N taxa that are passed in are limited to the top (max÷N) most popular species. Results are then combined and re-sorted, meaning that the final list of taxa returned may well contain fewer species than max. This only really makes sense when expand=TRUE.

taxon_names

Return a scientific (Latin) name for each returned taxon, if one is available. Names are usually (but not necessarily) the same as the scientific name listed on the Open Tree of Life.

include_raw

Also return the raw (non-phylogenetically informed) score for each taxon.

sort

If this is set to rank or raw then do not order species by phylogenetic popularity score then OTT id (as is the default), but instead use an alternative order. If raw, then use the raw (non-phylogenetic) score, which may be zero or absent for some taxa such as these with no wikipedia page (the raw score is also returned, in the same way as it is when setting include_raw=TRUE). If rank, then order by species rank (lowest first, with higher level taxa at start) then by plain popularity score (highest first), and finally by OTT id. Since only species (not higher taxa) have a rank, this necessarily puts all species first.

rate

maximum number of calls to the API per second.

key

your OneZoom API key (defaults to the public key of 0 if not specified).

basereq

an httr2 request object, as generated by oz_basereq(). If NA, uses the default request.

Value

A data frame of the input otts alongside their popularity and popularity rank.

Author

Francis Windram

Examples

if (FALSE) { # \dontrun{
popularity(247341)

popularity(c(247341, 563159, 269666, 504327, 668392), rate=5)

popularity(c(247341, 563159, 269666, 504327, 668392), expand=TRUE, spread_evenly=TRUE, rate=5)
} # }