fselector 1.3.0 → 1.3.1

data/.yardopts

@@ -3,4 +3,4 @@
 --default-return ""
 --title "FSelector Documentation"
 --no-private
---files README.md,ChangeLog,LICENSE lib
+--files README.md,ChangeLog,LICENSE,HowToContribute lib

data/ChangeLog

@@ -1,11 +1,20 @@
-2012-05-24	version 1.3.0
+2012-05-31	v1.3.1
+------------------
+
+  * add HowToContribute section with test examples in README to show how to write one's own feature selection algorithms and/or contribute them to FSelector on GitHub.com
+  * all discretization algorithms now set feature type as CATEGORICAL, this will allow correct file format conversion after discretization
+  * add RandomSubset algorithm (primarily for test purpose)
+  
+2012-05-24	v1.3.0
+------------------
 
   * update clear\_vars() in Base by use of Ruby metaprogramming, this trick avoids repetitive overriding it in each derived subclass
   * re-organize LasVegasFilter, LasVegasIncremental and Random into algo_both/, since they are applicable to dataset with either discrete or continuous features, even with mixed type
   * update data\_from\_csv() so that it can read CSV file more flexibly. note by default, the last column is class label
   * add data\_from\_url() to read on-line dataset (in CSV, LibSVM or Weka ARFF file format) specified by a url
   
-2012-05-20	version 1.2.0
+2012-05-20	v1.2.0
+------------------
 
   * add KS-Test algorithm for continuous feature
   * add KS-CCBF algorithm for continuous feature
@@ -13,7 +22,8 @@
   * add KL-Divergence algorithm for discrete feature
   * include the Discretizer module for algorithms requiring data with discrete feature, which allows to deal with continuous feature after discretization. Those algorithms requiring data with continuous feature now do not include the Discretizer module
   
-2012-05-15	version 1.1.0
+2012-05-15	v1.1.0
+------------------
 
   * add replace\_by\_median\_value! for replacing missing value with feature median value
   * add replace\_by\_knn\_value! for replacing missing value with weighted feature value from k-nearest neighbors
@@ -22,43 +32,51 @@
   * rename Ensemble to EnsembleMultiple for ensemble feature selection by creating an ensemble of feature selectors using multiple feature selection algorithms of the same type
   * bug fix in FileIO module
   
-2012-05-08	version 1.0.1
+2012-05-08	v1.0.1
+------------------
 
   * modify Ensemble module so that ensemble\_by\_score() and ensemble\_by\_rank() now take Symbol, instead of Method, as argument. This allows easier and clearer function call
   * enable select_feature! interface in Ensemble module for the type of subset selection algorithms
   
-2012-05-04	version 1.0.0
+2012-05-04	v1.0.0
+------------------
 
   * add new algorithm INTERACT for discrete feature
   * add Consistency module to deal with data inconsistency calculation, which bases on a Hash table and is efficient in both storage and speed
   * update the Chi2 algorithm to try to reproduce the results of the original Chi2 algorithm
   * update documentation whenever necessary
   
-2012-04-25	version 0.9.0
+2012-04-25	v0.9.0
+------------------
 
   * add new discretization algorithm (Three-Interval Discretization, TID)
   * add new algorithm Las Vegas Filter (LVF) for discrete feature
   * add new algorithm Las Vegas Incremental (LVI) for discrete feature
   
-2012-04-23	version 0.8.1
+2012-04-23	v0.8.1
+------------------
 
   * correct a bug in the example in the README file because discretize\_by\_ChiMerge!() now takes confidence alpha value as argument instead of chi-square value
   
-2012-04-23	version 0.8.0
+2012-04-23	v0.8.0
+------------------
 
   * add new algorithm FTest (FT) for continuous feature
   * add .yardoc_opts to gem to use the MarkDown documentation syntax
   
-2012-04-20	Tiejun Cheng	<need47@gmail.com>
+2012-04-20	v0.7.0
+------------------
 
-  * update to version 0.7.0
+  * update to v0.7.0
 
