aishafenton-hysteresis_filters 0.1.5

data/README.txt

@@ -0,0 +1,55 @@
+HysteresisFilters
+    by VisFleet Ltd
+    http://www.visfleet.com
+
+== DESCRIPTION:
+  
+A collection of simple decision filters which have the Hysteresis property. The filters provide
+simple boolean logic but with a little added fuzzyness. The fuzzyness is based on what states
+a filter has previously been through (i.e. Hysteresis). These filters are useful when you want
+to: smooth away brief changes in state (e.g. Tolerance filter), make your logic robust against 
+flipping between states (e.g. Schmitt filter), or only want to know when something has 
+changed (e.g. Transition filter).
+
+Each trigger can be used by itself or chained together to make surprisingly complex behaviours.
+
+== FEATURES/PROBLEMS:
+  
+* FIX (list of features or problems)
+
+== SYNOPSIS:
+
+  FIX (code sample of usage)
+
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+* FIX (sudo gem install, anything else)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIX
+
+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/Rakefile

@@ -0,0 +1,14 @@
+# -*- ruby -*-
+require 'rubygems'
+require './lib/hysteresis_filters.rb'
+
+desc "Test the hysteresis_filters plugin using rspec"
+Spec::Rake::SpecTask.new do |t|
+  t.warning = true
+  t.pattern = 'spec/**/*.rb'
+end
+
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end

data/lib/hysteresis_filters.rb

@@ -0,0 +1,115 @@
+require 'pp'
+require 'spec/rake/spectask'
+
+# 
+# This Module provides a set of triggers which exhibit the Hysteresis property. Each trigger can be
+# used by itself or chained togeather to make more complex behaviours. See rspecs for example uses
+# 
+module HysteresisFilters
+
+  class DecisionFilter
+    attr_accessor :boolean_state
+    
+    def initialize
+      self.reset
+    end
+
+    def reset
+      @boolean_state = false
+    end
+    
+  end
+
+  # 
+  # A Schmitt Trigger is a 'greather than' test against a two value threshold. When the trigger is in a false state the
+  # the input value must be greater than the 'upper threshold' beforing firing. However when in the true state
+  # the value must dip below the lower_threshold before changing to false. Schmitt Triggers are good for filtering
+  # out oscillations around a threshold. See http://en.wikipedia.org/wiki/Schmitt_trigger
+  # 
+  class SchmittTrigger < DecisionFilter
+
+    def greater_than?(value, lower_threshold, upper_threshold)
+      threshold = (@boolean_state) ? lower_threshold : upper_threshold
+      if value > threshold
+        return @boolean_state = true
+      else
+        return @boolean_state = false
+      end
+    end
+    
+  end
+
+  # 
+  # A Trigger than only fires when transitioning between states. In other words the 
+  # trigger will return true when the input state changes from false to true, or
+  # vice versa. Useful in cases where you only want to do something the first time
+  # an event happens (such as a Speed Alert email).
+  # 
+  class TransitionTrigger < DecisionFilter
+
+    def transitioning?(state)
+      if @boolean_state != state
+        @boolean_state = state
+        return true
+      else
+        return false
+      end
+    end
+
+  end
+  
+  # 
+  # A Trigger that only fires after the input state has been continously in that state
+  # for 'count' times. If the input state changes within the last 'count' inputs then
+  # the internal counter is reset. For example, only Fire a Speed Alert email after 
+  # been overspeeding continously for 30 seconds.
+  # 
+  # The Trigger also implements the method first_occurrence. This can be used to 
+  # retrospectively retrieve the first occurrence of the given 'obj' parameter 
+  # where the trigger first started to be true.
+  # 
+  class ToleranceTrigger < DecisionFilter
+
+    attr_reader :first_occurrence, :count, :value
+
+    def state?(state, count, obj)
+      # only set @value if it's nil (i.e. before trigger has switched)
+      @value ||= obj
+
+      # state unchanged
+      if @boolean_state == state
+        @value = obj
+        # reset
+        @count = 0
+        return @boolean_state
+      # state changed
+      else
+        @count += 1
+        # if first time
+        if @count == 1
+          @possible_first_occurrence = obj
+        end
+        # long enough? then switch over
+        if @count >= count
+          @value = obj
+          @boolean_state = state
+          @first_occurrence = @possible_first_occurrence
+          @count = 0
+          return @boolean_state
+        else
+          return @boolean_state
+        end
+      end
+      
+    end
+    
+    def reset
+      @first_occurrence = nil
+      @count = 0
+      super
+    end
+    
+  end
+
+
+end

