/ 
AI-FANN-Evolving-0.4
River stage zero No dependents
/ aivolver

NAME

aivolver - Evolves optimal artificial neural networks

SYNOPSIS

 aivolver [<config.yml>] [OPTION]...
	 try `aivolver --help' or `aivolver --manual' for more information

OPTIONS AND ARGUMENTS

***NO LONGER ACCURATE, CONSULT THE YAML CONFIG FILES***

<config.yml>

If the first command line argument is a file location, this will be interpreted as the location of a configuration file in YAML syntax structured as in this example: https://raw.github.com/naturalis/ai-fann-evolving/master/examples/conf.yml.

Subsequent command line arguments can then be provided that override the defaults in this configuration file.

-h/--help/-?

Prints help message and exits.

-m/--manual

Prints manual page and exits.

-v/--verbose

Increments verbosity of the process. Can be used multiple times.

-o/--outfile <file.ann>

File name for the fittest ANN file over all generations.

-d/--data <key=value>

The data argument is used multiple times, each time followed by a key/value pair that defines the location of one of the data files. The key/value pairs are as follows:

file=<data.tsv>

Defines the location of a file of input data.

fraction=<number>

Fraction of input data to use for training (versus testing).

-i/--initialize <key=value>

The initialize argument is used multiple times, each time followed by a key/value pair that defines one of the initialization settings for the (genetic) structure of the evolving population. The key/value pairs are as follows:

individual_count=<count>

Defines the number of individuals in the population.

chromosome_count=<count>

Defines the number of non-homologous chromosomes (i.e. n for diploid org). Normally 1 chromosome suffices.

gene_count=<count>

Defines the number of genes per chromosome. Normally 1 gene (i.e. 1 ANN) suffices.

-e/--experiment <key=value>

The experiment argument is used multiple times, each time followed by a key/value pair that defines one of the properties of the evolutionary process. The key/value pairs are as follows:

crossover_rate=<rate>

p of exchange between chromosomes.

mutation_rate=<rate>

p of a trait mutating.

reproduction_rate=<rate>

Proportion of population contributing to next generation.

ngens=<number>

Number of generations. This should be the longer the better, at least while the fitness is still improving.

workdir=<dir>

Output directory.

DESCRIPTION

Artificial neural networks (ANNs) are decision-making machines that develop their capabilities by training on input data. During this training, the ANN builds a topology of input neurons, hidden neurons, and output neurons that respond to signals in ways (and with sensitivities) that are determined by a variety of parameters. How these parameters will interact to give rise to the final functionality of the ANN is hard to predict a priori, but can be optimized in a variety of ways.

aivolver is a program that does this by evolving parameter settings using a genetic algorithm that runs for a number of generations determined by ngens. During this process it writes the intermediate ANNs into the workdir until the best result is written to the outfile.

The genetic algorithm proceeds by simulating a population of individual_count diploid individuals that each have chromosome_count chromosomes whose gene_count genes encode the parameters of the ANN. During each generation, each individual is trained on a sample data set, and the individual's fitness is then calculated by testing its predictive abilities on an out-of-sample data set. The fittest individuals (whose fraction of the total is determined by reproduction_rate) are selected for breeding in proportion to their fitness.

Before breeding, each individual undergoes a process of mutation, where a fraction of the ANN parameters is randomly perturbed. Both the size of the fraction and the maximum extent of the perturbation is determined by mutation_rate. Subsequently, the homologous chromosomes recombine (i.e. exchange parameters) at a rate determined by crossover_rate, which then results in (haploid) gametes. These gametes are fused with those of other individuals to give rise to the next generation.

TRAINING AND TEST DATA

The data that is used for training the ANNs and for subsequently testing their predictive abilities are provided as tab-separated tables. An example of an input data set is here:

https://github.com/naturalis/ai-fann-evolving/blob/master/examples/butterbeetles.tsv

The tables have a header row, with at least the following columns:

ID

The ID column contains a unique identifier (a string) for each record in the data set.

CLASS

Each CLASS column (multiple are allowed) specifies the classification that should emerge from one of the output neurons. Often this would be an integer, for example either 1 or -1 for a binary classification. The number of CLASS columns determines the number of outputs in the ANN.

[others]

All other columns are interpreted as the predictor columns from which the ANN must derive its capacity for classification. Normally these are continuous values, which are normalized between all records, e.g. in a range between -1 and 1.