Initial setup of RandomCutForest

Author: jotok

.gitignore

@@ -0,0 +1,2 @@
+build
+*.iml

LICENSE

@@ -173,3 +173,30 @@
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -1 +1,2 @@
+RandomCutForest
 Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.

README.md

@@ -1,13 +1,87 @@
-## My Project
+# Random Cut Forest
 
-TODO: Fill this README out!
+This package is an implementation of the Random Cut Forest probabilistic data 
+structure. Random Cut Forests (RCFs) were originally developed at Amazon to use in an
+anomaly detection algorithm. After anomaly detection was launched, new 
+algorithms based on RCFs were developed for density estimation, imputation,
+and forecasting. The goal of this library is to be easy to use and to strike
+a balance between efficiency and extensibility.
 
-Be sure to:
+The public interface to this package is the RandomCutForest class, which 
+defines methods for anomaly detection, anomaly detection with attribution,
+density estimation, imputation, and forecasting.
 
-* Change the title in this README
-* Edit your repository description on GitHub
+## Basic operations
 
-## License
+To create a RandomCutForest instance with all parameters set to defaults:
 
-This project is licensed under the Apache-2.0 License.
+```java
+int dimensions = 1; // The number of dimensions in the input data, required
+RandomCutForest forest = RandomCutForest.defaultForest(dimensions);
+```
+
+To explicitly set optional parameters like number of trees in the forest or 
+sample size, RandomCutForest provides a builder:
+
+```java
+RandomCutForest forest = RandomCutForest.builder()
+    .numberOfTrees(90)
+    .sampleSize(200)
+    .dimensions(2) // still required!
+    .lambda(0.2)
+    .randomSeed(123)
+    .storeSequenceIndexesEnabled(true)
+    .centerOfMassEnabled(true)
+    .build();
+```
+
+Typical usage of a forest is to compute a statistic on an input data point and
+then update the forest with that point in a loop.
+
+```java
+Supplier<double[]> input = ...;
+
+while (true) {
+    double[] point = input.get();
+    double score = forest.getAnomalyScore(point);
+    forest.update(point);
+    System.out.println("Anomaly Score: " + score);
+}
+```
+
+## Command-line usage
+
+For each algorithm included in this package there is CLI application that can
+be used for experiments. These applications use `String::split` to read
+delimited data, and as such are **not intended for production use**. Instead,
+use these applications as example code and as a way to learn about the
+algorithms and their hyperparameters.
+
+You can build a local archive by running the Maven package command. Use the "excludedGroups" flag to disable the
+long-running "functional" tests, which take about 10 minutes to complete.
+
+```text
+% mvn package -DexcludedGroups=functional
+```
+
+You can then invoke an example CLI application by adding the superjar to your classpath. For example:
+
+```text
+% java -cp target/random-cut-forest-1.0.jar com.amazon.randomcutforest.runner.AnomalyScoreRunner --help
+Usage: java -cp RandomCutForest-1.0-super.jar com.amazon.randomcutforest.runner.AnomalyScoreRunner [options] < input_file > output_file
+
+Compute scalar anomaly scores from the input rows and append them to the output rows.
+
+Options:
+        --delimiter, -d: The character or string used as a field delimiter. (default: ,)
+        --header-row: Set to 'true' if the data contains a header row. (default: false)
+        --number-of-trees, -n: Number of trees to use in the forest. (default: 100)
+        --random-seed: Random seed to use in the Random Cut Forest (default: 42)
+        --sample-size, -s: Number of points to keep in sample for each tree. (default: 256)
+        --shingle-cyclic, -c: Set to 'true' to use cyclic shingles instead of linear shingles. (default: false)
+        --shingle-size, -g: Shingle size to use. (default: 1)
+        --window-size, -w: Window size of the sample or 0 for no window. (default: 0)
+
+        --help, -h: Print this help message and exit.
+```