data/spec/motion_start_spec.rb

@@ -0,0 +1,63 @@
+require 'pp'
+require 'lib/hysteresis_filters'
+
+describe 'Motion Start-Stop' do
+
+  before do
+    @tt = HysteresisFilters::TransitionTrigger.new
+    @tt.reset
+    @st = HysteresisFilters::ToleranceTrigger.new
+    @st.reset
+    @sct = HysteresisFilters::SchmittTrigger.new
+    @sct.reset
+  end
+
+  it "should filter motion start and stops" do
+    # GPS drift
+    8.times do
+      dist = rand(15)
+      in_motion?(dist).should be_false
+    end
+
+    # False starts
+    in_motion?(19).should be_false
+    in_motion?(19).should be_false
+    in_motion?(3).should be_false
+    in_motion?(19).should be_false
+    in_motion?(3).should be_false
+
+    # Going for real now
+    in_motion?(19, 'a').should be_false
+    in_motion?(19, 'b').should be_false
+    in_motion?(20, 'c').should be_false
+    in_motion?(21, 'd').should be_true
+    in_motion?(17, 'e').should be_true
+    @st.first_occurrence.should == 'a'
+
+    # False stops
+    in_motion?(19).should be_true
+    in_motion?(3).should be_true
+    in_motion?(4).should be_true
+    in_motion?(3).should be_true
+    in_motion?(10).should be_true
+
+    # Stopping for real now
+    in_motion?(11).should be_true
+    in_motion?(3).should be_true
+    in_motion?(3).should be_true
+    in_motion?(4).should be_true
+    in_motion?(3).should be_false
+    in_motion?(15).should be_false
+    in_motion?(0).should be_false
+
+  end
+
+end
+
+def in_motion?(dist, obj = nil)
+  @sct.greater_than?(dist, 5, 15)
+  return @sct.boolean_state = @st.state?(@sct.boolean_state, 4, obj)
+end
+
+
+

data/spec/schmitt_trigger_spec.rb

@@ -0,0 +1,26 @@
+require 'pp'
+require 'lib/hysteresis_filters'
+
+describe HysteresisFilters::SchmittTrigger do
+
+  before do
+    @st = HysteresisFilters::SchmittTrigger.new
+    @st.reset
+  end
+
+  it "should return when greater than thresholds" do
+    0.upto(15) do |i|
+      @st.greater_than?(i, 5, 15).should be_false
+    end
+    16.upto(30) do |i|
+      @st.greater_than?(i, 5, 15).should be_true
+    end
+    30.downto(6) do |i|
+      @st.greater_than?(i, 5, 15).should be_true
+    end
+    5.downto(-5) do |i|
+      @st.greater_than?(i, 5, 15).should be_false
+    end
+  end  
+
+end

data/spec/speed_alert_spec.rb

