Java Library

This page provides information pertaining to AACon Java library usage.

Using the library

Note

For impatient please find the complete example below!

To calculate conservation using AACon follow the steps:

  1. Loading data - Load data
  2. Initialising the executor - Initialise the executor
  3. Normalisation - Decide on normalisation
  4. Setting the conservation methods - Set conservation methods
  5. Output the results - 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.

Initialising the executor

AACon methods require the ExecutorService object which is used to parallel the calculations. The ExecutorService initialised 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 initialise 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();

Normalisation

AACon methods require the boolean parameter telling the system whether the results should be normalised or not. Normalised results have values between 0 and 1. Please note however, that some results cannot be normalised. In such a case, the system returns not normalised values, and log the issue to the standard error stream. The following formula is used for normalisation

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.

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);