nimbus 2.2.1 → 2.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77c90d8df14d57b793836e99eb985c9bac4e80c1
+  data.tar.gz: e7ca59175e219cafd229d178d544fe4a9cb94c58
+SHA512:
+  metadata.gz: 61a480e4d2e165f75059b950e2ce78e53686199e0459fade8944fea8f47d894d91aac2a849fa8cffc6cf39cb448a57b722776f5ee5c219548b9663189bc82e0e
+  data.tar.gz: e27b2d8ebc4f4cd686e2f9df72d77beeea368128c3cdac59284db21bfcf74ec5c1d31b08c265a38fc393c19c529080df5e3551c89adc0809837a3d3469c4141b

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Contributor Code of Conduct
+
+The Nimbus team is committed to fostering a welcoming community.
+
+we adopt an inclusive Code of Conduct adapted from the Contributor Covenant, version 1.4, you can read it here: [Contributor Covenant Code of Conduct](http://contributor-covenant.org/version/1/4/).
+
+

data/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# How to Contribute to this Project
+
+## Report an issue
+
+The prefered way to report any bug is [opening an issue in the project's Github repo](https://github.com/xuanxu/nimbus/issues/new).
+
+For more informal communication, you can contact [@xuanxu via twitter](https://twitter.com/xuanxu)
+
+## Resolve an issue
+
+Pull request are welcome. If you want to contribute code to solve an issue:
+
+* Add a comment to tell everyone you are working on the issue.
+* If an issue has someone assigned it means that person is already working on it.
+* Fork the project.
+* Create a topic branch based on master.
+* Commit there your code to solve the issue.
+* Make sure all test are passing (and add specs to test any new feature if needed).
+* Follow these [best practices](https://github.com/styleguide/ruby)
+* Open a *pull request* to the main repository describing what issue you are addressing.
+
+## Cleaning up
+
+In the rush of time sometimes things get messy, you can help us cleaning things up:
+
+* implementing pending specs
+* increasing code coverage
+* improving code quality
+* updating dependencies
+* making code consistent
+
+## Other ways of contributing without coding
+
+* If you think there's a feature missing, or find a bug, create an issue (make sure it has not already been reported).
+* You can also help promoting the project talking about it in your social networks.
+
+## How to report an issue
+
+* Try to use a descriptive and to-the-point title
+* Is a good idea to include some of there sections:
+  * Steps to reproduce the bug
+  * Expected behaviour/response
+  * Actual response
+* Sometimes it is also helpful if you mention your operating system or shell.
+
+Thanks! :heart: :heart: :heart:

data/MIT-LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Juanjo Bazán & Oscar González Recio
+Copyright (c) 2017 Juanjo Bazán & Oscar González Recio
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,9 +1,12 @@
-# Nimbus [![Build Status](https://secure.travis-ci.org/xuanxu/nimbus.png?branch=master)](http://travis-ci.org/xuanxu/nimbus)
+# Nimbus
 Random Forest algorithm for genomic selection.
 
+[![Build Status](https://secure.travis-ci.org/xuanxu/nimbus.png?branch=master)](http://travis-ci.org/xuanxu/nimbus)
+[![Gem Version](https://badge.fury.io/rb/nimbus.png)](http://badge.fury.io/rb/nimbus)
+
 ## Random Forest
 
-The [random forest algorithm](http://en.wikipedia.org/wiki/Random_forest) is an classifier consisting in many random decision trees. It is based on choosing random subsets of variables for each tree and using the most frequent, or the averaged tree output as the overall classification. In machine learning terms, it is an ensembler classifier, so it uses multiple models to obtain better predictive performance than could be obtained from any of the constituent models.
+The [random forest algorithm](http://en.wikipedia.org/wiki/Random_forest) is a classifier consisting in many random decision trees. It is based on choosing random subsets of variables for each tree and using the most frequent, or the averaged tree output as the overall classification. In machine learning terms, it is an ensembler classifier, so it uses multiple models to obtain better predictive performance than could be obtained from any of the constituent models.
 
 The forest outputs the class that is the mean or the mode (in regression problems) or the majority class (in classification problems) of the node's output by individual trees.
 
@@ -35,14 +38,14 @@ Nimbus can be used to:
 
 Nimbus can be used both with regression and classification problems.
 
-**Regression**: is the default mode. 
+**Regression**: is the default mode.
 
-* The split of nodes uses quadratic loss as loss function. 
+* The split of nodes uses quadratic loss as loss function.
 * Labeling of nodes is made averaging the fenotype values of the individuals in the node.
 
-**Classification**: user-activated declaring `classes` in the configuration file. 
+**Classification**: user-activated declaring `classes` in the configuration file.
 
-* The split of nodes uses the Gini index as loss function. 
+* The split of nodes uses the Gini index as loss function.
 * Labeling of nodes is made finding the majority fenotype class of the individuals in the node.
 
 ## Variable importances
@@ -51,29 +54,36 @@ By default Nimbus will estimate SNP importances everytime a training file is run
 
 You can disable this behaviour (and speed up the training process) by setting the parameter `var_importances: No` in the configuration file.
 
-## Install
+## Installation
+
+You need to have [Ruby](https://www.ruby-lang.org) (2.1 or higher) with Rubygems installed in your computer. Then install Nimbus with:
 
-You need to have Ruby (1.9.2 or higher) and Rubygems installed in your computer. Then install nimbus with:
+````shell
+> gem install nimbus
+````
 
-    $ gem install nimbus
+There are not extra dependencies needed.
 
 ## Getting Started
 
 Once you have nimbus installed in your system, you can run the gem using the `nimbus` executable:
 
-    $ nimbus
+````shell
+> nimbus
+````
 
-It will look for these files:
+It will look for these files in the directory where Nimbus is running:
 
-* `training.data`: If found it will be used to build a random forest
-* `testing.data` : If found it will be pushed down the forest to obtain predictions for every individual in the file
-* `random_forest.yml`: If found it will be the forest used for the testing.
+* `training.data`: If found it will be used to build a random forest.
+* `testing.data` : If found it will be pushed down the forest to obtain predictions for every individual in the file.
+* `random_forest.yml`: If found it will be the forest used for the testing instead of building one.
+* `config.yml`: A file detailing random forest parameters and datasets. If not found default values will be used.
 
-That way in order to train a forest a training file is needed. And to do the testing you need two files: the testing file and one of the other two: the training OR the random_forest file, because nimbus needs a forest from which obtain the predictions.
+That way in order to train a forest a training file is needed. And to do the testing you need two files: the testing file and one of the other two: the training OR the random_forest file, because Nimbus needs a forest from which obtain the predictions.
 
 ## Configuration (config.yml)
 
-The values for the input data files and the forest can be specified in the `config.yml` file that shouldbe locate in the directory where you are running `nimbus`.
+The names for the input data files and the forest parameters can be specified in the `config.yml` file that should be located in the directory where you are running `nimbus`.
 
 The `config.yml` has the following structure and parameters:
 
@@ -91,14 +101,14 @@ The `config.yml` has the following structure and parameters:
       SNP_total_count: 200
       node_min_size: 5
 
-Under the input chapter:
+### Under the input chapter:
 
  * `training`: specify the path to the training data file (optional, if specified `nimbus` will create a random forest).
- * `testing`: specify the path to the testing data file (optional, if specified `nimbus` will traverse this dat through a random forest).
+ * `testing`: specify the path to the testing data file (optional, if specified `nimbus` will traverse this data through a random forest).
  * `forest`: specify the path to a file containing a random forest structure (optional, if there is also testing file, this will be the forest used for the testing).
  * `classes`: **optional (needed only for classification problems)**. Specify the list of classes in the input files as a comma separated list between squared brackets, e.g.:`[A, B]`.
 
-Under the forest chapter:
+### Under the forest chapter:
 
  * `forest_size`: number of trees for the forest.
  * `SNP_sample_size_mtry`: size of the random sample of SNPs to be used in every tree node.
@@ -106,6 +116,19 @@ Under the forest chapter:
  * `node_min_size`: minimum amount of individuals in a tree node to make a split.
  * `var_importances`: **optional**. If set to `No` Nimbus will not calculate SNP importances.
 
+### Default values
+
+If there is no config.yml file present, Nimbus will use these default values:
+
+````yaml
+forest_size:          300
+tree_SNP_sample_size: 60
+tree_SNP_total_count: 200
+tree_node_min_size:   5
+training_file: 'training.data'
+testing_file:  'testing.data'
+forest_file:   'forest.yml
+````
 
 ## Input files
 
@@ -137,7 +160,83 @@ After training:
 
 After testing:
 
- * `testing_file_predictions.txt`: A file defining the structure of the computed Random Forest.
+ * `testing_file_predictions.txt`: A file detailing the predicted results for the testing dataset.
+
+## Example usage
+
+### Sample files
+
+Sample files are located in the `/spec/fixtures` directory, both for regression and classification problems. They can be used as a starting point to tweak your own configurations.
+
+Depending on the kind of problem you want to test different files are needed:
+
+### Regression
+
+**Test with a Random Forest created from a training data set**
+
+Download/copy the `config.yml`, `training.data` and `testing.data` files from the [regression folder](./tree/master/spec/fixtures/regression).
+
+Then run nimbus:
+
+````shell
+> nimbus
+````
+
+It should output a `random_forest.yml` file with the nodes and structure of the resulting random forest, the `generalization_errors` and `snp_importances` files, and the predictions for both training and testing datasets (`training_file_predictions.txt` and `testing_file_predictions.txt` files).
+
+**Test with a Random Forest previously created**
+
+Download/copy the `config.yml`, `testing.data` and `random_forest.yml` files from the [regression folder](./tree/master/spec/fixtures/regression).
+
+Edit the `config.yml` file to comment/remove the training entry.
+
+Then use nimbus to run the testing:
+
+````shell
+> nimbus
+````
+
+It should output a `testing_file_predictions.txt` file with the resulting predictions for the testing dataset using the given random forest.
+
+### Classification
+
+**Test with a Random Forest created from a training data set**
+
+Download/copy the `config.yml`, `training.data` and `testing.data` files from the [classification folder](./tree/master/spec/fixtures/classification).
+
+Then run nimbus:
+
+````shell
+> nimbus
+````
+
+It should output a `random_forest.yml` file with the nodes and structure of the resulting random forest, the `generalization_errors` file, and the predictions for both training and testing datasets (`training_file_predictions.txt` and `testing_file_predictions.txt` files).
+
+**Test with a Random Forest previously created**
+
+Download/copy the `config.yml`, `testing.data` and `random_forest.yml` files from the [classification folder](./tree/master/spec/fixtures/classification).
+
+Edit the `config.yml` file to comment/remove the training entry.
+
+Then use nimbus to run the testing:
+
+````shell
+> nimbus
+````
+
+It should output a `testing_file_predictions.txt` file with the resulting predictions for the testing dataset using the given random forest.
+
+
+## Test suite
+
+Nimbus includes a test suite located in the `spec` directory. You can run the specs if you clone the code to your local machine and run the default rake task:
+
+````shell
+> git clone git://github.com/xuanxu/nimbus.git
+> cd nimbus
+> bundle install
+> rake
+````
 
 ## Resources
 
@@ -149,8 +248,19 @@ After testing:
 * [Random Forest at Wikipedia](http://en.wikipedia.org/wiki/Random_forest)
 * [RF Leo Breiman page](http://www.stat.berkeley.edu/~breiman/RandomForests/)
 
+
+## Contributing
+
+Contributions are welcome. We encourage you to contribute to the Nimbus codebase.
+
+Please read the [CONTRIBUTING](CONTRIBUTING.md) file.
+
+
 ## Credits
 
 Nimbus was developed by [Juanjo Bazán](http://twitter.com/xuanxu) in collaboration with Oscar González-Recio.
 
-Copyright © 2011 - 2012 Juanjo Bazán, released under the MIT license
+
+## LICENSE
+
+Copyright © 2017 Juanjo Bazán, released under the [MIT license](MIT-LICENSE.txt)

data/bin/nimbus

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 #--
-# Copyright (c) 2011-2013 Juanjo Bazan
+# Copyright (c) 2011-2017 Juanjo Bazan
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -23,4 +23,4 @@
 #++
 
 require 'nimbus'
-Nimbus.application.run
+Nimbus.application.run

data/lib/nimbus.rb

@@ -20,6 +20,7 @@ module Nimbus
 
   STDERR = $stderr
   STDOUT = $stdout
+  STDOUT.sync = true
 
   # Nimbus module singleton methods.
   #
@@ -43,26 +44,21 @@ module Nimbus
     # Writes message to the standard output
     def message(msg)
       STDOUT.puts msg
-      STDOUT.flush
     end
 
     # Writes message to the error output
     def error_message(msg)
       STDERR.puts msg
-      STDERR.flush
     end
 
     # Writes to the standard output
     def write(str)
       STDOUT.write str
-      STDOUT.flush
     end
 
     # Clear current console line
     def clear_line!
-      self.write "\r"
-      self.write(" " * 50)
-      self.write "\r"
+      print "\r\e[2K"
     end
 
   end

data/lib/nimbus/classification_tree.rb

@@ -8,7 +8,7 @@ module Nimbus
   # * 1: Calculate loss function for the individuals in the node (first node contains all the individuals).
   # * 2: Take a random sample of the SNPs (size m << total count of SNPs)
   # * 3: Compute the loss function (default: gini index) for the split of the sample based on value of every SNP.
-  # * 4: If the SNP with minimum loss function also minimizes the general loss of the node, split the individuals sample in three nodes, based on value for that SNP [0, 1, or 2]
+  # * 4: If the SNP with minimum loss function also minimizes the general loss of the node, split the individuals sample in two nodes, based on average value for that SNP [0,1][2], or [0][1,2]
   # * 5: Repeat from 1 for every node until:
   #   - a) The individuals count in that node is < minimum size OR
   #   - b) None of the SNP splits has a loss function smaller than the node loss function
@@ -34,8 +34,8 @@ module Nimbus
 
     # Creates a node by taking a random sample of the SNPs and computing the loss function for every split by SNP of that sample.
     #
-    # * If SNP_min is the SNP with smaller loss function and it is < the loss function of the node, it splits the individuals sample in three:
-    # (those with value 0 for the SNP_min, those with value 1 for the SNP_min, and those with value 2 for the SNP_min) then it builds these 3 new nodes.
+    # * If SNP_min is the SNP with smaller loss function and it is < the loss function of the node, it splits the individuals sample in two:
+    # (the average of the 0,1,2 values for the SNP_min in the individuals is computed, and they are splitted in [<=avg], [>avg]) then it builds these 2 new nodes.
     # * Otherwise every individual in the node gets labeled with the average of the fenotype values of all of them.
     def build_node(individuals_ids, y_hat)
       # General loss function value for the node
@@ -45,24 +45,21 @@ module Nimbus
 
       # Finding the SNP that minimizes loss function
       snps = snps_random_sample
-      min_loss, min_SNP, split, ginis = node_loss_function, nil, nil, nil
+      min_loss, min_SNP, split, split_type, ginis = node_loss_function, nil, nil, nil, nil
 
       snps.each do |snp|
-        individuals_split_by_snp_value = split_by_snp_value individuals_ids, snp
+        individuals_split_by_snp_value, node_split_type = split_by_snp_avegare_value individuals_ids, snp
         y_hat_0 = Nimbus::LossFunctions.majority_class(individuals_split_by_snp_value[0], @id_to_fenotype, @classes)
         y_hat_1 = Nimbus::LossFunctions.majority_class(individuals_split_by_snp_value[1], @id_to_fenotype, @classes)
-        y_hat_2 = Nimbus::LossFunctions.majority_class(individuals_split_by_snp_value[2], @id_to_fenotype, @classes)
-        
+
         gini_0 = Nimbus::LossFunctions.gini_index individuals_split_by_snp_value[0], @id_to_fenotype, @classes
         gini_1 = Nimbus::LossFunctions.gini_index individuals_split_by_snp_value[1], @id_to_fenotype, @classes
-        gini_2 = Nimbus::LossFunctions.gini_index individuals_split_by_snp_value[2], @id_to_fenotype, @classes
         loss_snp = (individuals_split_by_snp_value[0].size * gini_0 +
-                    individuals_split_by_snp_value[1].size * gini_1 + 
-                    individuals_split_by_snp_value[2].size * gini_2) / individuals_count
+                    individuals_split_by_snp_value[1].size * gini_1) / individuals_count
 
-        min_loss, min_SNP, split, ginis = loss_snp, snp, individuals_split_by_snp_value, [y_hat_0, y_hat_1, y_hat_2] if loss_snp < min_loss
+        min_loss, min_SNP, split, split_type, ginis = loss_snp, snp, individuals_split_by_snp_value, node_split_type, [y_hat_0, y_hat_1] if loss_snp < min_loss
       end
-      return build_branch(min_SNP, split, ginis, y_hat) if min_loss < node_loss_function
+      return build_branch(min_SNP, split, split_type, ginis, y_hat) if min_loss < node_loss_function
       return label_node(y_hat, individuals_ids)
     end
 

data/lib/nimbus/configuration.rb

@@ -36,26 +36,26 @@ module Nimbus
     )
 
     DEFAULTS = {
-      :forest_size          => 500,
-      :tree_SNP_sample_size => 60,
-      :tree_SNP_total_count => 200,
-      :tree_node_min_size   => 5,
+      forest_size:          300,
+      tree_SNP_sample_size: 60,
+      tree_SNP_total_count: 200,
+      tree_node_min_size:   5,
 
-      :loss_function_discrete   => 'majority_class',
-      :loss_function_continuous => 'average',
+      loss_function_discrete:   'majority_class',
+      loss_function_continuous: 'average',
 
-      :training_file => 'training.data',
-      :testing_file  => 'testing.data',
-      :forest_file   => 'forest.yml',
-      :config_file   => 'config.yml',
+      training_file: 'training.data',
+      testing_file:  'testing.data',
+      forest_file:   'forest.yml',
+      config_file:   'config.yml',
 
-      :output_forest_file   => 'random_forest.yml',
-      :output_training_file => 'training_file_predictions.txt',
-      :output_testing_file  => 'testing_file_predictions.txt',
-      :output_tree_errors_file => 'generalization_errors.txt',
-      :output_snp_importances_file => 'snp_importances.txt',
+      output_forest_file:   'random_forest.yml',
+      output_training_file: 'training_file_predictions.txt',
+      output_testing_file:  'testing_file_predictions.txt',
+      output_tree_errors_file: 'generalization_errors.txt',
+      output_snp_importances_file: 'snp_importances.txt',
 
-      :silent => false
+      silent: false
     }
 
     # Initialize a Nimbus::Configuration object.
@@ -85,10 +85,10 @@ module Nimbus
     # Accessor method for the tree-related subset of options.
     def tree
       {
-        :snp_sample_size => @tree_SNP_sample_size,
-        :snp_total_count => @tree_SNP_total_count,
-        :tree_node_min_size => @tree_node_min_size,
-        :classes => @classes
+        snp_sample_size: @tree_SNP_sample_size,
+        snp_total_count: @tree_SNP_total_count,
+        tree_node_min_size: @tree_node_min_size,
+        classes: @classes
       }
     end
 
@@ -126,8 +126,8 @@ module Nimbus
         @forest_file   = File.expand_path(DEFAULTS[:forest_file  ], Dir.pwd) if File.exists? File.expand_path(DEFAULTS[:forest_file  ], Dir.pwd)
       end
 
-      @do_training = true if @training_file
-      @do_testing  = true if @testing_file
+      @do_training = true unless @training_file.nil?
+      @do_testing  = true unless @testing_file.nil?
       @classes = @classes.map{|c| c.to_s.strip} if @classes
 
       if @do_testing && !@do_training && !@forest_file