### Introduction ###

IAMBEE is designed to analyse genomics data from evolution experiments.
It was specifically designed to analyse large genomics dataset from evolution experiments involving clonal organisms and complex traits.

### Requirements ###

IAMBEE runs on unix and windows. In principle it should run on a mac as well, but this was not tested.

IAMBEE requires java runtime environment 8 or higher.

### Input ###

IAMBEE requires an interaction network of the organism under research and a list of mutations together with their functional impact score and frequency increase during a selective sweep (see example data)
See examples for the correct format of these files.

### Output ###

All output will be written to the user-specified output folder. This includes several cnf files for each population and a concatenated cnf file for all populations together.
In the opt folder, the results of the optimization of the concatenated cnf file are stored. They are denoted by edgeCost_[SOME_COST]. Within these are the optimal subnetworks for every repeat and a file best_result.network, which is identical to the optimal subnetwork with the highest score. Additionally, information on the stability of the solutions for that specific edge cost can also be found.
Also in the opt folder, the resulting_networks folder contains the result, which is obtained by combining all best optimal subnetworks. This network is given as a sift, weightednetwork and xgmml file. Note that these files essentially depict the same network but have different layers of information.
A browser-based visualization is also available in the d3js_visualization folder. the highestScoringSubnetwork.html file can be readily opened in your browser (requires an internet connection).

### Use case ###

The example_data folder contains genomic data of 16 independently evolved populations of E. coli in ethanol conditions.
The strains were grown in increasing concentrations of ethanol (see the associated paper).
The example data is only the data of the first ethanol tolerance jump (from 6% to 6,5%).
The run_example.sh (unix) and run_example.bat (windows) script run the same code which analyses the example data and writes the output to the "output" folder.

### Important notes ###

For the purpose of time, the settings of the example script are turned low (5 repeats instead of 20 repeats for each optimization step within the parameter sweep and a smaller parameter sweep range with rather large step size of 0.1 for the parameter sweep).
This should allow the example to be run on a modern desktop in under 10 minutes. Because of this, results will differ from the results obtained in the paper (The solution will be smaller in this example as we did not run IAMBEE for the lower edge costs, which take longer).
It is, however, advised to turn the parameter settings up when analysing your own data (20 repeats and a step size which makes for at least 30 intermediate points)

Also note that the resulting network from the use case is not identical to the resulting network from the initial selective sweep in the paper as the paper additionally visualises the mutation from the second selective sweep. Also, the colors and position of the populations can differ.


### parameters and file formats ###

For additional information on the parameters, run the jar files without any input parameters.
For additional information on input file formats, see the use case example in example_data. 

### Troubleshooting ###


If run times are very long (do note that depending on the size of the dataset normal run times can be up to an hour on a modern desktop) it is usually due to either of two problems:

1) your concatenated .cnf file is too large. Check the size of this file, if it is above 3 mb you should consider manually setting the sld cutoff (-s flag).
This will discard all found paths with a probability below a certain value, as their value is too low to be considered (check manually for an adequate value for the sld cutoff).

2) The edge cost sweep was set inadequate. The proposed edge cost sweep in the use case will not be universally valid. If run times are very long while the cnf file is < 5 mb,
increase the costs used in the edge sweep. Conversely, if the algorithm finishes but does not yield any (or a very small) result, decrease the edge costs used in the sweep.

### Contact ###

For questions and remarks, please contact kathleen.marchal@intec.ugent.be