genealogy 1.5.0 → 2.0.0

data/lib/genealogy/constants.rb

@@ -1,24 +1,55 @@
 module Genealogy
-  PARENT2LINEAGE = { :father => :paternal, :mother => :maternal }
-  LINEAGE2PARENT = PARENT2LINEAGE.invert
-  PARENT2SEX = { :father => :male, :mother => :female }
-  SEX2PARENT = PARENT2SEX.invert
-  OPPOSITESEX = {:male => :female, :female => :male}
+  module Constants
+    # deafault options for has_parent method
+    DEFAULTS = {
+      column_names: {
+        sex: 'sex',
+        father_id: 'father_id',
+        mother_id: 'mother_id',
+        current_spouse_id: 'current_spouse_id',
+        birth_date: 'birth_date',
+        death_date: 'death_date'
+      },
+      perform_validation: true,
+      ineligibility: :pedigree,
+      current_spouse: false,
+      sex_values: ['M','F'],
+      limit_ages: {
+        min_male_procreation_age: 12,
+        max_male_procreation_age: 75,
+        min_female_procreation_age: 9,
+        max_female_procreation_age: 50,
+        max_male_life_expectancy: 110,
+        max_female_life_expectancy: 110
+      }
+    }
 
-  AKA = {
-    :father => "F",
-    :mother => "M",
-    :paternal_grandfather => "PGF", 
-    :paternal_grandmother => "PGM", 
-    :maternal_grandfather => "MGF", 
-    :maternal_grandmother => "MGM", 
-    :children => "C",
-    :siblings => "S", 
-    :half_siblings => "HS",
-    :paternal_half_siblings => "PHS",
-    :maternal_half_siblings => "MHS", 
-    :grandchildren => "GC", 
-    :uncles_and_aunts => "U&A", 
-    :nieces_and_nephews => "N&N"
-  }
+    # ineligibility levels
+    PEDIGREE = 1
+    PEDIGREE_AND_DATES = 2
+    OFF = 0
+
+    PARENT2LINEAGE = ActiveSupport::HashWithIndifferentAccess.new({ father: :paternal, mother: :maternal })
+    LINEAGE2PARENT = ActiveSupport::HashWithIndifferentAccess.new({ paternal: :father, maternal: :mother })
+    PARENT2SEX = ActiveSupport::HashWithIndifferentAccess.new({ father: :male, mother: :female })
+    SEX2PARENT = ActiveSupport::HashWithIndifferentAccess.new({ male: :father, female: :mother })
+    OPPOSITESEX = ActiveSupport::HashWithIndifferentAccess.new({male: :female, female: :male})
+
+    AKA = ActiveSupport::HashWithIndifferentAccess.new({
+      father: "F",
+      mother: "M",
+      paternal_grandfather: "PGF", 
+      paternal_grandmother: "PGM", 
+      maternal_grandfather: "MGF", 
+      maternal_grandmother: "MGM", 
+      children: "C",
+      siblings: "S", 
+      half_siblings: "HS",
+      paternal_half_siblings: "PHS",
+      maternal_half_siblings: "MHS", 
+      grandchildren: "GC", 
+      uncles_and_aunts: "U&A", 
+      nieces_and_nephews: "N&N"
+    })
+  end
 end

data/lib/genealogy/current_spouse_methods.rb

