colrapi 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd57d805f97201c9f050d7af940ebcca77e853f7b43ca5c7282225789817a083
-  data.tar.gz: d86a91635ea40384db919990728e4f14e164b6915910ba066b0fd6439743fe6e
+  metadata.gz: 8fdc3cd60c5c9678fa5f5feb8706a91ff121374f9a84966224b8824ff4a97397
+  data.tar.gz: b2a57d1fc5eaa08288359b44905358511d75a5dfa084368b9f77c8e70c488447
 SHA512:
-  metadata.gz: 82125cb4367f4ced07316de2c1bec8ae2401b176ff9844f23fbb5400d4304667dec532070f0d1b7d5b021ec86646167e649df7c89859339b37c6bed7ec91da8e
-  data.tar.gz: 9159517b23fc36d214d6e0c1fc611c15d027c2dc58409c859f8c3486728305526d2ec1508c564ebc7ad6bc1bf21e047d989ea08dce8346bdecbee15c05b34ca9
+  metadata.gz: 6d0f6fc5211efc5da06e31c56188fd039d1ab8bef714a969d87db5398ea8ec1f5e9d49f0762019c51e11050ed85a80e4c18543d5310f29e5dcfe85161da8a9c6
+  data.tar.gz: 8101188650f8034ecc4ae36a51bdc57d132984f85a908ae35b906e5f79e00737c29b8b4d27f65e749e7e6f9586e47b11ce66e45e64523be619192e54fd2a41b1

data/.gitignore

@@ -1,4 +1,5 @@
 .byebug_history
+.vscode
 .idea
 /.bundle/
 /.yardoc
@@ -9,4 +10,4 @@
 /spec/reports/
 /tmp/
 *.gem
-Gemfile.lock
+Gemfile.lock

data/CHANGELOG.md

@@ -1,4 +1,8 @@
 ## [Unreleased]
+ - Updated license from NCSA to MIT
+
+## [0.1.3] - 2025-03-04
+ - Added environment and highest_taxon_id to name_usage_search
 
 ## [0.1.2] - 2024-09-11
  - Removed Gemfile.lock

data/LICENSE.txt

@@ -1,21 +1,10 @@
 The MIT License (MIT)
 
-Copyright (c) 2022 mjy
+Copyright © 2024 Species File Group
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/README.md

@@ -18,11 +18,154 @@ Or install it yourself as:
 
     $ gem install colrapi
 
-## Usage
 
