petrovich 0.0.7 → 0.1.0

data/README.md

@@ -1,6 +1,7 @@
-![Petrovich Logo](https://raw.github.com/rocsci/petrovich/master/petrovich.png)
+![Petrovich Logo](petrovich.png)
 
-Склонение падежей русских имён, фамилий и отчеств. Вы задаёте начальное имя в именительном падеже, а получаете в нужном вам.
+Склонение падежей русских имён, фамилий и отчеств. Вы задаёте начальное имя
+в именительном падеже, а получаете в нужном вам.
 
 [![Build Status](https://secure.travis-ci.org/rocsci/petrovich.png)](http://travis-ci.org/rocsci/petrovich)
 
@@ -10,36 +11,47 @@
 
     gem 'petrovich'
 
-Установите гем:
+Установите гем cредствами Bundler:
 
     $ bundle
 
-Или, установите отдельно:
+Или установите его отдельно:
 
     $ gem install petrovich
 
-## Зависимоси
+## Зависимости
 
- * Ruby >= 1.9.1
- * Не зависит от Rails
+Для работы гема требуется Ruby не младше версии 1.9.1. Petrovich не
+привязан к Ruby on Rails и может свободно использоваться практически
+в любых приложениях и библиотеках на Ruby.
 
 ## Использование
 
-Вы задаёте начальные значения (фамилию, имя и отчество) в именительном падеже. Самое простое использование выглядит так:
+Вы задаёте начальные значения (фамилию, имя и отчество) в именительном
+падеже.
 
 ```ruby
-# Указание пола снижает количество отказов
 p = Petrovich.new(:male)
 p.lastname('Иванов', :dative)      # => Иванову
 p.firstname('Пётр', :dative)       # => Петру
 p.middlename('Сергеевич', :dative) # => Сергеевичу
 ```
 
-Конструктор класса `Petrovich` принимает пол в качестве единственного аргумента. Пол может иметь значения `:male`, `:female` или `:androgynous`. Последнее означает, что имя не склоняется по родам. Обычно, не склоняются украинские фамилии, как например фамилия Симоненко, а так же фамилии, пришедшие в русский язык из европейских языков, например - Нельсон. Но всегда лучше, если пол вам известен и вы указываете его - так увеличивается вероятность правильного распознавания.
+Конструктор класса `Petrovich` принимает пол в качестве единственного
+аргумента. Пол может принимать значения `:male`, `:female` или
+`:androgynous`. Последнее означает, что слово не склоняется по родам.
+По нормам языка, некоторые фамилии не склоняются. Например, такие
+украинские фамилии, как Симоненко, а также заимствованные фамилии,
+такие как Нельсон.
+
+Важно понимать, что явное указание пола повышает точность обработки слов.
+Если пол не известен, однако известно отчество, то гем постарается
+определить по пол отчеству на основе простой эвристики.
 
 ### Продвинутое использование
 
-Вы можете подмешать модуль `Petrovich::Extension` в любой класс. Это особенно полезно при использовании `ActiveRecord` и подобных ORM:
+Вы можете подмешать модуль `Petrovich::Extension` в любой класс. Это
+особенно полезно при использовании ActiveRecord и подобных ORM.
 
 ```ruby
 class User < ActiveRecord::Base
@@ -71,7 +83,8 @@ class User < ActiveRecord::Base
 end
 ```
 
-Или, подмешиваем в обычный класс:
+Ничего не мешает подмешать модуль `Petrovich::Extension` в самый обычный
+класс.
 
 ```ruby
 class Person
@@ -96,7 +109,13 @@ class Person
 end
 ```
 
-В примерах выше, вы указываете при помощи метода `petrovich` соответствие фамилии, имени и отчества методам или атрибутам класса. После этого, вы легко можете склонять имена, используя следующий синтаксис вызовов:
+При помощи метода `petrovich` указываются методы, представляющие фамилию,
+имя и отчество. В данном примере указано, что метод `name` представляет
+имя, метод `lastname` представляет фамилию, метод `patronymic` представляет
+отчество.
+
+После конфигурации Petrovich можно легко выполнять склонение необходимых
+строк.
 
 ```ruby
 user = User.new
@@ -107,8 +126,6 @@ user.my_middlename_dative # => Петровичу
 user.my_lastname_dative   # => Петренко
 ```
 
-и для второго примера:
-
 ```ruby
 person = Person.new
 person.name # => Иван
@@ -117,44 +134,91 @@ person.my_firstname_dative  # => Ивану
 person.my_middlename_dative # => Олеговичу
 person.my_lastname_dative   # => Сафронову
 ```
-Изначальное имя должно быть в именительнои падеже. Вы просто добавляете `_падеж` в конец имени оригинального метода и получаете нужное значение. Вот список суффиксов, которые вы можете добавить к имени оригинального метода, чтобы получить имя в нужном падаже:
 
- * genitive        - родительный
- * dative          - дательный
- * accusative      - винительный
- * instrumentative - творительный
- * prepositional   - предложный
+Базовое имя должно быть в именительном падеже. Вы просто добавляете
+`_падеж` в конец имени оригинального метода и получаете заданное имя
+в требуемом падеже.
 
-## Разработчики
+Вот список суффиксов, которые вы можете добавить к имени метода, чтобы
+получить имя в нужном падеже:
 
- * [Андрей Козлов](https://github.com/tanraya) - идея, реализация
- * [Дмитрий Усталов](http://eveel.ru) - неоценимая помощь
+ * genitive      — родительный;
+ * dative        — дательный;
+ * accusative    — винительный;
+ * instrumental  — творительный;
+ * prepositional — предложный.
 
-## Дальнейшее развитие
+## Оценка точности
 
-Мы планируем и далее улучшать этот проект. Поэтому, нам важен отклик от других разработчиков, использующих этот гем. Вот наши планы:
+Тестирование гема при склонении коллекции фамилий из морфологического
+словаря [АОТ] показало точность около 99%. Оригинальный словарь
+распространяется по лицензии LGPL версии 2.1, однако используется
+только в задаче оценки точности данного гема.
 
- * Тесты на базу фамилий.
- * Добавить debug-mode, чтобы видеть, какое именно правило применилось
- * Cli-interface, чтобы работать с гемом из коммандной строки
- * Веб-интерфейс для проверки имён (ф.и.о) и их логгирования, для улучшения правил распознавания.
- * Проверка работы с mongoid и mongo-mapper
+Для оценки точности достаточно выполнить команду `rake evaluate`. После
+выполнения этой команды в поток стандартного вывода будут напечатаны
+результаты оценки с данными в словаре АОТ.
 
-Если вы хотите помочь этому проекту, вы можете реализовать любой план из перечисленных выше. Но прежде свяжитесь с разработчиками, чтобы ваши и наши планы не пересекались.
+```
+Pr(nominative|male) = 100.0000%
+Pr(genitive|male) = 99.6763%
+Pr(dative|male) = 99.7012%
+Pr(accusative|male) = 99.7261%
+Pr(instrumental|male) = 97.9485%
+Pr(prepositional|male) = 99.6888%
+```
+```
+Pr(nominative|female) = 100.0000%
+Pr(genitive|female) = 99.8652%
+Pr(dative|female) = 99.8952%
+Pr(accusative|female) = 99.9251%
+Pr(instrumental|female) = 99.4189%
+Pr(prepositional|female) = 99.8952%
+```
 
-## Тестирование
+В настоящий момент наблюдается точность в 99.6275% на основе обработки
+88314 примеров.
 
-Чтобы запустить тесты, тестирующие фамилии, нужно установить `ENV` переменную:
+[АОТ]: http://seman.svn.sourceforge.net/viewvc/seman/trunk/Docs/Morph_UNIX.txt?revision=HEAD&view=markup
 
-```
+## Модульные тесты
+
+Чтобы запустить тесты, тестирующие фамилии, нужно установить переменную
+окружения `TEST_SURNAMES`:
+
+```shell
 TEST_SURNAMES=1 rspec
 ```
 
+## Разработчики
+
+ * [Андрей Козлов](https://github.com/tanraya) — идея, реализация.
+ * [Дмитрий Усталов](http://eveel.ru) — неоценимая помощь.
+
+## Дальнейшее развитие
+
+Мы планируем и далее улучшать этот проект. Поэтому нам важен отклик от
+пользователей данного гема. Вот наши планы:
+
+ * добавить отладочный режим, чтобы видеть, какое именно правило было
+использовано при словообразовании;
+ * интерфейс командной строки, чтобы работать с гемом из командной строки;
+ * Web-интерфейс для обработки ФИО;
+ * проверка совместимости с различными ORM и сторонними библиотеками.
+
+Если вы хотите помочь этому проекту, вы можете реализовать любую
+вышеперечисленную идею. Перед этим желательно связаться с нами,
+чтобы мы были в курсе.
+
 ## Содействие
 
-Если вы нашли баги, как программной части, так и в словаре, вы всегда можете форкнуть репозиторий и внести необходимые правки. Ваша помощь не останется незамеченной. Если вы заметили ошибки при склонении падежей имён, фамилий или отчеств, можете написать об этом в issues. Проблема будет сразу же исследована и решена.
+Если вы нашли баги, как программной части, так и в базе правил, то вы всегда
+можете форкнуть репозиторий и внести необходимые изменения. Ваша помощь не
+останется незамеченной! Если вы заметили ошибки при склонении падежей имён,
+фамилий или отчеств, можете написать об этом в Issues на GitHub.
+Проблема будет сразу же исследована и, по возможности, решена.
 
-Не стесняйтесь добавлять улучшения. Как всегда, чтобы помочь, вам нужно:
+Не стесняйтесь добавлять улучшения.
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/Rakefile

@@ -1,9 +1,8 @@
 #!/usr/bin/env rake
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
+# encoding: utf-8
+
+require 'bundler/gem_tasks'
+
 begin
   require 'rdoc/task'
 rescue LoadError
@@ -12,7 +11,14 @@ rescue LoadError
   RDoc::Task = Rake::RDocTask
 end
 
-# Run tests by default
-task :default => :spec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :petrovich do
+  require 'petrovich'
+end
+
+# Run tests and perform evaluation by default
+task :default => [:spec, :evaluate]
 
-Bundler::GemHelper.install_tasks
+Dir.glob('lib/tasks/*.rake').each { |r| import r }

data/lib/petrovich.rb

@@ -31,18 +31,18 @@ require 'petrovich/extension'
 # * +:genitive+ - родительный
 # * +:dative+ - дательный
 # * +:accusative+ - винительный
-# * +:instrumentative+ - творительный
+# * +:instrumental+ - творительный
 # * +:prepositional+ - предложный
 #
 class Petrovich
-  CASES = [:nominative, :genitive, :dative, :accusative, :instrumentative, :prepositional]
+  CASES = [:nominative, :genitive, :dative, :accusative, :instrumental, :prepositional]
 
-  NOMINATIVE      = :nominative      # именительный
-  GENITIVE        = :genitive        # родительный
-  DATIVE          = :dative          # дательный
-  ACCUSATIVE      = :accusative      # винительный
-  INSTRUMENTATIVE = :instrumentative # творительный
-  PREPOSITIONAL   = :prepositional   # предложный
+  NOMINATIVE      = :nominative    # именительный
+  GENITIVE        = :genitive      # родительный
+  DATIVE          = :dative        # дательный
+  ACCUSATIVE      = :accusative    # винительный
+  INSTRUMENTATIVE = :instrumental  # творительный
+  PREPOSITIONAL   = :prepositional # предложный
 
   def initialize(gender = nil)
     @gender = gender.to_s

data/lib/tasks/evaluate.rake

@@ -0,0 +1,89 @@
+# encoding: utf-8
+
+require 'csv'
+
+CASES = [
+  :nominative,
+  :genitive,
+  :dative,
+  :accusative,
+  :instrumental,
+  :prepositional
+]
+
+def check!(errors, correct, total, lemma, gender, gcase, expected)
+  inflector = Petrovich.new(gender)
+  inflection = begin
+    UnicodeUtils.upcase(inflector.lastname(lemma, gcase))
+  rescue
+    ''
+  end
+
+  total[[gender, gcase]] += 1
+
+  if inflection == expected
+    correct[[gender, gcase]] += 1
+    true
+  else
+    errors << [lemma, expected, inflection, [gender, gcase]]
+    inflection
+  end
+end
+
+desc 'Evaluate the inflector on surnames'
+task :evaluate => :petrovich do
+  filename = File.expand_path('../../../spec/data/surnames.tsv', __FILE__)
+  errors_filename = ENV['errors'] || 'errors.tsv'
+
+  correct, total = Hash.new(0), Hash.new(0)
+
+  puts 'I will evaluate the inflector on "%s" ' \
+       'and store errors to "%s".' % [filename, errors_filename]
+
+  CSV.open(errors_filename, 'w', col_sep: "\t") do |errors|
+    errors << %w(lemma expected actual params)
+
+    CSV.open(filename, col_sep: "\t", headers: true).each do |row|
+      word = row['word'].force_encoding('UTF-8')
+      lemma = row['lemma'].force_encoding('UTF-8')
+
+      grammemes = if row['grammemes']
+        row['grammemes'].force_encoding('UTF-8').split(',')
+      else
+        []
+      end
+
+      gender = grammemes.include?('мр') ? :male : :female
+
+      if grammemes.include? '0'
+        # some words are aptotic so we have to ensure that
+        CASES.each do |gcase|
+          check! errors, correct, total, lemma, gender, gcase, word
+        end
+      elsif grammemes.include? 'им'
+        check! errors, correct, total, lemma, gender, :nominative, word
+      elsif grammemes.include? 'рд'
+        check! errors, correct, total, lemma, gender, :genitive, word
+      elsif grammemes.include? 'дт'
+        check! errors, correct, total, lemma, gender, :dative, word
+      elsif grammemes.include? 'вн'
+        check! errors, correct, total, lemma, gender, :accusative, word
+      elsif grammemes.include? 'тв'
+        # actually, it's called the instrumetal case
+        check! errors, correct, total, lemma, gender, :instrumental, word
+      elsif grammemes.include? 'пр'
+        check! errors, correct, total, lemma, gender, :prepositional, word
+      end
+    end
+  end
+
+  total.each do |(gender, gcase), correct_count|
+    precision = correct[[gender, gcase]] / correct_count.to_f * 100
+    puts "\tPr(%s|%s) = %.4f%%" % [gcase, gender, precision]
+  end
+
+  correct_size = correct.values.inject(&:+)
+  total_size = total.values.inject(&:+)
+  puts 'Well, the precision on %d examples is about %.4f%%.' %
+    [total_size, (correct_size / total_size.to_f * 100)]
+end

metadata

@@ -1,32 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: petrovich
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
 - Andrew Kozloff
+- Dmitry Ustalov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-29 00:00:00.000000000 Z
+date: 2013-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: unicode_utils
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -63,6 +64,7 @@ description: Вы задаёте начальное имя в именитель
   вам
 email:
 - demerest@gmail.com
+- dmitry@eveel.ru
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -71,6 +73,7 @@ files:
 - lib/petrovich/rules.rb
 - lib/petrovich/rules.yml
 - lib/petrovich.rb
+- lib/tasks/evaluate.rake
 - MIT-LICENSE
 - Rakefile
 - README.md