@@ -0,0 +1,66 @@
+module Genealogy
+  # Module CurrentSpouseMethods provides methods to manage and query current spouse. It's included by the genealogy enabled AR model
+  module CurrentSpouseMethods
+    extend ActiveSupport::Concern
+
+    include Constants
+
+    # add current spouse updating receiver and argument individuals foreign_key in a transaction
+    # @param [Object] spouse
+    # @return [Boolean] 
+    def add_current_spouse(spouse)
+
+      raise_unless_current_spouse_enabled
+      check_incompatible_relationship(:current_spouse,spouse)
+
+      if gclass.perform_validation_enabled
+        self.current_spouse = spouse
+        spouse.current_spouse = self
+        transaction do
+          spouse.save!
+          save!
+        end
+      else
+        transaction do
+          self.update_attribute(:current_spouse,spouse)
+          spouse.update_attribute(:current_spouse,self)
+        end
+      end
+
+    end
+
+    # remove current spouse resetting receiver and argument individuals foreign_key in a transaction
+    # @return [Boolean] 
+    def remove_current_spouse
+      raise_unless_current_spouse_enabled
+      if gclass.perform_validation_enabled
+        ex_current_spouse = current_spouse
+        current_spouse.current_spouse = nil
+        self.current_spouse = nil
+        transaction do
+          ex_current_spouse.save!
+          save!
+        end
+      else
+        transaction do
+          current_spouse.update_attribute(:current_spouse,nil)
+          self.update_attribute(:current_spouse,nil)
+        end
+      end
+    end
+
+    # list of individual who cannot be current spouse
+    # @return [Array]
+    def ineligible_current_spouses
+      raise_unless_current_spouse_enabled
+      self.gclass.send(ssex.to_s.pluralize)
+    end
+
+    private
+
+    def raise_unless_current_spouse_enabled
+      raise FeatureNotEnabled, "Spouse tracking not enabled. Enable it with option 'current_spouse_enabled: true' for has_parents method}" unless self.class.current_spouse_enabled
+    end
+
+  end
+end

data/lib/genealogy/exceptions.rb

@@ -1,12 +1,9 @@
 module Genealogy
-  class WrongArgumentException < RuntimeError;  end
-  class WrongOptionException < RuntimeError;  end
-  class WrongOptionValueException < RuntimeError;  end
-  class LineageGapException < RuntimeError;  end
-  class IncompatibleObjectException < RuntimeError;  end
-  class WrongSexException < RuntimeError;  end
-  class IncompatibleRelationshipException < RuntimeError
-    def initialize(msg = "Trying to create a relationship incopatible with the the existing ones")
+  class LineageGapException < StandardError;  end
+  class FeatureNotEnabled < StandardError;  end
+  class SexError < StandardError;  end
+  class IncompatibleRelationshipException < StandardError
+    def initialize(msg = "Trying to create an incompatible relationship")
       super(msg)
     end
   end

data/lib/genealogy/genealogy.rb

@@ -1,82 +1,119 @@
 module Genealogy
 
-  def check_options(options, admitted_keys)
+  extend ActiveSupport::Concern
 
-    raise WrongArgumentException, "first argument must be in a hash." unless options.is_a? Hash
-    raise WrongArgumentException, "seconf argument must be in an array." unless admitted_keys.is_a? Array
+  module ClassMethods
+    
+    include Genealogy::Constants
 
-    options.each do |key, value|
-      unless admitted_keys.include? key
-        raise WrongOptionException.new("Unknown option: #{key.inspect} => #{value.inspect}.")
+    # gives to ActiveRecord model geneaogy capabilities. Modules UtilMethods QueryMethods IneligibleMethods AlterMethods and SpouseMethods are included
+    # @param [Hash] options
+    # @option options [Boolean] current_spouse (false) specifies whether to track or not individual's current spouse
+    # @option options [Boolean] perform_validation (true) specifies whether to perform validation or not while altering pedigree that is before updating relatives external keys
+    # @option options [Boolean, Symbol] ineligibility (:pedigree) specifies ineligibility setting. If `false` ineligibility checks will be disabled and you can assign, as a relative, any individuals you want. 
+    #   This can be dangerous because you can build nosense loop (in terms of pedigree). If pass one of symbols `:pedigree` or `:pedigree_and_dates` ineligibility checks will be enabled.
+    #   More specifically with `:pedigree` (or `true`) checks will be based on pedigree topography, i.e., ineligible children will include ancestors. With `:pedigree_and_dates` check will also be based on 
+    #   procreation ages (min and max, male and female) and life expectancy (male and female), i.e. an individual born 200 years before is an ineligible mother
+    # @option options [Hash] limit_ages (min_male_procreation_age:12, max_male_procreation_age:75, min_female_procreation_age:9, max_female_procreation_age:50, max_male_life_expectancy:110, max_female_life_expectancy:110) 
+    #   specifies one or more limit ages different than defaults
+    # @option options [Hash] column_names (sex:'sex', father_id:'father_id', mother_id:'mother_id', current_spouse_id:'current_spouse_id', birth_date:'birth_date', death_date:'death_date') specifies column names to map database individual table
+    # @option options [Array] sex_values (['M','F']) specifies values used in database sex column 
+    # @return [void] 
+    def has_parents options = {}
+
+      check_options(options)
+
+      # keep track of the original extend class to prevent wrong scopes in query method in case of STI
+      class_attribute :gclass, instance_writer: false
+      self.gclass = self 
+      
+      class_attribute :ineligibility_level, instance_accessor: false
+      self.ineligibility_level = case options[:ineligibility]
+      when :pedigree
+        PEDIGREE
+      when true
+        PEDIGREE
+      when :pedigree_and_dates
+        PEDIGREE_AND_DATES
+      when false
+        OFF
+      when nil
+        PEDIGREE
+      else
+        raise ArgumentError, "ineligibility option must be one among :pedigree, :pedigree_and_dates or false"
       end
