Module: Gbif::Species

Defined in:
lib/gbifrb/Species.rb

Class Method Summary collapse

Class Method Details

.name_backbone(name:, rank: nil, kingdom: nil, phylum: nil, clazz: nil, order: nil, family: nil, genus: nil, strict: nil, offset: nil, limit: nil, verbose: nil, options: nil) ⇒ Hash

Search the GBIF taxonomic backbone

Examples:

require 'gbifrb'

species = Gbif::Species
species.name_backbone(name: "Helianthus")
species.name_backbone(name: "Poa")

Parameters:

  • offset (Fixnum) (defaults to: nil) —

    Number of record to start at, any non-negative integer. Default: 0

  • limit (Fixnum) (defaults to: nil) —

    Number of results to return. Default: 100

  • verbose (Boolean) (defaults to: nil) —

    Print request headers to stdout. Default: false

  • options (Hash) (defaults to: nil) —

    Hash of options for configuring the request, passed on to Faraday.new

    • timeout [Fixnum] open/read timeout Integer in seconds

    • open_timeout [Fixnum] read timeout Integer in seconds

    • proxy [Hash] hash of proxy options

      • uri [String] Proxy Server URI

      • user [String] Proxy server username

      • password [String] Proxy server password

    • params_encoder [Hash] not sure what this is

    • bind [Hash] A hash with host and port values

    • boundary [String] of the boundary value

    • oauth [Hash] A hash with OAuth details

  • name (String) —

    Full scientific name potentially with authorship (required)

  • rank (String) (defaults to: nil) —

    The rank given as our rank enum. (optional)

  • kingdom (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • phylum (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • clazz (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • order (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • family (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • genus (String) (defaults to: nil) —

    If provided default matching will also try to match against this if no direct match is found for the name alone. (optional)

  • strict (bool) (defaults to: nil) —

    If True it (fuzzy) matches only the given name, but never a taxon in the upper classification (optional)

Returns:



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/gbifrb/Species.rb', line 50

def self.name_backbone(name:, rank: nil, kingdom: nil, phylum: nil,
  clazz: nil, order: nil, family: nil, genus: nil, strict: nil,
  offset: nil, limit: nil, verbose: nil, options: nil)

  arguments = { name: name, rank: rank, kingdom: kingdom,
          phylum: phylum, class: clazz, order: order,
          family: family, genus: genus, strict: strict,
          offset: offset, limit: limit }.tostrings
  opts = arguments.delete_if { |k, v| v.nil? }
  Request.new("species/match", opts, verbose, options).perform
end

.name_lookup(q: nil, rank: nil, higherTaxonKey: nil, status: nil, isExtinct: nil, habitat: nil, nameType: nil, datasetKey: nil, nomenclaturalStatus: nil, limit: 100, offset: nil, facet: false, facetMincount: nil, facetMultiselect: nil, type: nil, hl: false, verbosity: false, verbose: nil, options: nil) ⇒ Hash

Search the GBIF full text

Examples:

require 'gbifrb'

speices = Gbif::Species
speices.name_lookup(q: "Helianthus")
speices.name_lookup(q: "Poa")

Parameters:

  • q (String) (defaults to: nil) —

    Query term(s) for full text search (optional)

  • rank (String) (defaults to: nil) —

    ‘CLASS’, ‘CULTIVAR’, ‘CULTIVAR_GROUP’, ‘DOMAIN’, ‘FAMILY’, ‘FORM’, ‘GENUS’, ‘INFORMAL’, ‘INFRAGENERIC_NAME’, ‘INFRAORDER’, ‘INFRASPECIFIC_NAME’, ‘INFRASUBSPECIFIC_NAME’, ‘KINGDOM’, ‘ORDER’, ‘PHYLUM’, ‘SECTION’, ‘SERIES’, ‘SPECIES’, ‘STRAIN’, ‘SUBCLASS’, ‘SUBFAMILY’, ‘SUBFORM’, ‘SUBGENUS’, ‘SUBKINGDOM’, ‘SUBORDER’, ‘SUBPHYLUM’, ‘SUBSECTION’, ‘SUBSERIES’, ‘SUBSPECIES’, ‘SUBTRIBE’, ‘SUBVARIETY’, ‘SUPERCLASS’, ‘SUPERFAMILY’, ‘SUPERORDER’, ‘SUPERPHYLUM’, ‘SUPRAGENERIC_NAME’, ‘TRIBE’, ‘UNRANKED’, ‘VARIETY’ (optional)

  • verbosity (bool) (defaults to: false) —

    If True show alternative matches considered which had been rejected.

  • higherTaxonKey (String) (defaults to: nil) —

    Filters by any of the higher Linnean rank keys. Note this is within the respective checklist and not searching nub keys across all checklists (optional)

  • status (String) (defaults to: nil) —

    (optional) Filters by the taxonomic status as one of:

    • ‘ACCEPTED’

    • ‘DETERMINATION_SYNONYM’ Used for unknown child taxa referred to via spec, ssp, …

    • ‘DOUBTFUL’ Treated as accepted, but doubtful whether this is correct.

    • ‘HETEROTYPIC_SYNONYM’ More specific subclass of ‘SYNONYM’.

    • ‘HOMOTYPIC_SYNONYM’ More specific subclass of ‘SYNONYM’.

    • ‘INTERMEDIATE_RANK_SYNONYM’ Used in nub only.

    • ‘MISAPPLIED’ More specific subclass of ‘SYNONYM’.

    • ‘PROPARTE_SYNONYM’ More specific subclass of ‘SYNONYM’.

    • ‘SYNONYM’ A general synonym, the exact type is unknown.

  • isExtinct (bool) (defaults to: nil) —

    Filters by extinction status (e.g. ‘isExtinct=True’)

  • habitat (String) (defaults to: nil) —

    Filters by habitat. One of: ‘marine’, ‘freshwater’, or ‘terrestrial’ (optional)

  • nameType (String) (defaults to: nil) —

    (optional) Filters by the name type as one of:

    • ‘BLACKLISTED’ surely not a scientific name.

    • ‘CANDIDATUS’ Candidatus is a component of the taxonomic name for a bacterium that cannot be maintained in a Bacteriology Culture Collection.

    • ‘CULTIVAR’ a cultivated plant name.

    • ‘DOUBTFUL’ doubtful whether this is a scientific name at all.

    • ‘HYBRID’ a hybrid formula (not a hybrid name).

    • ‘INFORMAL’ a scientific name with some informal addition like “cf.” or indetermined like Abies spec.

    • ‘SCINAME’ a scientific name which is not well formed.

    • ‘VIRUS’ a virus name.

    • ‘WELLFORMED’ a well formed scientific name according to present nomenclatural rules.

  • datasetKey (String) (defaults to: nil) —

    Filters by the dataset’s key (a uuid) (optional)

  • nomenclaturalStatus (String) (defaults to: nil) —

    Not yet implemented, but will eventually allow for filtering by a nomenclatural status enum

  • facet (String) (defaults to: false) —

    A list of facet names used to retrieve the 100 most frequent values for a field. Allowed facets are: ‘datasetKey’, ‘higherTaxonKey’, ‘rank’, ‘status’, ‘isExtinct’, ‘habitat’, and ‘nameType’. Additionally ‘threat’ and ‘nomenclaturalStatus’ are legal values but not yet implemented, so data will not yet be returned for them. (optional)

  • facetMincount (String) (defaults to: nil) —

    Used in combination with the facet parameter. Set ‘facetMincount=#’ to exclude facets with a count less than #, e.g. bit.ly/1bMdByP only shows the type value ‘ACCEPTED’ because the other statuses have counts less than 7,000,000 (optional)

  • facetMultiselect (bool) (defaults to: nil) —

    Used in combination with the facet parameter. Set ‘facetMultiselect=True’ to still return counts for values that are not currently filtered, e.g. bit.ly/19YLXPO still shows all status values even though status is being filtered by ‘status=ACCEPTED’ (optional)

  • type (String) (defaults to: nil) —

    Type of name. One of ‘occurrence’, ‘checklist’, or ‘metadata’. (optional)

  • hl (bool) (defaults to: false) —

    Set ‘hl=True’ to highlight terms matching the query when in fulltext search fields. The highlight will be an emphasis tag of class ‘gbifH1’ e.g. ‘q=’plant’, hl=True’. Fulltext search fields include: ‘title’, ‘keyword’, ‘country’, ‘publishing country’, ‘publishing organization title’, ‘hosting organization title’, and ‘description’. One additional full text field is searched which includes information from metadata documents, but the text of this field is not returned in the response. (optional)

  • offset (Fixnum) (defaults to: nil) —

    Number of record to start at, any non-negative integer. Default: 0

  • limit (Fixnum) (defaults to: 100) —

    Number of results to return. Default: 100

  • verbose (Boolean) (defaults to: nil) —

    Print request headers to stdout. Default: false

  • options (Hash) (defaults to: nil) —

    Hash of options for configuring the request, passed on to Faraday.new

    • timeout [Fixnum] open/read timeout Integer in seconds

    • open_timeout [Fixnum] read timeout Integer in seconds

    • proxy [Hash] hash of proxy options

      • uri [String] Proxy Server URI

      • user [String] Proxy server username

      • password [String] Proxy server password

    • params_encoder [Hash] not sure what this is

    • bind [Hash] A hash with host and port values

    • boundary [String] of the boundary value

    • oauth [Hash] A hash with OAuth details

Returns:



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/gbifrb/Species.rb', line 206

def self.name_lookup(q: nil, rank: nil, higherTaxonKey: nil, status: nil,
  isExtinct: nil, habitat: nil, nameType: nil, datasetKey: nil,
  nomenclaturalStatus: nil, limit: 100, offset: nil, facet: false,
  facetMincount: nil, facetMultiselect: nil, type: nil, hl: false,
  verbosity: false, verbose: nil, options: nil)

  arguments = { q: q, rank: rank, higherTaxonKey: higherTaxonKey,
    status: status, isExtinct: isExtinct, habitat: habitat, nameType: nameType,
    datasetKey: datasetKey, nomenclaturalStatus: nomenclaturalStatus,
    limit: limit, offset: offset, facet: facet, facetMincount: facetMincount,
    facetMultiselect: facetMultiselect, type: type, hl: hl,
    verbose: verbosity }.tostrings
  opts = arguments.delete_if { |k, v| v.nil? }
  Request.new("species/search", opts, verbose, options).perform
end

.name_suggest(q: nil, datasetKey: nil, rank: nil, limit: 100, offset: nil, verbose: nil, options: nil) ⇒ Hash

Search the GBIF suggester

Examples:

require 'gbifrb'

species = Gbif::Species
species.name_suggest(q: "Helianthus")
species.name_suggest(q: "Poa")

Parameters:

  • offset (Fixnum) (defaults to: nil) —

    Number of record to start at, any non-negative integer. Default: 0

  • limit (Fixnum) (defaults to: 100) —

    Number of results to return. Default: 100

  • verbose (Boolean) (defaults to: nil) —

    Print request headers to stdout. Default: false

  • options (Hash) (defaults to: nil) —

    Hash of options for configuring the request, passed on to Faraday.new

    • timeout [Fixnum] open/read timeout Integer in seconds

    • open_timeout [Fixnum] read timeout Integer in seconds

    • proxy [Hash] hash of proxy options

      • uri [String] Proxy Server URI

      • user [String] Proxy server username

      • password [String] Proxy server password

    • params_encoder [Hash] not sure what this is

    • bind [Hash] A hash with host and port values

    • boundary [String] of the boundary value

    • oauth [Hash] A hash with OAuth details

  • q (String) (defaults to: nil) —

    Simple search parameter. The value for this parameter can be a simple word or a phrase. Wildcards can be added to the simple word parameters only, e.g. ‘q=puma’ (Required)

  • datasetKey (String) (defaults to: nil) —

    Filters by the checklist dataset key (a uuid, see examples)

  • rank (String) (defaults to: nil) —

    A taxonomic rank. One of ‘class’, ‘cultivar’, ‘cultivar_group’, ‘domain’, ‘family’, ‘form’, ‘genus’, ‘informal’, ‘infrageneric_name’, ‘infraorder’, ‘infraspecific_name’, ‘infrasubspecific_name’, ‘kingdom’, ‘order’, ‘phylum’, ‘section’, ‘series’, ‘species’, ‘strain’, ‘subclass’, ‘subfamily’, ‘subform’, ‘subgenus’, ‘subkingdom’, ‘suborder’, ‘subphylum’, ‘subsection’, ‘subseries’, ‘subspecies’, ‘subtribe’, ‘subvariety’, ‘superclass’, ‘superfamily’, ‘superorder’, ‘superphylum’, ‘suprageneric_name’, ‘tribe’, ‘unranked’, or ‘variety’.

Returns:



85
86
87
88
89
90
91
92
 
# File 'lib/gbifrb/Species.rb', line 85

def self.name_suggest(q: nil, datasetKey: nil, rank: nil, limit: 100, offset: nil,
  verbose: nil, options: nil)

  arguments = { q: q, datasetKey: datasetKey, rank: rank,
    limit: limit, offset: offset }.tostrings
  opts = arguments.delete_if { |k, v| v.nil? }
  Request.new("species/suggest", opts, verbose, options).perform
end

.name_usage(key: nil, name: nil, data: 'all', language: nil, datasetKey: nil, uuid: nil, sourceId: nil, rank: nil, shortname: nil, limit: 100, offset: nil, verbose: nil, options: nil) ⇒ Array

Search for GBIF name usages

Examples:

require 'gbifrb'

speices = Gbif::Species
speices.name_usage(name: "Helianthus")
speices.name_usage(name: "Poa")

Parameters:

  • offset (Fixnum) (defaults to: nil) —

    Number of record to start at, any non-negative integer. Default: 0

  • limit (Fixnum) (defaults to: 100) —

    Number of results to return. Default: 100

  • verbose (Boolean) (defaults to: nil) —

    Print request headers to stdout. Default: false

  • options (Hash) (defaults to: nil) —

    Hash of options for configuring the request, passed on to Faraday.new

    • timeout [Fixnum] open/read timeout Integer in seconds

    • open_timeout [Fixnum] read timeout Integer in seconds

    • proxy [Hash] hash of proxy options

      • uri [String] Proxy Server URI

      • user [String] Proxy server username

      • password [String] Proxy server password

    • params_encoder [Hash] not sure what this is

    • bind [Hash] A hash with host and port values

    • boundary [String] of the boundary value

    • oauth [Hash] A hash with OAuth details

  • key (Fixnum) (defaults to: nil) —

    A GBIF key for a taxon

  • name (String) (defaults to: nil) —

    Filters by a case insensitive, canonical namestring, e.g. ‘Puma concolor’

  • data (String) (defaults to: 'all') —

    The type of data to get. Default: ‘all’. Options: ‘all’, ‘verbatim’, ‘name’, ‘parents’, ‘children’, ‘related’, ‘synonyms’, ‘descriptions’, ‘distributions’, ‘media’, ‘references’, ‘speciesProfiles’, ‘vernacularNames’, ‘typeSpecimens’, ‘root’

  • language (String) (defaults to: nil) —

    Language, default is english

  • datasetKey (String) (defaults to: nil) —

    Filters by the dataset’s key (a uuid)

  • uuid (String) (defaults to: nil) —

    A uuid for a dataset. Should give exact same results as datasetKey.

  • sourceId (Fixnum) (defaults to: nil) —

    Filters by the source identifier.

  • rank (String) (defaults to: nil) —

    Taxonomic rank. Filters by taxonomic rank as one of: ‘CLASS’, ‘CULTIVAR’, ‘CULTIVAR_GROUP’, ‘DOMAIN’, ‘FAMILY’, ‘FORM’, ‘GENUS’, ‘INFORMAL’, ‘INFRAGENERIC_NAME’, ‘INFRAORDER’, ‘INFRASPECIFIC_NAME’, ‘INFRASUBSPECIFIC_NAME’, ‘KINGDOM’, ‘ORDER’, ‘PHYLUM’, ‘SECTION’, ‘SERIES’, ‘SPECIES’, ‘STRAIN’, ‘SUBCLASS’, ‘SUBFAMILY’, ‘SUBFORM’, ‘SUBGENUS’, ‘SUBKINGDOM’, ‘SUBORDER’, ‘SUBPHYLUM’, ‘SUBSECTION’, ‘SUBSERIES’, ‘SUBSPECIES’, ‘SUBTRIBE’, ‘SUBVARIETY’, ‘SUPERCLASS’, ‘SUPERFAMILY’, ‘SUPERORDER’, ‘SUPERPHYLUM’, ‘SUPRAGENERIC_NAME’, ‘TRIBE’, ‘UNRANKED’, ‘VARIETY’

  • shortname (String) (defaults to: nil) —

    A short name..need more info on this?

Returns:

  • (Array) —

    An array of hashes



126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/gbifrb/Species.rb', line 126

def self.name_usage(key: nil, name: nil, data: 'all', language: nil,
  datasetKey: nil, uuid: nil, sourceId: nil, rank: nil, shortname: nil,
  limit: 100, offset: nil, verbose: nil, options: nil)

  arguments = { key: key, name: name, data: data,
    language: language, datasetKey: datasetKey, uuid: uuid,
    sourceId: sourceId, rank: rank, shortname: shortname,
    limit: limit, offset: offset }.tostrings
  opts = arguments.delete_if { |k, v| v.nil? }
  Request.new("species/", opts, verbose, options).perform
end