AACon Java Library

This page provides information pertaining to AACon Java library usage.

Using AACon Java library

For impatient: please find the complete example below

To calculate conservation using AACon follow the steps

  1. Load data
  2. Initialize the executor
  3. Decide on normalization
  4. Set conservation methods
  5. Output the results

All these steps are discussed in greater details below.

Loading data

AACon methods require a List of FastaSequence objects as input. Below is an example of how to load the Fasta formatted sequence file or the Clustal alignment file. For this call to succeed all the sequences must be of the same length (as this is an alignment).
List<FastaSequence> sequences = CmdParser.openInputStream(<PATH_TO_INPUT_FILE>);

For the examples of the input file please see AACon standalone executable help page.

Initializing the executor

AACon methods require the ExecutorService object which is used to parallel the calculations. The ExecutorService initialized with the number of threads equals to the number of cores on the executing machine is recommended for a faster calculation and can be obtained as follows:

int corenum = Runtime.getRuntime().availableProcessors();
ExecutorService executor = Executors.newFixedThreadPool(corenum);

Please take care to initialize and pass only one executor to all the methods to avoid the waist of resources. After use, the executor must be disposed of, it can be done as follows: executor.shutdown();

Normalization

AACon methods require the boolean parameter telling the system whether the results should be normalized or not. Normalized results have values between 0 and 1. Please note however, that some results cannot be normalized. In such a case, the system returns not normalized values, and log the issue to the standard error stream. The following formula is used for normalization n = (d - dmin)/(dmax - dmin) Negative results first converted to positive by adding an absolute value of the most negative result.

Setting the conservation methods

AACon ConservationCalculator.getConservation() method takes a Set of ConservationMethod to use for calculating the conservation. Below is a few examples of making such sets.

  • To calculate conservation according to KABAT method construct a set in the following way - EnumSet.of(ConservationMethod.KABAT).
  • For all the methods use the following construct - EnumSet.allOf(ConservationMethod.class)
  • For a set of methods including KABAT, JORES, SCHNEIDER, SHENKIN and GERSTEIN use the following construct - EnumSet.range(ConservationMethod.KABAT, ConservationMethod.GERSTEIN)

Output the results

The results can be output using one of the following methods

  1. ConservationFormatter.formatResults(Map<ConservationMethod, double[]> scores, OutputStream outStream)
  2. ConservationFormatter.formatResults(Map<ConservationMethod, double[]> scores, String outFilePath, Format format, List<FastaSequence> alignment)

Use the first method to output the results of the calculation without an alignment to any OutputStream. Use the second method to output results with the alignment.

First method usage example

// Usage example - printing results to the console
ConservationFormatter.outputScoreLine(result, System.out)
// printing results to the file
FileOutputStream outfile = new FileOutputStream("results.txt");
ConservationFormatter.formatResults(result, outfile);
outfile.close();

Second method usage example

// Usage example - printing results with alignment in Fasta format to the file called output.txt
ConservationFormatter.formatResults(result, "test.txt", Format.RESULT_WITH_ALIGNMENT, sequences);

For more information on the output formats please see standalone AACon help.

An example

Using AACon library for calculating conservation

// Determine the number of CPU cores available on the system.  
int corenum = Runtime.getRuntime().availableProcessors();
// Initialize the Executor instance with a number of cores
ExecutorService executor = Executors.newFixedThreadPool(corenum);

// Load the data from the file containing either Clustal formatted alignment 
// or a list of FASTA formatted sequences. Assuming that small.align file is
// in the same directory as this program
List<FastaSequence> sequences = CmdParser.openInputStream("small.align");
	
// Calculate conservation scores using all methods.
Map<ConservationMethod, double[]> result = getConservation(sequences, true, 
                         EnumSet.allOf(ConservationMethod.class)), executor);

// Print the results to the console.  
ConservationFormatter.formatResults(result, System.out);