-In development, this is it for now:
+## Documentation
+
+Most of the [ChecklistBank/Catalogue of Life API](https://api.checklistbank.org) is wrapped by the Colrapi gem, but not everything is documented yet. Looking through the [tests](https://github.com/SpeciesFileGroup/colrapi/tree/main/test) is a good way to see examples and learn how to use the Ruby gem. If you need something documented, please [open an issue](https://github.com/SpeciesFileGroup/colrapi/issues/new) ticket.
+
+The Colrapi Ruby gem uses dataset_id to access information scoped within a dataset. There are [4 types of datasets](https://api.checklistbank.org/vocab/datasetorigin) in ChecklistBank: `external`, `project`, `release`, and `xrelease`. Most datasets are `external`, maintained outside of ChecklistBank and imported. A `project` is a draft version of a dataset assembled inside ChecklistBank from `external` datasets (e.g., [Catalogue of Life](https://www.checklistbank.org/dataset/3/about)). A `release` is a published dataset released from a `project` (e.g., [Catalogue of Life 2024 Annual Checklist](https://www.checklistbank.org/dataset/COL24/about)). An `xrelease` is a published dataset in which automated tools were used to extend a `release` dataset with additional information to fill in data gaps and have less editorial scrutiny. For example, this can mean that a very carefully scrutinized `external` dataset can be assembled into a project, published with some editorial decisions as a `release` and also extended to include missing names that a taxonomic expert might have deliberately excluded from their taxonomic database for various reasons in an `xrelease`. `xrelease` datasets aim to meet the use case of being able to attach occurrences and other data to a (nearly) complete list of scientific names. If you want the more expert scrutinized version of COL, then use a `release`. If you want to attach data to a complete list of scientific names and are less concerned about taxonomic scrutiny, then use an `xrelease`. (There may be no public COL `xrelease` datasets yet as the feature is currently under development.)
+
+Catalogue of Life has dataset_id=3, but you should almost never use dataset_id=3 because it is a draft unreleased version of COL and can have errors while the releases are being produced. Instead use 3LR to get the COL latest release, or 3LXR to get the COL latest extended release. COL releases new editions each month and the monthly releases are eventually deleted. If you need stable data that will be persistently accessible, then use the dataset_id=COLYY, where YY is the Annual Checklist year (e.g. COL24 to get the 2024 Annual Checklist). COL aims to keep the annual checklists permanently accessible, but the best practice is to download a copy of the data and archive it permanently with any research papers that use COL. Download a copy here, replacing {dataset_id} with the dataset_id: https://www.checklistbank.org/dataset/{dataset_id}/download
+
+### Dataset
+
+Get a list of external datasets in ChecklistBank:
+```ruby
+Colrapi.dataset(origin: 'external')
+```
+
+#### [/dataset](http://api.checklistbank.org/#/default/search)
+Get a list of projects in ChecklistBank:
+```ruby
+Colrapi.dataset(origin: 'project')
+```
+
+Get a list of releases in ChecklistBank released from Catalogue of Life:
+```ruby
+Colrapi.dataset(origin: 'release', released_from: 3)
+```
+
+Get a list of xreleases in ChecklistBank released from Catalogue of Life:
+```ruby
+Colrapi.dataset(origin: 'xrelease', released_from: 3)
+```
+
+Get a list of datasets that contribute to Catalogue of Life:
+```ruby
+Colrapi.dataset(contributes_to: 3)
+```
+
+Get a list of datasets under a specific [license](https://api.checklistbank.org/vocab/license):
+```ruby
+Colrapi.dataset(license: 'cc by')
+```
+
+### Names
+
+
+
+
+### Metadata
+
+Get metadata by dataset_id:
+```ruby
+Colrapi.dataset(dataset_id: 'COL24')
+```
+
+
+### Name usage search
+
+There are a two ways to conduct name usage search in ChecklistBank/Catalogue of Life: 1) using Elasticsearch or 2) querying PostgreSQL directly. Elasticsearch offers more advanced search functionality and parameters while PostgreSQL might perform faster.
+
+#### 1) Elasticsearch 
+##### [/nameusage/search](http://api.checklistbank.org/#/default/search_4) or [/dataset/{dataset_id}/nameusage/search](http://api.checklistbank.org/#/default/searchDataset)
+
+Elasticsearch all of ChecklistBank:
+```ruby
+Colrapi.nameusage_search(q: 'Homo sapiens') #  => MultiJson object
+```
+
+Elasticsearch the Catalogue of Life latest release:
+```ruby
+Colrapi.nameusage_search(dataset_id: '3LR', q: 'Homo sapiens') #  => MultiJson object
+```
+
+Elasticsearch the Catalogue of Life 2024 Annual Checklist:
+```ruby
+Colrapi.nameusage_search(dataset_id: 'COL24', q: 'Homo sapiens') #  => MultiJson object
+```
+
+Elasticsearch Orthoptera Species File:
+```ruby
+Colrapi.nameusage_search(dataset_id: 1021, q: 'Cyphoderris strepitans') #  => MultiJson object
+```
+
+#### 2) PostgreSQL Search
+##### [/dataset/{dataset_id}/nameusage](https://api.checklistbank.org/#/default/list_3)
+Query PostgreSQL directly for *Homo sapiens* in the Catalogue of Life latest release:
+```ruby
+Colrapi.nameusage('3LR', q: 'Homo sapiens') #  => MultiJson object
+```
+
+Query PostgreSQL directly for *Homo sapiens* in the Catalogue of Life 2024 Annual Checklist:
+```ruby
+Colrapi.nameusage('COL24', q: 'Homo sapiens') #  => MultiJson object
+```
+
+Query PostgreSQL directly for *Cyphoderris strepitans* in Orthoptera Species File
+```ruby
+Colrapi.nameusage(1021, q: 'Cyphoderris strepitans') #  => MultiJson object
+```
+
+## Taxon
+Get a taxon from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3') #  => MultiJson object
+```
+
+Get the higher classification for a taxon from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'classification') #  => MultiJson object
+```
+
+Get the distribution for a taxon from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'distribution') #  => MultiJson object
+```
+
+Get additional info about a taxon from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'info') #  => MultiJson object
+```
+
+Get species interactions for a taxon from 3i World Auchenorrhyncha Database by taxon ID:
+```ruby
+Colrapi.taxon(2317, taxon_id: 28472, subresource: 'interaction') #  => MultiJson object
+```
+
+Get media for a taxon from WoRMS World Porifera Database by taxon ID:
+```ruby
+Colrapi.taxon(1044, taxon_id: 'urn:lsid:marinespecies.org:taxname:166055', subresource: 'media') #  => MultiJson object
+```
+
+Get a source information from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'source') #  => MultiJson object
+```
+
+Get synonyms from the Catalogue of Life latest release by taxon ID:
+```ruby
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'synonyms') #  => MultiJson object
+```
+
+Get a taxonomic treatment from a Plazi dataset by taxon ID:
+```ruby
+Colrapi.taxon('49590', taxon_id: '03D087F29465E83AFCF39B19FA20FC96.taxon', subresource: 'treatment') #  => MultiJson object
+```
+
+Get vernacular names from the Catalogue of Life latest release by taxon ID:
 ```ruby
