interval_notation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a937def556100b39f5ceda9350746e0bd4d8ecb7
+  data.tar.gz: 41f639a8c41a16cbecb65dce7bfa8862429196da
+SHA512:
+  metadata.gz: ef63264b1222cc9014f420b3dcf35528dec369db7d2515ac6ff7fa66e96714ec1b091e51a8d7c77c5dd9052b2856d6332adcf92c9a117f71bd67bb1dcbb7ac27
+  data.tar.gz: f453f8d84ed5900c06713ede45ef045e0fe562ab8e469e4522db0be2daedb4aad1c593dd1f3970d5cdc40793942ea40ef412a809bd325a3f1e27e95894f2b566

data/.gitignore

@@ -0,0 +1,19 @@
+for_article/
+source_data/
+source_data_2/
+genome/
+top_motif/
+*.bed
+robust_set.freeze1
+robust_set.freeze1.reduced.pc-3
+*.txt
+*.out
+*.log
+*.sav
+*.fasta
+*.rar
+*.tar
+*.gz
+*.csv
+*.xls
+*.xlsx

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in interval_notation.gemspec
+gemspec

data/README.md

@@ -0,0 +1,163 @@
+# IntervalNotation
+
+`interval_notation` allows one to work with 1D-intervals.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'interval_notation'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install interval_notation
+
+## Usage
+
+`IntervalNotation` provides methods to create intervals with open or closed boundaries or singular points, unite and intersect them, check inclusion into an interval and so on.
+
+In order to construct intervals and interval sets, please use factory methods, not class constructors:
+```ruby
+include IntervalNotation::Syntax::Short
+# Predefined interval sets
+R # => (-∞,+∞)
+Empty # => ∅
+# Singular point
+pi = pt(Math::PI) # => {3.141592653589793}
+# Finite intervals
+interval_1 = oo(1,3) # => (1,3)
+interval_2 = oc(3,5) # => (3,5]
+interval_3 = co(10,15) # => [10,15)
+interval_4 = cc(4,11) # => [4,11]
+# Aliases for infinite intervals
+interval_5 = lt(7) # => (-∞,7)
+interval_6 = le(-3) # => (-∞,-3]
+interval_7 = gt(-3) # => (-3,+∞)
+interval_8 = ge(5.5) # => [5.5,+∞)
+# one can also create infinite intervals using basic methods
+interval_5_2 = oo(-Float::INFINITY, 7) # => (-∞,7)
+interval_6_2 = oc(-Float::INFINITY, -3) # => (-∞,-3]
+interval_7_2 = oo(-3, Float::INFINITY) # => (-3,+∞)
+interval_8_2 = co(5.5, Float::INFINITY) # => [5.5,+∞)
+# Create interval set from string (see IntervalSet.from_string for details)
+interval_9 = int('{0}U[1,5)U(5,infty)') # => {0}U[1,5)U(5,+∞)
+```
+
+If you prefer more descriptive method names, use `IntervalNotation::Syntax::Long`. In such case you'll have `open_open`, `open_closed`, `closed_open`, `closed_closed`, `less_than`, `less_than_or_equal_to`, `greater_than`, `greater_than_or_equal_to` and `point` methods. `interval` is a long-form analog for `int` - to create interval set from string
+
+Consider that no one class is supposed to be used directly! For further details see section **Internal structure**.
+
+### Interval operations
+Intervals can be combined in many different ways:
+```ruby
+include IntervalNotation::Syntax::Long
+a = open_closed(0,15) # => (0,15]
+b = closed_open(10,25) # => [10,25)
+c = point(-5) # => {-5}
+bc = b | c # => {-5}∪[10,25)
+
+# Union of a pair of intervals:
+a | b # => (0,25)
+a.union(b) # ditto
+
+# Intersection:
+a & b # => [10,15]
+a.intersection(b)
+
+# Difference:
+a - b # => (0,10)
+a.subtract(b)
+
+# Symmetric difference:
+a ^ b # => (0,10)∪(15,25)
+a.symmetric_difference(b)
+
+# Interval complement
+~a # => (-∞,0]∪(15,+∞)
+a.complement
+
+# Interval closure
+bc.closure # => {-5}∪[10,25]
+
+# Covering interval
+bc.covering_interval # => [-5,25)
+```
+
+If you want to combine more than two intervals, you can perform several consequent operations:
+```ruby
+a | b | c # => {-5}∪(0,25)
+a & b & c # => ∅
+# or may be
+[a,b,c].inject(&:|) # => {-5}∪(0,25)
+[a,b,c].inject(&:&) # => ∅
+```
+But there is a much better and faster way to unite or intersect multiple intervals:
+```ruby
+IntervalNotation::Operations.union([a,b,c]) # => {-5}∪(0,25]
+IntervalNotation::Operations.intersection([a,b,c]) # => ∅
+```
+If you unite thousands or millions of intervals, you definitely should choose the last method! Do not try to inject intervals one by one for the sake of perfomance. Running time can differ dramatically (seconds vs hours for union of hundreds of thousands intervals).
+
+### Interval queries
+One can test whether two intervals intersect, cover one another and so on:
+```ruby
+Empty.empty? # => true
+closed_closed(0,5).empty? # => false
+
+Empty.contiguous? # => true
+closed_closed(0,5).contiguous? # => true
+point(8).contiguous? # => true
+(open_open(0,5) | point(8)).contiguous? # => false
+
+closed_closed(0,5).include_position?(3) # => true
+open_open(0,5).include_position?(5) # => false
+open_open(0,5).include_position?(8) # => false (actually nil which is falsy)
+(open_open(0,5)|open_open(7,9)).include_position?(8)# => true
+
+closed_closed(0,5).intersect?(closed_closed(3,10)) # => true
+closed_closed(0,5).intersect?(closed_closed(5,10)) # => true
+closed_closed(0,5).intersect?(open_closed(5,10)) # => false
+closed_closed(0,5).intersect?(closed_closed(7,10)) # => false
+
+closed_closed(0,5).contain?(closed_closed(2,3)) # => true
+closed_closed(2,3).contained_by?(closed_closed(0,5)) # => true
+```
+
+Full list of querying methods:
+```ruby
+interval_set.total_length
+interval_set.num_connected_components
+interval_set.empty?
+interval_set.contiguous?
+interval_set.include_position?(position)
+interval_set.intersect?(interval_set)
+interval_set.contain?(interval_set)
+interval_set.contained_by?(interval_set)
+```
+
+## Internal structure
+
+`IntervalNotation::IntervalSet` is designed in order to keep ordered list of non-overlapping intervals and represent 1-D point set. Each interval in the `IntervalSet` is an instance of one of following classes: `Point`, `OpenOpenInterval`, `OpenClosedInterval`, `ClosedOpenInterval` or `ClosedOpenInterval` representing contiguous 1-D subsets. One can find them in `IntervalNotation::BasicIntervals` module. None of these classes is intended to be directly instantiated, usually intervals are constructed using factory methods and combining operations.
+
+All factory methods listed above create `IntervalSet`s, wrapping an instance of corresponding interval or point class. All interval set operations create new `IntervalSet`s, even if they contain the only basic interval.
+
+`IntervalSet`s are value objects. Once instantiated they cannot be changed, all operations just create new objects. It also means, you can fearlessly use them as key values in hashes.
+
+Combining of intervals is made by sweep line method, so is linear by number of intervals. Many querying operations (such as `#intersect`) rely on combining intervals thus also have linear complexity. Some of these perfomance drawbacks will be fixed in future.
+Query `#include_position?` is made by binary search (so has logarithmic complexity).
+
+`IntervalSet` has two constructors: `.new` and `.new_unsafe`. Use them with caution. Default constructor accepts data in a specially prepared format, while unsafe constructor makes no validation at all (and can create inconsistent obect). But `.new_unsafe` still can be useful when you are absolutely sure, provided data is ok, and a few milliseconds for unnecessary validation make sense.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/interval_notation/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/TODO.md