-      if block_given?
-        yield key, value
+
+      ## limit_ages
+      if ineligibility_level >= PEDIGREE_AND_DATES
+        DEFAULTS[:limit_ages].each do |age,v|
+          class_attribute age, instance_accessor: false
+          self.send("#{age}=", options[:limit_ages].try(:[],age) || v)
+        end
       end
-    end
 
-  end
+      [:current_spouse, :perform_validation].each do |opt|
+        ca = "#{opt}_enabled"
+        class_attribute ca, instance_accessor: false
+        self.send "#{ca}=", options.key?(opt) ? options[opt] : DEFAULTS[opt]
+      end
 
-  def has_parents options = {}
 
-    admitted_keys = [:sex_column, :sex_values, :father_column, :mother_column, :current_spouse_column, :current_spouse, :birth_date_column, :death_date_column, :perform_validation]
-    check_options(options, admitted_keys) do |key, value|
-      if key == :sex_values
-        raise WrongOptionException, ":sex_values option must be an array of length 2: first for male sex symbol an last for female" unless value.is_a?(Array) and value.size == 2
+      # column names class attributes
+      DEFAULTS[:column_names].merge(options[:column_names]).each do |k,v|
+        class_attribute_name = "#{k}_column"
+        class_attribute class_attribute_name, instance_accessor: false
+        self.send("#{class_attribute_name}=", v)
+        alias_attribute k, v unless k == v.to_sym
       end
-    end
 