-2012-04-19	Tiejun Cheng	<need47@gmail.com>
+2012-04-19	v0.6.0
+------------------
 
   * add new algorithm BetweenWithinClassesSumOfSquare (BSS_WSS) for continuous feature
   * add new algorithm WilcoxonRankSum (WRS) for continuous feature
 
-2012-04-18	Tiejun Cheng	<need47@gmail.com>
+2012-04-18	v0.5.0
+------------------
 
   * require the RinRuby gem (http://rinruby.ddahl.org) to access the 
     statistical routines in the R package (http://www.r-project.org/)

data/HowToContribute

@@ -0,0 +1,116 @@
+How to add your own feature selection algorithms
+------------------------------------------------
+
+**Baisc steps**
+    
+    1. Require the FSelector gem
+    
+    2. Derive a subclass from a base class (Base, BaseDiscrete, BaseContinuous and etc.)  
+    
+    3. Set your own feature selection algorithm with one of the following two types:  
+      :feature_weighting         # if it outputs weight for each feature
+      :feature_subset_selection  # if it outputs a subset of original feature set
+     
+    4. Depending on your algorithm type, override one of the following two interfaces:
+      calc_contribution()   # if it belongs to the type of feature weighting algorithms
+      get_feature_subset()  # if it belongs to the type of feature subset selection algorithms
+
+**Example**
+
+    require 'fselector'  # step 1
+    
+    module FSelector
+      # create a new algorithm belonging to the type of feature weighting
+      # to this end, simply override the calc_contribution() in Base class
+      class NewAlgo_Weight < Base  # step 2
+        # set the algorithm type
+        @algo_type = :feature_weighting  # step 3
+        
+        # add your own initialize() here if necessary
+        
+        private
+        
+        # the algorithm assigns feature weight randomly
+        def calc_contribution(f)  # step 4
+          s = rand
+          
+          # set the score (s) of feature (f) for class (:BEST is the best score among all classes)
+          set_feature_score(f, :BEST, s)
+        end
+      end # NewAlgo_Weight
+      
+      
+      # create a new algorithm belonging to the type of feature subset selection
+      # to this end, simly override the get_feature_subset() in Base class
+      class NewAlgo_Subset < Base  # step 2
+        # set the algorithm type
+        @algo_type = :feature_subset_selection  # step 3
+        
+        # add your own initialize() here if necessary
+        
+        private
+        
+        # the algorithm returns a random half-size subset of the orignal one
+        def get_feature_subset  # step 4
+          org_features = get_features
+          subset = org_features.sample(org_features.size/2)
+          
+          subset
+        end
+        
+      end # NewAlgo_Subset
+    end # module
+    
+ **Test your algorithms**
+       
+    require 'fselector'
+    
+    # example 1
+    
+    # use NewAlgo_Weighting
+    r1 = FSelector::NewAlgo_Weight.new
+    r1.data_from_csv('test/iris.csv')
+    r1.select_feature_by_rank!('<=1')
+    puts r1.get_features
+    
+    # example 2
+    
+    # use NewAlgo_Subset
+    r2 = FSelector::NewAlgo_Subset.new
+    r2.data_from_csv('test/iris.csv')
+    r2.select_feature!
+    puts r2.get_features
+
+How to become a contributor of FSelector on GitHub
+--------------------------------------------------
+
+**Set up your repository**
+    
+    1. Go to https://github.com/need47/fselector and click the "Fork" button
+
+    2. Clone your fork to your local machine:
+      git clone git@github.com:yourGitUserName/fselector.git
+        
+    3. Assign the original repository to a remote called "upstream":  
+      cd fselector  
+      git remote add upstream git://github.com/need47/fselector.git
+      
+    4. Get updates from the "upstream" and merge to your local repository:  
+      git fetch upstream  
+      git merge upstream/master
+    
+**Develop features**
+    
+    1. Create and checkout a feature branch to house your edits:
+      git checkout -b branchName
+      
+    2. Add your own feature selection algorithm:
+      git add yourAlgorithm.rb  
+      git commit -m "your commit message"
+    
+    3. Push your branch to GitHub:  
+      git push origin branchName
+    
+    4. Visit your forked project on GitHub and switch to your branhName branch  
+
+    5. Click the "Pull Request" button to request that your features to be merged to the "upstream" master

data/README.md

@@ -1,15 +1,15 @@
 FSelector: a Ruby gem for feature selection and ranking
 ===========================================================
 
-**Home** [https://rubygems.org/gems/fselector](https://rubygems.org/gems/fselector)  
+**Home**: [https://rubygems.org/gems/fselector](https://rubygems.org/gems/fselector)  
 **Source Code**: [https://github.com/need47/fselector](https://github.com/need47/fselector)  
 **Documentation** [http://rubydoc.info/gems/fselector/frames](http://rubydoc.info/gems/fselector/frames)  
 **Author**: Tiejun Cheng  
 **Email**: [need47@gmail.com](mailto:need47@gmail.com)  
 **Copyright**: 2012  
 **License**: MIT License  
-**Latest Version**: 1.3.0  
-**Release Date**: 2012-05-24
+**Latest Version**: 1.3.1  
+**Release Date**: 2012-05-31
 
 Synopsis
 --------
@@ -27,8 +27,9 @@ outputs a reduced data set with only selected subset of features, which
 can later be used as the input for various machine learning softwares 
 such as LibSVM and WEKA. FSelector, as a collection of filter methods, 
 does not implement any classifier like support vector machines or 
-random forest. See below for a list of FSelector's features and 
-{file:ChangeLog} for updates.
+random forest. Check below for a list of FSelector's features, 
+{file:ChangeLog} for updates, and {file:HowToContribute} if you want 
+to contribute.
 
 Feature List
 ------------
@@ -88,7 +89,8 @@ Feature List
     WilcoxonRankSum                  WRS         weighting  two-class      continuous
     LasVegasFilter                   LVF         subset     multi-class    discrete, continuous, mixed
     LasVegasIncremental              LVI         subset     multi-class    discrete, continuous, mixed
-    Random                           Random      weighting  multi-class    discrete, continuous, mixed
+    Random                           Rand        weighting  multi-class    discrete, continuous, mixed
+    RandomSubset                     RandS       subset     multi-class    discrete, continuous, mixed
     
   **note for feature selection interface:**   
   there are two types of filter methods, i.e., feature weighting algorithms and feature subset selection algorithms  
@@ -143,7 +145,7 @@ Usage
 -----
 
 **1. feature selection by a single algorithm**
-
+    
     require 'fselector'
 	
     # use InformationGain (IG) as a feature selection algorithm
@@ -186,7 +188,7 @@ Usage
 
 	
 **2. feature selection by an ensemble of multiple feature selectors**
-
+    
     require 'fselector'
 	
 	# example 1
@@ -253,7 +255,7 @@ Usage
     puts '  # features (after): ' + re.get_features.size.to_s
     
 **3. feature selection after discretization**
- 
+    
     require 'fselector'
     
     # the Information Gain (IG) algorithm requires data with discrete feature
@@ -277,13 +279,19 @@ Usage
 
 **4. see more examples test_*.rb under the test/ directory**
 
+How to contribute
+-----------------
+check {file:HowToContribute} to see how to write your own feature selection algorithms and/or make contribution to FSelector.
+
 Change Log
 ----------
+
 A {file:ChangeLog} is available from version 0.5.0 and upward to refelect 
-what's new and what's changed 
+what's new and what's changed.
 
 Copyright
 ---------
+
 FSelector © 2012 by [Tiejun Cheng](mailto:need47@gmail.com).
 FSelector is licensed under the MIT license. Please see the {file:LICENSE} for
 more information.

data/lib/fselector.rb

@@ -7,7 +7,7 @@ R.eval 'options(warn = -1)' # suppress R warnings
 #
 module FSelector
   # module version
-  VERSION = '1.3.0'
+  VERSION = '1.3.1'
 end
 
 # the root dir of FSelector

data/lib/fselector/algo_base/base.rb

@@ -506,7 +506,16 @@ module FSelector
     end
     
     
-    # get feature subset, for the type of subset selection algorithms
+    # calculate each feature's contribution
+    # override it in derived subclass for the type of feature weighting algorithms
+    def calc_contribution(f)
+      abort "[#{__FILE__}@#{__LINE__}]: \n"+
+            "  derived subclass must implement its own calc_contribution()"
+    end
+    
+    
+    # get feature subset
+    # override it in derived subclass for the type of feature subset selection algorithms
     def get_feature_subset
       abort "[#{__FILE__}@#{__LINE__}]: \n"+
             "  derived subclass must implement its own get_feature_subset()"

data/lib/fselector/algo_both/Random.rb

@@ -4,9 +4,9 @@
 module FSelector
 #
 # Random (Rand) for discrete, continuous or mixed feature, 
-# no pratical use but can be used as a baseline
+# no pratical use but can be used for test purpose
 #
-#  Rand = rand numbers within [0..1)
+#  Rand assignes random score of [0..1) to each feature
 #  
 # ref: [An extensive empirical study of feature selection metrics for text classification](http://dl.acm.org/citation.cfm?id=944974)
 #
@@ -40,4 +40,8 @@ module FSelector
   end # class
   
   
+  # shortcut so that you can use FSelector::Rand instead of FSelector::Random
+  Rand = Random
+  
+  
 end # module

data/lib/fselector/algo_both/RandomSubset.rb

@@ -0,0 +1,52 @@
+#
+# FSelector: a Ruby gem for feature selection and ranking
+#
+module FSelector
+#
+# RandomSubset (RandS) for discrete, continuous or mixed feature, 
+# no pratical use but can be used for test purpose
+#
+#  RandS generates a random subset of the original one
+#
+  class RandomSubset < Base
+    # this algo outputs a subset of feature
+    @algo_type = :feature_subset_selection
+    
+    #
+    # initialize from an existing data structure
+    #
+    # @param [Integer] nfeature number of feature required 
+    #   use random number if nil 
+    #
+    def initialize(nfeature=nil, data=nil)
+      super(data)
+      
+      @nfeature = nfeature
+    end
+    
+    private
+    
+    # RandomSubset algorithm
+    def get_feature_subset
+      subset = []
+      
+      if @nfeature and @nfeature > 0
+        subset = get_features.sample(@nfeature)
+      else
+        n = rand(get_features.size)
+        n += 1 if n == 0
+        subset = get_features.sample(n)
+      end
+      
+      subset
+    end # get_feature_subset
+    
+    
+  end # class
+  
+  
+  # shortcut so that you can use FSelector::RandS instead of FSelector::RandomSubset
+  RandS = RandomSubset
+  
+  
+end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fselector
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-24 00:00:00.000000000 Z
+date: 2012-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rinruby
-  requirement: &24934116 !ruby/object:Gem::Requirement
+  requirement: &25065000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 2.0.2
   type: :runtime
   prerelease: false
-  version_requirements: *24934116
+  version_requirements: *25065000
 description: FSelector is a Ruby gem that aims to integrate various feature selection/ranking
   algorithms and related functions into one single package. Welcome to contact me
   (need47@gmail.com) if you'd like to contribute your own algorithms or report a bug.
@@ -41,6 +41,7 @@ files:
 - README.md
 - ChangeLog
 - LICENSE
+- HowToContribute
 - .yardopts
 - lib/fselector/algo_base/base.rb
 - lib/fselector/algo_base/base_CFS.rb
@@ -51,6 +52,7 @@ files:
 - lib/fselector/algo_both/LasVegasFilter.rb
 - lib/fselector/algo_both/LasVegasIncremental.rb
 - lib/fselector/algo_both/Random.rb
+- lib/fselector/algo_both/RandomSubset.rb
 - lib/fselector/algo_continuous/BSS_WSS.rb
 - lib/fselector/algo_continuous/CFS_c.rb
 - lib/fselector/algo_continuous/F-Test.rb