Cleanup for public release

Author: ruffrey

README.md

@@ -1,11 +1,76 @@
-# pine
+# Pine - a tool for Random Decision Forests
 
-ensembles of random decision trees
+Ensembles of random decision trees. Make predictions using the machine learning technique.
 
-![random decision tree ensembles training](decision-ensembles.png)
+See [this Kaggle discussion](https://www.kaggle.com/general/3920) of the term *random forest*.
+
+## usage
+
+[Go](https://golang.org/dl) is required to build this app. 
+
+```bash
+cd pine/tree
+make deps
+go build
+./tree # prints help
+```
+
+Training:
+```bash
+./tree -train -data=../test-data/iris.csv -save=../sav.gob
+```
+
+Predicting:
+```bash
+./tree -pred -model=../sav.gob -seed=5.7,3.8,1.7,0.3
+```
+
+All options:
+
+```text
+Usage of ./tree:
+  -charmode skipSize
+    	Character prediction mode rather than numeric feature mode. This will create test cases by iterating through the data skipSize at a time, and making the previous `sequenceLength` items have higher weights based on the closeness to the current item being predicted.s
+  -data string
+    	Training data input file
+  -folds int
+    	How many subdivisions of the dataset to make for cross-validation (default 5)
+  -m int
+    	Override calculation for feature split size (little m)
+  -max int
+    	Stop predicting after this many rounds (-pred only)
+  -model string
+    	Load a pretrained model for prediction
+  -pred
+    	Make a prediction
+  -profile string
+    	[cpu|mem] enable profiling
+  -save string
+    	Where to save the model after training
+  -seed string
+    	Predict based on this string of data
+  -seqlen int
+    	Normally equal to the number of variables during -charmode, override for fewer previous look-behind-memory-variables in every input test cases
+  -skipsize int
+    	During -charmode, how many items to skip before making another training case (default 3)
+  -subsetpct float
+    	Percent of the dataset which should be used to train a tree (always minus 1 fold for cross-validation) (default 0.6)
+  -tojson
+    	Convert a model to json
+  -train
+    	Train a model
+  -trees int
+    	How many decision trees to make per fold of the dataset (default 1)
+```
+
+## experimental character mode
+
+There is an experimental `-charmode` flag that attempts to encode strings of text and make predictions on it, like you would with a neural network.
 
 ## how it works
 
+![random decision tree ensembles training](decision-ensembles.png)
+
 Given a data set, rows of input features x, where the last column is the expected category y.
 Often these are encoded in CSV format. The data should be encoded to float32 parseable values.
 
@@ -32,3 +97,15 @@ To do it, start by splitting the whole dataset into equal bags (or folds) withou
 For example, say there are 20 samples and we want 4 folds. Each fold will have 5 samples, and none of the 20 samples will be repeated across all the folds. However, they need to be put randomly into the folds (random without replacement).
 
 Next, loop through all the folds. The fold in the loop iteration will be the test set, so reserve it for later. Use all the other folds to train a set of decision trees. In our example above, that means on the first fold, we would use the last 3 for training, on the second, use the first fold and the last two for training, etc. For every training set, construct decision trees that best predicts it.
+
+# License
+
+MIT
+
+# Sources
+
+http://blog.citizennet.com/blog/2012/11/10/random-forests-ensembles-and-performance-metrics
+
+http://blog.yhat.com/posts/random-forests-in-python.html
+
+https://machinelearningmastery.com/implement-random-forest-scratch-python/

asm-examples/oit_amd64.go renamed to old/asm-examples/oit_amd64.go

@@ -6,8 +6,10 @@ import (
 	"strings"
 )
 
+// datarow is a single row from a CSV file, where each column is a number
 type datarow []float32
 
+// parseRow is a utility which turns the file text from a CSV row into a list of numbers
 func parseRow(row string, rowIndex int) (dr datarow) {
 	cols := strings.Split(row, ",")
 	if len(cols) == 0 { // blank lines ignored

asm-examples/oit_amd64.s renamed to old/asm-examples/oit_amd64.s

@@ -19,13 +19,3 @@ type Tree struct {
 	leftSamples  []datarow // temp test cases for left group
 	rightSamples []datarow // temp test cases for right group
 }
-
-//func (t *Tree) String() string {
-//	return fmt.Sprintf("VariableIndex: %f, ValueIndex: %f, LeftNode: %+v, RightNode: %+v, LeftTerminal: %f, RightTerminal: %f",
-//		t.VariableIndex,
-//		t.ValueIndex,
-//		t.LeftNode,
-//		t.RightNode,
-//		t.LeftTerminal,
-//		t.RightTerminal)
-//}