@@ -0,0 +1,3 @@
+* Write benchmarks
+* Optimize `#closure` and `#intersect?`
+* Visualization in console and in IRuby (how to scale into 80-symbol or 1200px screen); SVG; TeX formatters

data/interval_notation.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'interval_notation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "interval_notation"
+  spec.version       = IntervalNotation::VERSION
+  spec.authors       = ["Ilya Vorontsov"]
+  spec.email         = ["prijutme4ty@gmail.com"]
+  spec.summary       = %q{interval_notation allows one to work with 1D-intervals.}
+  spec.description   = %q{interval_notation provides methods to create intervals with open or closed boundaries or singular points, unite and intersect them, check inclusion into an interval and so on.}
+  spec.homepage      = "https://github.com/prijutme4ty/interval_notation"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/interval_notation/basic_intervals.rb

@@ -0,0 +1,263 @@
+require_relative 'error'
+require_relative 'interval_set'
+
+module IntervalNotation
+  module BasicIntervals # :nodoc: all
+    # Auxiliary class to represent information about interval boundaries
+    BoundaryPoint = Struct.new(:value, :included, :opening, :interval_index, :interval_boundary) do
+      def closing
+        !opening
+      end
+    end
+
+    module ActslikeInterval
+      def self.included(base)
+        base.class_eval do
+          attr_reader :from, :to
+        end
+      end
+
+      def closure
+        if from_finite?
+          if to_finite?
+            ClosedClosedInterval.new(from, to)
+          else
+            ClosedOpenInterval.new(from, to) # to == +∞
+          end
+        else
+          if to_finite?
+            OpenClosedInterval.new(from, to)  # from == -∞
+          else
+            OpenOpenInterval.new(from, to)  # from == -∞, to == +∞
+          end
+        end
+      end
+
+      def to_interval_set; IntervalSet.new([self]); end
+
+      def from_finite?; from.to_f.finite?; end
+      def to_finite?; to.to_f.finite?; end
+      def finite?; from_finite? && to_finite?; end
+
+      def from_to_s; from_finite? ? from : MINUS_INFINITY_SYMBOL; end
+      def to_to_s; to_finite? ? to : PLUS_INFINITY_SYMBOL; end
+
+      def length; to - from; end
+      def inspect; to_s; end
+      def singular_point?; false; end
+      def hash; [@from, @to, include_from?, include_to?].hash; end;
+      def eql?(other); other.class.equal?(self.class) && from.eql?(other.from) && to.eql?(other.to); end
+    end
+
+    class OpenOpenInterval
+      include ActslikeInterval
+      def initialize(from, to)
+        raise Error, "Interval (#{from};#{to}) can't be created"  unless from < to
+        @from = from
+        @to = to
+      end
+      def to_s; "(#{from_to_s};#{to_to_s})"; end
+      def include_from?; false; end
+      def include_to?; false; end
+      def include_position?(value); from < value && value < to; end
+      def ==(other); other.is_a?(OpenOpenInterval) && from == other.from && to == other.to; end
+      def interval_boundaries(interval_index)
+        [ BoundaryPoint.new(from, false, true, interval_index, true),
+          BoundaryPoint.new(to, false, false, interval_index, true) ]
+      end
+    end
+
+    class OpenClosedInterval
+      include ActslikeInterval
+      def initialize(from, to)
+        raise Error, "Interval (#{from};#{to}] can't be created"  unless from < to
+        raise Error, "Infinite boundary should be open" unless to.to_f.finite?
+        @from = from
+        @to = to
+      end
+      def to_s; "(#{from_to_s};#{to_to_s}]"; end
+      def include_from?; false; end
+      def include_to?; true; end
+
+      def to_finite?; true; end
+      def to_to_s; to; end
+
+      def closure
+        if from_finite?
+          ClosedClosedInterval.new(from, to)
+        else
+          OpenClosedInterval.new(from, to)  # from == -∞
+        end
+      end
+
+      def include_position?(value); from < value && value <= to; end
+      def ==(other); other.is_a?(OpenClosedInterval) && from == other.from && to == other.to; end
+      def interval_boundaries(interval_index)
+        [ BoundaryPoint.new(from, false, true, interval_index, true),
+          BoundaryPoint.new(to, true, false, interval_index, true) ]
+      end
+    end
+
+    class ClosedOpenInterval
+      include ActslikeInterval
+      def initialize(from, to)
+        raise Error, "Interval [#{from};#{to}) can't be created"  unless from < to
+        raise Error, "Infinite boundary should be open" unless from.to_f.finite?
+        @from = from
+        @to = to
+      end
+      def to_s; "[#{from_to_s};#{to_to_s})"; end
+      def include_from?; true; end
+      def include_to?; false; end
+
+      def from_finite?; true; end
+      def from_to_s; from; end
+
+      def closure
+        if to_finite?
+          ClosedClosedInterval.new(from, to)
+        else
+          ClosedOpenInterval.new(from, to) # to == +∞
+        end
+      end
+
+      def include_position?(value); from <= value && value < to; end
+      def ==(other); other.is_a?(ClosedOpenInterval) && from == other.from && to == other.to; end
+      def interval_boundaries(interval_index)
+        [ BoundaryPoint.new(from, true, true, interval_index, true),
+          BoundaryPoint.new(to, false, false, interval_index, true) ]
+      end
+    end
+
+    class ClosedClosedInterval
+      include ActslikeInterval
+      def initialize(from, to)
+        raise Error, "Interval [#{from};#{to}] can't be created"  unless from < to
+        raise Error, "Infinite boundary should be open" unless from.to_f.finite? && to.to_f.finite?
+        @from = from
+        @to = to
+      end
+      def to_s; "[#{from_to_s};#{to_to_s}]"; end
+      def include_from?; true; end
+      def include_to?; true; end
+
+      def from_finite?; true; end
+      def to_finite?; true; end
+      def finite?; true; end
+      def from_to_s; from; end
+      def to_to_s; to; end
+
+      def closure; self; end
+
+      def include_position?(value); from <= value && value <= to; end
+      def ==(other); other.is_a?(ClosedClosedInterval) && from == other.from && to == other.to; end
+      def interval_boundaries(interval_index)
+        [ BoundaryPoint.new(from, true, true, interval_index, true),
+          BoundaryPoint.new(to, true, false, interval_index, true) ]
+      end
+    end
+
+    class Point
+      attr_reader :value
+      protected :value
+      def initialize(value)
+        raise Error, "Point can't represent an infinity"  unless value.to_f.finite?
+        @value = value
+      end
+      def from; value; end
+      def to; value; end
+
+      def to_interval_set; IntervalSet.new([self]); end
+
+      def from_finite?; true; end
+      def to_finite?; true; end
+      def finite?; true; end
+
+      def length; 0; end
+      def to_s; "{#{@value}}"; end
+      def inspect; to_s; end
+
+      def include_from?; true; end
+      def include_to?; true; end
+
+      def closure; self; end
+
+      def singular_point?; true; end
+      def include_position?(val); value == val; end
+      def hash; @value.hash; end;
+      def eql?(other); other.class.equal?(self.class) && value == other.value; end
+      def ==(other); other.is_a?(Point) && value == other.value; end
+      def interval_boundaries(interval_index)
+        BoundaryPoint.new(from, true, nil, interval_index, false)
+      end
+    end
+
+    def self.interval_by_boundary_inclusion(include_from, from, include_to, to)
+      if include_from
+        if include_to
+          if from != to
+            ClosedClosedInterval.new(from, to)
+          else
+            Point.new(from)
+          end
+        else
+          ClosedOpenInterval.new(from, to)
+        end
+      else
+        if include_to
+          OpenClosedInterval.new(from, to)
+        else
+          OpenOpenInterval.new(from, to)
+        end
+      end
+    end
+
+    PLUS_INFINITY_VARIANTS = ['∞', 'inf', 'infinity', 'infty', '\infty', '+∞', '+inf', '+infinity', '+infty', '+\infty']
+    MINUS_INFINITY_VARIANTS = ['-∞', '-inf', '-infinity', '-infty', '-\infty']
+    EMPTY_VARIANTS = ['∅','empty','']
+    OPENING_VARIANTS = ['(','[']
+    CLOSING_VARIANTS = [')',']']
+
+    # returns an Interval (wrapped or unwrapped) or an array of Points or empty list (for Empty interval)
+    def self.from_string(interval_str)
+      interval_str = interval_str.gsub(/\s/,'')
+      return Empty  if EMPTY_VARIANTS.include?(interval_str.downcase)
+      return R  if interval_str == 'R'
+      if interval_str[0] == '{' && interval_str[-1] == '}'
+        interval_str[1..-2].split(/[,;]/).map{|el| Point.new(Float(el)) }
+      elsif OPENING_VARIANTS.include?(interval_str[0]) && CLOSING_VARIANTS.include?(interval_str[-1])
+        boundary_values = interval_str[1..-2].split(/[,;]/).map(&:strip)
+        raise Error, 'Unknown format'  unless boundary_values.size == 2
+        from = (MINUS_INFINITY_VARIANTS.include?(boundary_values[0].downcase)) ? -Float::INFINITY : Float(boundary_values[0])
+        to   = (PLUS_INFINITY_VARIANTS.include?(boundary_values[1].downcase)) ? Float::INFINITY : Float(boundary_values[1])
+
+        if interval_str[0] == '('
+          if interval_str[-1] == ')'
+            OpenOpenInterval.new(from, to)
+          elsif interval_str[-1] == ']'
+            OpenClosedInterval.new(from, to)
+          else
+            raise Error, 'Unknown format'
+          end
+        elsif interval_str[0] == '['
+          if interval_str[-1] == ')'
+            ClosedOpenInterval.new(from, to)
+          elsif interval_str[-1] == ']'
+            ClosedClosedInterval.new(from, to)
+          else
+            raise Error, 'Unknown format'
+          end
+        else
+          raise Error, 'Unknown format'
+        end
+      else
+        begin
+          Point.new(Float(interval_str))
+        rescue
+          raise Error, 'Unknown format'
+        end
+      end
+    end
+
+  end
+end

