gnfinder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eae6b30a26b68c5f5ccba1be049217ab729193362b9fc0d8beabc9e3f552b282
+  data.tar.gz: bf0663a41af4296984664f7568ea2d773a07dff823d9181e2cfa073a8f15cb32
+SHA512:
+  metadata.gz: 1c1cc186e55feca2b0ea65b9ebbd05faf8190ed6bbefddd51f70c605e88d180686e594a0d0e7174387087c50b5d88cc6f554e49905120b7be55a0ef74ebacd7b
+  data.tar.gz: 9785c062cbf89f645434d0e5e796a71d33c9406ef64d8ead8b9e9795f5525fd9a98ccfb09a124e58e3344cba50883fae7c200a3ce9de7249546b111940105b7e

data/.gitignore

@@ -0,0 +1,51 @@
+*.gem
+*.rbc
+.byebug_history
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,10 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  Exclude:
+    - 'lib/protob_pb.rb'
+    - 'lib/protob_services_pb.rb'
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## Unreleased
+
+## [v0.1.0]
+
+- Add [#5]: add an optional list of preferred data-sources for verification
+- Add [#4]: add an option for verification of found names
+- Add [#3]: enable sending options to gRPC service
+- Add [#2]: send a text and receive found names
+- Add [#1]: connect to gRPC server of `gnfinder` Go-lang program
+
+## Footnotes
+
+This document follows [changelog guidelines]
+
+[v0.1.0]: https://github.com/GlobalNamesArchitecture/gnfinder/tree/v0.1.0
+
+[#5]: https://github.com/GlobalNamesArchitecture/gnfinder/issues/5
+[#4]: https://github.com/GlobalNamesArchitecture/gnfinder/issues/4
+[#3]: https://github.com/GlobalNamesArchitecture/gnfinder/issues/3
+[#2]: https://github.com/GlobalNamesArchitecture/gnfinder/issues/2
+[#1]: https://github.com/GlobalNamesArchitecture/gnfinder/issues/1
+
+
+[changelog guidelines]: https://github.com/olivierlacan/keep-a-changelog

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Global Names
+
+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 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

@@ -0,0 +1,185 @@
+# gnfinder
+
+Ruby gem to access functionality of [gnfinder] project written in Go. This gem
+allows to perform fast and accurate scientific name finding in UTF-8 encoded
+plain texts for Ruby-based projects.
+
+
+## Requirements
+
+This gem uses gRPC to access a running [gnfinder] server. You can find how
+to run it in [gnfinder] README file.
+
+## Installation
+
+To use the gem from Ruby proect install it using Gemfile, or manually:
+
+```bash
+gem install gnfinder
+```
+
+## Usage
+
+The purpose of this gem is to access [gnfinder] functionality out of Ruby
+applications. If you need to find names using other languages, use the
+[source code][client] of this gem for reference. For other usages read
+the original Go-lang [gnfinder] README file.
+
+First you need to create a instance of a `gnfinder` client
+
+```ruby
+import 'gnfinder'
+
+gf = Gnfinder::Client.new
+```
+
+By default the client will try to connect to `localhost:8778`. If you
+have another location for the server use:
+
+```
+import 'gnfinder'
+gf = Gnfinder.new(host: 123.123.123.123, port: 8000)
+```
+
+### Finding names in a text using default settings
+
+```ruby
+txt = File.read('utf8-text-with-names.txt')
+
+names = gf.find_names(txt)
+puts names[0].value
+puts names[0].odds
+```
+
+Returned result will have the following methods for each name:
+
+  * value: mame-string cleaned up for verification.
+  * verbatim: name-string as it was found in the text.
+  * odds: Bayes' odds value. For example odds 0.1 would mean that according to
+    the algorithm there is 1 chance out of 10 that the name-string is
+    a scientific name. This field will be empty if Bayes algorithms did not run.
+
+### Always enable Bayes search
+
+For languages that are not supported by [gnfinder] only heuristic algorithms
+are used by default, because some languages that are close to Latin (Italian,
+French, Portugese) would generate too many false positives. However you can
+override this default setting by running:
+
+```ruby
+names = gf.find_names(txt, with_bayes: true)
+```
+
+### Set a language for the text
+
+Sometimes gnfinder cannot determine the language of a text correctly. For
+example it happens when the text mostly consists of scientific names, or has
+large citations or list of references in a different language. It is possible
+to set a language for a text by hand. For supported languages
+(English and German) it will enable Bayes algorithm. For other languages
+this setting will be ignored.
+
+List of supported languages will increase with time.
+
+```ruby
+names = gf.find_names(txt, language: 'eng')
+names = gf.find_names(txt, language: 'deu')
+
+# setting is ignored, only known by gnfinder
+# 3-character notations iso-639-2 code are supported
+names = gf.find_names(txt, language: 'english')
+names = gf.find_names(txt, language: 'rus')
+```
+
+### Set verification option
+
+In case if found names need to be validated against a large collection of
+name-strings, use `with_verification` option. For each name algorithm will
+return the following information:
+
+  * match type:
+    -	``NONE``: name-string is unknown
+    - ``EXACT``: name-string matched exactly.
+    - ``CANONICAL_EXACT``: canonical form of a name-string matched exactly.
+    - ``CANONICAL_FUZZY``: fuzzy match of a canonical string.
+    - ``PARTIAL_EXACT``: only part of a name matched. For examle only genus of a
+      species was found.
+    - ``PARTIAL_FUZZY``: fuzzy match of a partial result. For example canonical
+      form of a trinomial matched on a species level with some corrections.
+  * source_id: ID of a data-source of a best matched result. Data source IDs
+    can be compared with the [data-source list]
+  * curated: true if name-string was found in some data-sources that are
+    deemed to curated by humans.
+  * path: the classification path of a matched name (if available)
+
+```ruby
+names = gf.find_names(txt, with_verification: true)
+```
+
+### Set preferred data-sources list
+
+Sometimes it is important to know if a name was found in a particular
+data-source (data-sources). There is a parameter that takes IDs from the
+[data-source list]. If a name-string was found in these data-sources, match
+results will be returned back.
+
+```ruby
+names = gf.find_names(txt, with_verification: true, sources: [1, 4, 179])
+```
+### Combination of parameters.
+
+It is possible to combine parameters. However if a parameter makes no sense in
+a particular context. It is silently ignored.
+
+```ruby
+# Runs Bayes' algorithms using English training set, runs verification and
+# returns matched results for 3 data-sources if they are available.
+names = gf.find_names(txt, language: eng, with_verification: true,
+                           sources: [1, 4, 179])
+
+# Ignores `sources:` settings, because `with_verification` is not set to `true`
+names = gf.find_names(txt, language: eng, sources: [1, 4, 179])
+```
+
+## Development
+
+This gem uses gRPC to access [gnfinder] server. gRPC in turn depends on a
+protobuf library. If you need to compile Ruby programs with protobuf you need
+to install [Go] language and download [gnfinder] project.
+
+```bash
+go get github.com/gnames/gnfinder
+```
+Then you need to run bundle from the root of the project and generate
+grpc files:
+
+```bash
+bundle
+rake grpc
+```
+
+If you get an error, you might need to set a ``GOPATH`` environment variable.
+
+After starting the server with default host and port (localhost:8778) you will
+be able to run tests for this Ruby client with:
+
+```bash
+bundle exec rake
+```
+
+To run rubocop test
+
+```bash
+bundle exec rake rubocop
+```
+
+To run tests without rubocop
+```bash
+bundle exec rspec
+```
+
+[gnfinder]: https://github.com/gnames/gnfinder
+[gnfinder recent release]: https://github.com/gnames/gnfinder/releases
+[Go]: https://golang.org/doc/install
+[client]: https://github.com/GlobalNamesArchitecture/gnfinder/blob/master/lib/gnfinder/client.rb
+[data-source list]: http://index.globalnames.org/datasource

data/Rakefile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler'
+require 'bundler/gem_tasks'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+require 'rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :grpc do
+  cmd = 'grpc_tools_ruby_protoc ' \
+        '-I $GOPATH/src/github.com/gnames/gnfinder/protob ' \
+        '--ruby_out=lib --grpc_out=lib ' \
+        '$GOPATH/src/github.com/gnames/gnfinder/protob/protob.proto'
+  puts cmd
+  `#{cmd}`
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+task default: %i[rubocop grpc spec]

data/gnfinder.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+
+require 'gnfinder/version'
+
+Gem::Specification.new do |gem|
+  gem.name = 'gnfinder'
+  gem.homepage = 'http://github.com/GlobalNamesArchitecture/gnfinder'
+  gem.version = Gnfinder::VERSION
+  gem.authors = ['Dmitry Mozzherin']
+  gem.license = 'MIT'
+  gem.summary = 'Scientific names finder'
+  gem.description = %(The gem searches for scientific names in texts using
+                     gRPC server running gnfinder app written in Go language)
+  gem.email = 'dmozzherin@gmail.com'
+
+  gem.files         = `git ls-files -z`
+                      .split("\x0")
+                      .reject { |f| f.match(%r{^(test|spec|features)/}) }
+
+  gem.require_paths = ['lib']
+  gem.required_ruby_version = '~> 2.5'
+  gem.add_development_dependency 'bundler', '~> 1.16'
+  gem.add_development_dependency 'byebug', '~> 10.0'
+  gem.add_development_dependency 'grpc', '~> 1.15'
+  gem.add_development_dependency 'grpc-tools', '~> 1.15'
+  gem.add_development_dependency 'rake', '~> 12.3'
+  gem.add_development_dependency 'rspec', '~> 3.8'
+  gem.add_development_dependency 'rubocop', '~> 0.59'
+end

data/lib/gnfinder.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'gnfinder/version'
+require_relative 'protob_pb.rb'
+require_relative 'protob_services_pb.rb'
+require_relative 'gnfinder/client'
+
+# Gnfinder is a namespace module for gndinfer gem.
+module Gnfinder
+end

data/lib/gnfinder/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gnfinder
+  # Gnfinder::Client connects to gnfinder server
+  class Client
+    def initialize(host = '0.0.0.0', port = '8778')
+      @stub = Protob::GNFinder::Stub.new("#{host}:#{port}",
+                                         :this_channel_is_insecure)
+    end
+
+    def ping
+      @stub.ping(Protob::Void.new).value
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+    def find_names(text, opts = {})
+      raise 'Text cannot be empty' if text.to_s.strip == ''
+
+      params = { text: text }
+      params[:with_bayes] = true if opts[:with_bayes]
+      params[:language] = opts[:language] if opts[:language].to_s.strip != ''
+      params[:with_verification] = true if opts[:with_verification]
+      if opts[:sources] && !opts[:sources].empty?
+        params[:sources] = opts[:sources]
+      end
+
+      @stub.find_names(Protob::Params.new(params)).names
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+  end
+end

data/lib/gnfinder/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Gnfinder is a namespace module for gndinfer gem.
+module Gnfinder
+  VERSION = '0.1.0'
+
+  def self.version
+    VERSION
+  end
+end

data/lib/protob_pb.rb

@@ -0,0 +1,59 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: protob.proto
+
+require 'google/protobuf'
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_message "protob.Pong" do
+    optional :value, :string, 1
+  end
+  add_message "protob.Void" do
+  end
+  add_message "protob.Params" do
+    optional :text, :bytes, 1
+    optional :with_bayes, :bool, 3
+    optional :language, :string, 4
+    optional :with_verification, :bool, 5
+    repeated :sources, :int32, 6
+  end
+  add_message "protob.NameStrings" do
+    optional :text, :bytes, 3
+    repeated :names, :message, 6, "protob.NameString"
+  end
+  add_message "protob.NameString" do
+    optional :value, :string, 1
+    optional :verbatim, :string, 2
+    optional :odds, :float, 3
+    optional :path, :string, 4
+    optional :curated, :bool, 5
+    optional :edit_distance, :int32, 6
+    optional :edit_distance_stem, :int32, 7
+    optional :source_id, :int32, 8
+    optional :match, :enum, 9, "protob.MatchType"
+    repeated :sources_result, :message, 10, "protob.SourceResult"
+  end
+  add_message "protob.SourceResult" do
+    optional :source_id, :int32, 1
+    optional :title, :string, 2
+    optional :name_id, :string, 3
+    optional :taxon_id, :string, 4
+  end
+  add_enum "protob.MatchType" do
+    value :NONE, 0
+    value :EXACT, 1
+    value :CANONICAL_EXACT, 2
+    value :CANONICAL_FUZZY, 3
+    value :PARTIAL_EXACT, 4
+    value :PARTIAL_FUZZY, 5
+  end
+end
+
+module Protob
+  Pong = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.Pong").msgclass
+  Void = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.Void").msgclass
+  Params = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.Params").msgclass
+  NameStrings = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.NameStrings").msgclass
+  NameString = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.NameString").msgclass
+  SourceResult = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.SourceResult").msgclass
+  MatchType = Google::Protobuf::DescriptorPool.generated_pool.lookup("protob.MatchType").enummodule
+end

data/lib/protob_services_pb.rb

@@ -0,0 +1,23 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: protob.proto for package 'protob'
+
+require 'grpc'
+require 'protob_pb'
+
+module Protob
+  module GNFinder
+    class Service
+
+      include GRPC::GenericService
+
+      self.marshal_class_method = :encode
+      self.unmarshal_class_method = :decode
+      self.service_name = 'protob.GNFinder'
+
+      rpc :Ping, Void, Pong
+      rpc :FindNames, Params, NameStrings
+    end
+
+    Stub = Service.rpc_stub_class
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: gnfinder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dmitry Mozzherin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: grpc-tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.59'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.59'
+description: |-
+  The gem searches for scientific names in texts using
+                       gRPC server running gnfinder app written in Go language
+email: dmozzherin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- gnfinder.gemspec
+- lib/gnfinder.rb
+- lib/gnfinder/client.rb
+- lib/gnfinder/version.rb
+- lib/protob_pb.rb
+- lib/protob_services_pb.rb
+homepage: http://github.com/GlobalNamesArchitecture/gnfinder
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Scientific names finder
+test_files: []