- res = Colrapi.nameusage(q: 'Homo sapiens') #  => MultiJson object
+Colrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'vernacular') #  => MultiJson object
 ```
 
 ## Development
@@ -37,7 +180,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/mjy/co
 
 ## License
 
-The gem is available as open source under the terms of the [NCSA/Illinois](https://opensource.org/licenses/NCSA).
+The gem is available as open source under the terms of the [MIT](https://opensource.org/licenses/MIT) license.
 
 ## Code of Conduct
 

data/colrapi.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.summary       = "Catalog of Life Client"
   s.description   = "colrapi (a play on Kholrabi) is a low-level wrapper around the Catalog of Life API."
   s.homepage      = "https://github.com/SpeciesFileGroup/colrapi"
-  s.license       = "NCSA"
+  s.license       = "MIT"
   s.required_ruby_version = ">= 2.5.0"
 
  # s.metadata["allowed_push_host"] = "TODO: Set to 'https://mygemserver.com'"

data/lib/colrapi/request.rb

@@ -29,6 +29,8 @@ module Colrapi
       @facet = Array(args[:facet]) if args[:facet]
       @min_rank = args[:min_rank]
       @max_rank = args[:max_rank]
+      @environment = args[:environment]
+      @highest_taxon_id = args[:highest_taxon_id]
       @parent_rank = args[:parent_rank]
       @root_id = Array(args[:root_id]) if args[:root_id]
       @root2_id = Array(args[:root2_id]) if args[:root2_id]
@@ -130,6 +132,7 @@ module Colrapi
                subgenus: @within_subgenus, section: @within_section, species: @within_species,
                nidx: @nidx_id, state: @state, running: @running, notCurrentOnly: @not_current_only,
                broken: @broken, subjectDatasetKey: @subject_dataset_id, mode: @mode, subject: @subject,
+               TAXON_ID: @highest_taxon_id, environment: @environment,
                sortBy: @sort_by, reverse: @reverse, url: @url, offset: @offset, limit: @limit}
       opts = args.delete_if { |_k, v| v.nil? }
 

data/lib/colrapi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Colrapi
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/colrapi.rb

@@ -437,7 +437,7 @@ module Colrapi
   end
 
   # Get name usages or a nameusage from a dataset
-  #   Note: Queries the PSQL database, whereas nameusage_search uses Elastic Search
+  #   Note: Queries the PostgreSQL database, whereas nameusage_search uses Elasticsearch
   #
   # @param dataset_id [String] The dataset id
   # @param nameusage_id [String] The nameusage id
@@ -551,6 +551,8 @@ module Colrapi
   # @param min_rank [String, nil] minimum taxonomic rank of name usages
   # @param max_rank [String, nil] maximum taxonomic rank of name usages
   # @param facet [Array, String, nil] the search facet
+  # @param environment [Array, String, nil] filter by environment (MARINE, TERRESTRIAL, FRESHWATER, BRACKISH)
+  # @param highest_taxon_id [String, nil] Filter by highest taxon ID
   #
   # @param sort_by [String, nil] sort results by NAME, TAXONOMIC, INDEX_NAME_ID, NATIVE, or RELEVANCE
   # @param reverse [Boolean] sort in reverse order
@@ -560,8 +562,8 @@ module Colrapi
   #
   # @return [Array, Boolean] An array of hashes
   def self.nameusage_search(q: nil, dataset_id: nil, endpoint: 'nameusage/search', content: nil, issue: nil,
-                            type: nil, rank: nil, min_rank: nil, max_rank: nil, facet: nil,
-                            sort_by: nil, reverse: nil, offset: nil, limit: nil,
+                            type: nil, rank: nil, min_rank: nil, max_rank: nil, environment: nil, facet: nil,
+                            highest_taxon_id: nil, sort_by: nil, reverse: nil, offset: nil, limit: nil, 
                             verbose: false)
 
     # a nil dataset_id will search name usages from all datasets in ChecklistBank
@@ -570,8 +572,9 @@ module Colrapi
     end
 
     Request.new(endpoint: endpoint, q: q, content: content, issue: issue, type: type,
-                rank: rank, min_rank: min_rank, max_rank: max_rank, facet: facet,
-                sort_by: sort_by, reverse: reverse, offset: offset, limit: limit, verbose: verbose).perform
+                rank: rank, min_rank: min_rank, max_rank: max_rank, facet: facet, environment: environment,
+                highest_taxon_id: highest_taxon_id, sort_by: sort_by, reverse: reverse,
+                offset: offset, limit: limit, verbose: verbose).perform
   end
 
   # Get a name usage suggestion

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: colrapi
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Matt Yoder, Geoff Ower
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2025-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -194,11 +194,11 @@ files:
 - lib/colrapi/version.rb
 homepage: https://github.com/SpeciesFileGroup/colrapi
 licenses:
-- NCSA
+- MIT
 metadata:
   homepage_uri: https://github.com/SpeciesFileGroup/colrapi
   source_code_uri: https://github.com/SpeciesFileGroup/colrapi
-  changelog_uri: https://github.com/SpeciesFileGroup/colrapi/releases/tag/v0.1.2
+  changelog_uri: https://github.com/SpeciesFileGroup/colrapi/releases/tag/v0.1.3
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -214,7 +214,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Catalog of Life Client