data/lib/interval_notation/combiners.rb

@@ -0,0 +1,120 @@
+require 'set'
+
+module IntervalNotation
+  # Combiner is an internal helper class for combining interval sets using sweep line.
+  # It starts moving from -∞ to +∞ and keep which intervals are crossed by sweep line.
+  # Class helps to effectively recalculate number of crossed intervals without rechecking
+  # all intervals each time, and dramatically reduces speed of operations on large number of intervals
+  class Combiner
+    attr_reader :num_interval_sets
+    attr_reader :previous_state
+
+    def initialize(num_interval_sets)
+      @num_interval_sets = num_interval_sets
+      @inside = Array.new(num_interval_sets, false)
+      @num_intervals_inside = 0 # number of intervals, we are inside (for efficiency)
+    end
+
+    # When sweep line pass several interval boundaries, +#pass+ should get all those points at once
+    # and update status of crossing sweep line.
+    # It also stores previous state, because it's actively used downstream.
+    def pass(points_on_place)
+      @previous_state = state
+      pass_recalculation(points_on_place)
+    end
+
+    # See +#pass+ for details
+    def pass_recalculation(points_on_place) # :nodoc:
+      num_spanning_intervals = @num_intervals_inside
+      num_covering_boundaries = 0
+
+      points_on_place.each do |point|
+        num_covering_boundaries += 1  if point.included
+
+        if point.interval_boundary
+          num_spanning_intervals -= 1  if point.closing
+          @num_intervals_inside += (@inside[point.interval_index] ? -1 : 1)
+          @inside[point.interval_index] ^= true
+        end
+      end
+      @num_interval_sets_covering_last_point = num_spanning_intervals + num_covering_boundaries
+    end
+    private :pass_recalculation
+  end
+
+  class UnionCombiner < Combiner
+    # checks whether current section should be included
+    def state
+      @num_intervals_inside > 0
+    end
+
+    # checks whether last passed point should be included
+    def include_last_point
+      @num_interval_sets_covering_last_point > 0
+    end
+  end
+
+  class IntersectCombiner < Combiner
+    # checks whether current section should be included
+    def state
+      @num_intervals_inside == num_interval_sets
+    end
+
+    # checks whether last passed point should be included
+    def include_last_point
+      @num_interval_sets_covering_last_point == num_interval_sets
+    end
+  end
+
+  class SubtractCombiner < Combiner
+    # checks whether last passed point should be included
+    attr_reader :include_last_point
+
+    def initialize
+      @include_last_point = nil
+      @inside = [false, false]
+    end
+
+    # checks whether current section should be included
+    def state
+      @inside[0] && ! @inside[1]
+    end
+
+    # See +#pass+ for details
+    def pass_recalculation(points_on_place) # :nodoc:
+      included = @inside.dup
+      points_on_place.each do |point|
+        @inside[point.interval_index] ^= point.interval_boundary # doesn't change on singular points
+        included[point.interval_index] = point.included
+      end
+      @include_last_point = included[0] && !included[1]
+    end
+    private :pass_recalculation
+  end
+
+  class SymmetricDifferenceCombiner < Combiner
+    # checks whether last passed point should be included
+    attr_reader :include_last_point
+
+    def initialize
+      @include_last_point = nil
+      @inside = [false, false]
+    end
+
+    # checks whether current section should be included
+    def state
+      @inside[0] ^ @inside[1]
+    end
+
+    # See +#pass+ for details
+    def pass_recalculation(points_on_place) # :nodoc:
+      included = @inside.dup
+      points_on_place.each do |point|
+        @inside[point.interval_index] ^= point.interval_boundary # doesn't change on singular points
+        included[point.interval_index] = point.included
+      end
+      @include_last_point = included[0] ^ included[1]
+    end
+    private :pass_recalculation
+  end
+end

data/lib/interval_notation/error.rb

@@ -0,0 +1,3 @@
+module IntervalNotation
+  class Error < StandardError; end
+end