@@ -0,0 +1,81 @@
+require 'pp'
+require 'lib/hysteresis_filters'
+
+describe 'Speed Alert' do
+
+  before do
+    @tt = HysteresisFilters::TransitionTrigger.new
+    @tt.reset
+    @tolt = HysteresisFilters::ToleranceTrigger.new
+    @tolt.reset
+    @sct = HysteresisFilters::SchmittTrigger.new
+    @sct.reset
+  end
+
+  it "should only fire when 1) overspeeding is starting, 2) higher than upper threshold (schmitt), 3) has been speeding for 5 consecutive seconds" do
+
+    # Normal driving
+    100.times do
+      speed = 80 + rand(20)
+      overspeed_started?(speed).should be_false
+    end
+
+    # Not quite speeding
+    overspeed_started?(90).should be_false
+    overspeed_started?(100).should be_false
+    overspeed_started?(110).should be_false
+    overspeed_started?(95).should be_false
+    overspeed_started?(91).should be_false
+
+    # Speeding now
+    overspeed_started?(111, 'a').should be_false
+    overspeed_started?(110, 'b').should be_false
+    overspeed_started?(100, 'c').should be_false
+    overspeed_started?(97, 'd').should be_false
+    # Speed alert fires!!!
+    overspeed_started?(97, 'e').should be_true
+    @tolt.first_occurrence.should == 'a'
+
+    # Continuing to speed, but not re-triggering
+    overspeed_started?(97).should be_false
+    overspeed_started?(110).should be_false
+    overspeed_started?(100).should be_false
+    overspeed_started?(97).should be_false
+    overspeed_started?(100).should be_false
+
+    # Slowing down, but not long enough to reset trigger
+    overspeed_started?(93).should be_false
+    overspeed_started?(90).should be_false
+
+    # Speeding again
+    overspeed_started?(101).should be_false
+    overspeed_started?(110).should be_false
+
+    # Slowing down. Now trigger is reset
+    overspeed_started?(93).should be_false
+    overspeed_started?(90).should be_false
+    overspeed_started?(82).should be_false
+    overspeed_started?(80).should be_false
+    overspeed_started?(97).should be_false
+
+    # Speeding again. This time fire.
+    overspeed_started?(101).should be_false
+    overspeed_started?(110).should be_false
+    overspeed_started?(100).should be_false
+    overspeed_started?(97).should be_false
+    # Speed alert fires!!!
+    overspeed_started?(97).should be_true
+
+  end
+
+end
+
+def overspeed_started?(speed, obj = nil)
+  @result = @sct.greater_than?(speed, 95, 100)
+  @result = @tolt.state?(@sct.boolean_state, 5, obj)
+  @tt.transitioning?(@result) and @result
+end
+
+
+
+

data/spec/tolerance_trigger_spec.rb

@@ -0,0 +1,22 @@
+require 'pp'
+require 'lib/hysteresis_filters'
+
+describe HysteresisFilters::ToleranceTrigger do
+
+  before do
+    @st = HysteresisFilters::ToleranceTrigger.new
+    @st.reset
+  end
+
+  it "should return true only after condition has been true >10 times" do
+    0.upto(30) do |i|
+      if i < 24
+        @st.state?(i > 14, 10, i).should be_false
+      else
+        @st.state?(i > 14, 10, i).should be_true
+        @st.first_occurrence.should == 15
+      end
+    end
+  end
+
+end

data/spec/transition_trigger_spec.rb

@@ -0,0 +1,28 @@
+require 'pp'
+require 'lib/hysteresis_filters'
+
+describe HysteresisFilters::TransitionTrigger do
+
+  before do
+    @tt = HysteresisFilters::TransitionTrigger.new
+    @tt.reset
+  end
+
+  it "should return true transitioning between states" do
+    0.upto(30) do |i|
+      if i != 16
+        @tt.transitioning?(i > 15).should be_false
+      else
+        @tt.transitioning?(i > 15).should be_true
+      end
+    end
+    30.downto(-5) do |i|
+      if i != 15
+        @tt.transitioning?(i > 15).should be_false
+      else
+        @tt.transitioning?(i > 15).should be_true
+      end
+    end
+  end  
+
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: aishafenton-hysteresis_filters
+version: !ruby/object:Gem::Version 
+  version: 0.1.5
+platform: ruby
+authors: 
+- VisFleet
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-09 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: A collection of simple decision filters which have the Hysteresis property
+email: info@visfleet.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- lib/hysteresis_filters.rb
+- Rakefile
+- README.txt
+- spec/motion_start_spec.rb
+- spec/schmitt_trigger_spec.rb
+- spec/speed_alert_spec.rb
+- spec/tolerance_trigger_spec.rb
+- spec/transition_trigger_spec.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: "A collection of simple decision filters which have the Hysteresis property. The filters provide simple boolean logic but with a little added fuzzyness. The fuzzyness is based on what states a filter has previously been through (i.e. Hysteresis). These filters are useful when you want to: smooth away brief changes in state (e.g. Tolerance filter), make your logic robust against  flipping between states (e.g. Schmitt filter), or only want to know when something has  changed (e.g. Transition filter)."
+test_files: []
+