-    class_attribute :genealogy_enabled, :current_spouse_enabled, :genealogy_class, :perform_validation
-    self.genealogy_enabled = true
-    self.current_spouse_enabled = options[:current_spouse].try(:==,true) || false           # default false
-    self.genealogy_class = self                                                             # keep track of the original extend class to prevent wrong scopes in query method in case of STI
-    self.perform_validation = options[:perform_validation].try(:==,false) ? false : true    # default true
-
-    tracked_relatives = [:father, :mother]
-    tracked_relatives << :current_spouse if current_spouse_enabled
-
-    ## sex
-    # class attributes
-    class_attribute :sex_column, :sex_values, :sex_male_value, :sex_female_value, :birth_date_column, :death_date_column
-    self.sex_column = options[:sex_column] || 'sex'
-    self.sex_values = options[:sex_values] || ['M','F']
-    self.sex_male_value = self.sex_values.first
-    self.sex_female_value = self.sex_values.last
-    self.birth_date_column = options[:birth_date_column] || 'birth_date'
-    self.death_date_column = options[:death_date_column] || 'death_date'
-    # instance attribute
-    alias_attribute :sex, sex_column if self.sex_column != 'sex'
-    # validation
-    validates_presence_of sex_column
-    validates_format_of sex_column, :with => /[#{sex_values.join}]/
-
-    tracked_relatives.each do |key|
-      # class attribute where is stored the correspondig foreign_key column name
-      class_attribute_name = "#{key}_column"
-      foreign_key = "#{key}_id"
-      class_attribute class_attribute_name
-      self.send("#{class_attribute_name}=", options[class_attribute_name.to_sym] || foreign_key)
-      # self join associations
-      belongs_to key, class_name: self, foreign_key: foreign_key
-    end
+      ## sex
+      class_attribute :sex_values, :sex_male_value, :sex_female_value, instance_accessor: false
+      self.sex_values = options[:sex_values] || DEFAULTS[:sex_values]
+      self.sex_male_value = self.sex_values.first
+      self.sex_female_value = self.sex_values.last
+      
+      # validation
+      validates_presence_of :sex
+      validates_format_of :sex, with: /[#{sex_values.join}]/
 
-    has_many :children_as_father, :class_name => self, :foreign_key => self.father_column, :dependent => :nullify, :extend => FatherAssociationExtension
-    has_many :children_as_mother, :class_name => self, :foreign_key => self.mother_column, :dependent => :nullify, :extend => MotherAssociationExtension
+      tracked_relatives = [:father, :mother]
+      tracked_relatives << :current_spouse if current_spouse_enabled
+      tracked_relatives.each do |k|
+        belongs_to k, class_name: self, foreign_key: self.send("#{k}_id_column")
+      end
 
-    # Include instance methods and class methods
-    include Genealogy::QueryMethods
-    include Genealogy::AlterMethods
-    include Genealogy::SpouseMethods if current_spouse_enabled
+      has_many :children_as_father, class_name: self, foreign_key: self.father_id_column, dependent: :nullify
+      has_many :children_as_mother, class_name: self, foreign_key: self.mother_id_column, dependent: :nullify
 
-  end
+      include Genealogy::UtilMethods
+      include Genealogy::QueryMethods
+      include Genealogy::IneligibleMethods
+      include Genealogy::AlterMethods
+      include Genealogy::CurrentSpouseMethods
 
-  module MotherAssociationExtension
-    def with(father_id)
-      where(father_id: father_id)
     end
-  end
-  module FatherAssociationExtension
-    def with(mother_id)
-      where(mother_id: mother_id)
+
+    private
+
+    def check_options(options)
+
+      raise ArgumentError, "Hash expected, #{options.class} given." unless options.is_a? Hash
+
+      # column names
+      options[:column_names] ||= {}
+      raise ArgumentError, "Hash expected for :column_names option, #{options[:column_names].class} given." unless options[:column_names].is_a? Hash
+
+      # sex
+      if array = options[:sex_values]
+        raise ArgumentError, ":sex_values option must be an array of length 2: [:male_value, :female_value]" unless array.is_a?(Array) and array.size == 2
+      end
+
+      # booleans
+      options.slice(:perform_validation, :current_spouse).each do |k,v|
+        raise ArgumentError, "Boolean expected for #{k} option, #{v.class} given." unless !!v == v
+      end
     end
+
   end
+
 end

data/lib/genealogy/ineligible_methods.rb

@@ -0,0 +1,116 @@
+module Genealogy
+  # Module IneligibleMethods provides methods to run genealogy queries to retrive groups of individuals who cannot be relatives according to provided role.
+  # It's included by the genealogy enabled AR model
+  module IneligibleMethods
+    extend ActiveSupport::Concern
+
+    include Constants
+
+    # @!macro [attach] generate
+    #   @method ineligible_$1s
+    #   list of individual who cannot be $1 
+    #   @return [Array,NilClass] Return nil if $1 already assigned
+    def self.generate_method_ineligibles_parent(parent)
+      define_method "ineligible_#{parent}s" do
+        unless self.send(parent) 
+          ineligibles = []
+          ineligibles |= descendants | [self] | gclass.send("#{OPPOSITESEX[PARENT2SEX[parent]]}s") if gclass.ineligibility_level >= PEDIGREE
+          if gclass.ineligibility_level >= PEDIGREE_AND_DATES  and life_range
+            ineligibles |= (gclass.all - ineligibles).find_all do |indiv|
+              if indiv.life_range
+                if birth
+                  !indiv.can_procreate_on?(birth)
+                else
+                  !indiv.can_procreate_during?(life_range)
+                end
+              else
+                false
+              end
+            end
+          end
+          ineligibles
+        end
+      end
+    end
+    generate_method_ineligibles_parent(:father)
+    generate_method_ineligibles_parent(:mother)
+
+
+    # @!macro [attach] generate
+    #   @method ineligible_$1_grand$2(grandparent)
+    #   list of individual who cannot be $1 grand$2 
+    #   @return [Array,NilClass] Return nil if $$1 grand$2 already assigned
+    def self.generate_method_ineligible_grandparent(lineage,grandparent)
+      relationship = "#{lineage}_grand#{grandparent}"
+      define_method "ineligible_#{relationship}s" do
+        unless send(relationship)
+          parent = send(LINEAGE2PARENT[lineage])          
+          ineligibles = []
+          ineligibles |= [parent].compact | descendants | siblings | send("#{lineage}_half_siblings") | [self] | gclass.send("#{OPPOSITESEX[PARENT2SEX[grandparent]]}s") if gclass.ineligibility_level >= PEDIGREE
+          if gclass.ineligibility_level >= PEDIGREE_AND_DATES              
+            ineligibles |= if parent
+              parent.send("ineligible_#{grandparent}s")
+            else
+              (gclass.all - ineligibles).find_all do |indiv|
+                if indiv.life_range
+                  !indiv.can_procreate_during?(send("#{LINEAGE2PARENT[lineage]}_birth_range"))
+                else
+                  false
+                end
+              end
+            end
+          end
+          ineligibles
+        end
+      end
+    end
+    
+    generate_method_ineligible_grandparent(:paternal,:father)
+    generate_method_ineligible_grandparent(:paternal,:mother)
+    generate_method_ineligible_grandparent(:maternal,:father)
+    generate_method_ineligible_grandparent(:maternal,:mother)
+
+    # list of individual who cannot be children: ancestors, children, full siblings, theirself and all individuals with father or mother according to self's sex
+    # @return [Array]
+    def ineligible_children
+      ineligibles = []
+      ineligibles |= ancestors | children | siblings | [self] | gclass.all_with(SEX2PARENT[ssex]) if gclass.ineligibility_level >= PEDIGREE
+      if gclass.ineligibility_level >= PEDIGREE_AND_DATES and fertility_range
+        ineligibles |= (gclass.all - ineligibles).find_all{ |indiv| !can_procreate_during?(indiv.birth_range)}
+      end
+      ineligibles
+    end
+
+    # list of individual who cannot be full siblings: ancestors, descendants, siblings, theirself and all individuals with different father or mother
+    # @return [Array]
+    def ineligible_siblings
+      ineligibles = []
+      if gclass.ineligibility_level >= PEDIGREE
+        ineligibles |= ancestors | descendants | siblings | [self]
+        ineligibles |= (father ? gclass.all_with(:father).where.not(father_id: father) : [])
+        ineligibles |= (mother ? gclass.all_with(:mother).where.not(mother_id: mother) : [])
+      end
+      if gclass.ineligibility_level >= PEDIGREE_AND_DATES 
+        # if a parent is present ineligible siblings are parent's ineligible children, otherwise try to estimate parent birth range.
+        # If it's possible ineligible siblings are all individuals whose life range overlaps parent birth range
+        [:father,:mother].each do |parent|
+          if p = send(parent)
+            ineligibles |= p.ineligible_children
+          elsif parent_fertility_range = send("#{parent}_fertility_range")
+            remainings = gclass.all - ineligibles
+            ineligibles |= remainings.find_all do |indiv|
+              if ibr = indiv.birth_range
+                !parent_fertility_range.overlaps? ibr
+              else
+                false
+              end
+            end
+          end
+        end
+      else
+      end
+      ineligibles
+    end
+
+  end
+end