name_gender_classifier 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 787939c630e3a02792909f4e987711b5ce2e336b515db92f349bed2ebe696309
+  data.tar.gz: 1ad33afd9ce5b28cdb1737345b7ba4d4b104b58fd0a85aa69d88cea2339f4403
+SHA512:
+  metadata.gz: 54975df68d17a91d44292eac77e6ab4372c64f922ccd9ade1a2dee3ebe9b1a967f3a992d42b5b6367218a5cddbfce1559630b7013607b9189e377b46bc082afa
+  data.tar.gz: 52f02d8ae418868dc3f529cf5eaa357470192fb1b549bf8602797576268d7128e60fb99eafc61abc0c163e8b58ba7b87f925875048b517ae3675e3e9bec7af97

data/lib/name_gender_classifier/database_manager.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'gdbm'
+
+module NameGenderClassifier
+  # Uses GDBM database to retrieve gender classification from {DB_NAME}.
+  module DatabaseManager
+    # @return [String] the database location (which holds the classified names)
+    DB_NAME = "#{Gem.loaded_specs['name_gender_classifier'].gem_dir}/lib/"\
+              'name_gender_classifier/classified_names_pt-br.db'
+
+    # Find in the database the value for a previously saved key. The key holds the first name
+    # and the value the gender probability.
+    #
+    # @param key [String, Symbol] a key to be searched in the database
+    #
+    # @return [Float] the gender probability (value between 0 and 1, where 0 <= male < 0.5 <= female <= 1)
+    def self.find(key)
+      value = gdbm[key.to_s]
+      gdbm.close
+      @gdbm = nil
+
+      value ? value.to_f : nil
+    end
+
+    # With a block { |db| ... } allow to read multiple records with a single database open request,
+    # or return the database instance for a single read request.
+    #
+    # @yard [db] gives the database instance to the block
+    # @return [GDBM, nil] the GDBM database instance or nil if used with a block
+    def self.gdbm
+      @gdbm ||= GDBM.new(DB_NAME)
+
+      if block_given?
+        yield(@gdbm)
+
+        @gdbm.close
+        @gdbm = nil
+      else
+        @gdbm
+      end
+    end
+  end
+end

data/lib/name_gender_classifier/fallback_gender_detector.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NameGenderClassifier
+  # If no match is found in the database, this module is called to predict the
+  # gender based on the first name suffix.
+  module FallbackGenderDetector
+    # @return [String] the locale
+    LOCALE = 'PT_BR'
+
+    # @return [String] male suffix terminations for pt-br
+    PT_BR_MALE_SUFFIXES = %w[ard as el eu ex iz is o on or os ur us rge me pe se re vi].freeze
+    # @return [String] female suffix terminations for pt-br
+    PT_BR_FEMALE_SUFFIXES = %w[a ais are ari eis eme ere ese iko ime ire yse ise isse
+                               oko uko ume quel bel cao ce de dis le li lis liz lse ne
+                               nis nge ris riz sse].freeze
+
+    # Try to guess the gender based on first name suffix.
+    #
+    # @param name [String] first name
+    #
+    # @return [String] the gender
+    def self.guess_gender(name)
+      return 'female' if const_get("#{LOCALE}_FEMALE_SUFFIXES").any? { |t| name.end_with?(t) }
+      return 'male' if const_get("#{LOCALE}_MALE_SUFFIXES").any? { |t| name.end_with?(t) }
+    end
+  end
+end

data/lib/name_gender_classifier.rb

