These files are supplemental to the BirdsOfAFeather project Java base classes.
Their purpose is to give researchers an easy starting point for
- generating solvability data (SolvabilityDataGenerator.java),
- adding features to such data (DataFeatureAdder.java), and
- experimenting with classification of ready-made simple data. (boaf-data-*)

These files are to supplemental to http://cs.gettysburg.edu/~tneller/puzzles/boaf/BirdsOfAFeather.zip and assume such files to be present in the same default Java package.

SolvabilityDataGenerator.java - 

This class generates a comma-separated value (CSV) file with (puzzle state, solvable) pairs.  These lines will generate a file boaf-data-0-100.csv containing pairs from simulated solution play from puzzle seed 0 through 99.

SolvabilityDataGenerator generator = new SolvabilityDataGenerator("boaf-data-0-100", 0, 100);
generator.generateCSVData();  

The initial node is searched to check solvability and the pair is output. For seed 0 and 10 initial states, these are the lines found in the output boaf-data-0-100.csv:

"TH5HKSTC6SACTS6C6HQD4SJDJS3C5D3S",1

"5S5H6H6S5D4D2HJHKD2SQD2DAS9C3SJD",0

If the initial state is solvable, the generator will select a random solvable child to play to at each state of the game until it is solved.  For each state that has both solvable and unsolvable children (i.e. successor states), a pair will be output for each child.  In this way, we focus attention of data collection on the decisions that matter in heuristically guiding search to a solution.

The state description, e.g. "TH5HKSTC6SACTS6C6HQD4SJDJS3C5D3S", is a row-major ordered sequence of 2-character card descriptors as defined in the Card.java class.  When a card grid cell is empty, the characters "--" are used.

One can also create additional stopping conditions for data generation as detailed in the class documentation.

DataFeatureAdder.java -

This line initiates the computation that will read in the aforementioned file and add new features in support of building solvability classifiers/regressions:
 
new DataFeatureAdder("boaf-data-0-100").exportCSV("boaf-data-0-100-with-features");

In this case, we take the data from containing only pairs with:

- state description
- a 1/0 indicating solvability/unsolvability, respectively

to 5-tuples with:

- state description
- the number of cards in the grid
- the number of children (i.e. legal plays) in that state
- the ratio of children to cards
- a 1/0 indicating solvability/unsolvability, respectively

There are, of course, many other useful features that are up to your creativity, curiosity, and ingenuity to compute and analyze.  That's what this code is for!

What you'll find in this file is starter code that shows you how to:
- read in the basic generated CSV file of pairs,
- convert the state descriptiohn to an actual BirdsOfAFeatherNode object to enable the computation of additional features, and 
- a model for how those features get bundled together and output as a new CSV file.

The beginning CSV output for the example above is...

"state","num_cards","num_moves","ratio_moves_per_card","solvable"
"TH5HKSTC6SACTS6C6HQD4SJDJS3C5D3S",1.0,0.7307692307692307,0.7307692307692307,1
"--THKSTC--ACTS--6HQD5DJDJS3C--6S",0.7142857142857143,0.34615384615384615,0.46153846153846156,1
"5H--KSTC--ACTS--6HQD5DJDJS3C--6S",0.7142857142857143,0.34615384615384615,0.46153846153846156,1

DataFeatureAdder is just a starting point for you.  Where you decide to take it is the fun part.  See the accompanying overview video for some starting resources to guide your learning.

If you can build a good, efficient classifier or estimator of relative solvability of a state, it could be used to order children in search and lead to the development of very efficient solvers for Birds of a Feather.  Enjoy!