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:



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

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:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/gbifrb/Species.rb', line 187

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:



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

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(name: nil, language: nil, datasetKey: nil, sourceId: 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

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

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

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

    Language, default is english

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

    Filters by the dataset’s key (a uuid)

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

    Filters by the source identifier.

Returns:

  • (Array) —

    An array of hashes



110
111
112
113
114
115
116
117
 
# File 'lib/gbifrb/Species.rb', line 110

def self.name_usage(name: nil, language: nil, datasetKey: nil, sourceId: nil,
  limit: 100, offset: nil, verbose: nil, options: nil)

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