@@ -0,0 +1,108 @@
+require 'iconv'
+
+# Gender detector for first names.
+module NameGenderClassifier
+  # Return the gender(s) (probability) for the informed name(s). The result type will vary depending
+  # on the parameter type:
+  #
+  # [String, Symbol] the gender (String) is returned.
+  # [Array<String>] an array (Array<String>) with the genders is returned.
+  # [Array<Object>] an array (Array<Object>) with the same objects and the newly assigned genders is returned.
+  #
+  # @param arg [String, Symbol, Array<String>, Array<Symbol>, Array<Object>] argument holding first
+  #   name(s) information(s).
+  # @param options [Hash] first_name_attribute: name of the method that returns the first name,
+  #                       gender_attribute: name of the method which will receive the gender assignment.
+  #
+  # @return [String, Array<String>, Array<Object>] the gender classification for the passed first names
+  def self.classify(arg, options = {})
+    case arg
+    when String, Symbol
+      most_probable_gender(arg)
+    when Array
+      # Assumes that all elements within the array are of the same type as the first.
+      if arg[0].is_a?(String) || arg[0].is_a?(Symbol)
+        classify_array(arg)
+      else
+        classify_objects(arg, options)
+      end
+    end
+  end
+
+  # Return the genders (probabilistically) for the informed names.
+  #
+  # @param array [Array<String>, Array<Symbol>] see {NameGenderClassifier.classify}
+  #
+  # @return [Array<String>] see {NameGenderClassifier.classify}
+  def self.classify_array(array)
+    result = []
+    DatabaseManager.gdbm do |db|
+      array.each do |name|
+        next unless name
+
+        result << most_probable_gender(name, db)
+      end
+    end
+
+    result
+  end
+
+  # For each object in the array, it tries to classify the gender for object.first_name or
+  # object.name (or equivalent method) and save it on object.gender (or equivalent method).
+  #
+  # @param objects [Array<Object>] see {NameGenderClassifier.classify}
+  # @param options see {NameGenderClassifier.classify}
+  #
+  # @return [Array<Object>] the objects with the assigned genders
+  def self.classify_objects(objects, options = {})
+    first_name_attribute = options.fetch(:first_name_attribute, nil) ||
+                           (:first_name if defined?(objects[0].first_name)) ||
+                           (:name if defined?(objects[0].name))
+
+    if first_name_attribute.nil?
+      puts 'The object doesn\'t have the methods \'name\' nor \'first_name\'. '\
+          'Use #classify(arg, first_name_attribute: nil, gender_attribute: nil) '\
+          'to inform which methods to lookup.'
+
+      return objects
+    end
+
+    gender_attribute = options.fetch(:gender_attribute, 'gender')
+    gender_attribute_assignment = "#{gender_attribute}="
+
+    DatabaseManager.gdbm do |db|
+      objects.each do |object|
+        next unless name = object.public_send(first_name_attribute)
+
+        object.public_send(gender_attribute_assignment, most_probable_gender(name, db))
+      end
+    end
+
+    objects
+  end
+
+  # Remove whitespaces, secondary names, accents, digits and transform to string and lower case.
+  def self.remove_unwanted_chars(name)
+    # Enforce the string format, remove white spaces and discard secondary names
+    return unless name = name.to_s.strip.split(' ')[0]
+
+    # Transform to lower case, transliterate and remove non letter characters
+    Iconv.iconv('ascii//translit//ignore', 'utf-8', name.downcase)[0].gsub(/\W+/, '')
+  end
+  private_class_method :remove_unwanted_chars
+
+  # @return [String, nil] the gender of the informed name
+  def self.most_probable_gender(name, db = nil)
+    return unless name = remove_unwanted_chars(name)
+
+    if fem_probability = db ? db[name]&.to_f : DatabaseManager.find(name)
+      fem_probability >= 0.5 ? 'female' : 'male'
+    else
+      FallbackGenderDetector.guess_gender(name)
+    end
+  end
+  private_class_method :most_probable_gender
+end
+
+require 'name_gender_classifier/database_manager'
+require 'name_gender_classifier/fallback_gender_detector'

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: name_gender_classifier
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Avantsoft
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-09-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gdbm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: iconv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: Using primarily IBGE census data [2010], this gem classifies brazilian
+  first names as 'male' or 'female'.
+email: hello@avantsoft.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/name_gender_classifier.rb
+- lib/name_gender_classifier/classified_names_pt-br.db
+- lib/name_gender_classifier/database_manager.rb
+- lib/name_gender_classifier/fallback_gender_detector.rb
+homepage: https://rubygems.org/gems/name_gender_classifier
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.9
+signing_key: 
+specification_version: 4
+summary: Gender detection for brazilian first names.
+test_files: []