Moving!

Future documentation will be on the forester-wiki.

Importing forester from Google code subversion into Eclipse IDE

forester source code is hosted by Google code at: http://code.google.com/p/forester/

To develop forester in Eclipse:

1. Prerequisite: ensure that your Eclipse IDE (version Helios or later) has a subversion plug-in, for example: http://www.eclipse.org/subversive/
2. In Eclipse, switch to “SVN Repository Exploring” perspective by: Window|Open Perspective|Other…|SVN Repository Exploring >> OK
3. Depending on software already installed within Eclipse, Eclipse might ask to install a “connector”, I select one which is compatible with subversion 1.6.x (?), after installation restart Eclipse
4. Click “New Repository Location” symbol (under “SVN Repositories”)
5. Enter this URL: “http://forester.googlecode.com/svn/” (or “https://forester.googlecode.com/svn/” for write access) >> Finish
6. Highlight and right-click: “forester” (version number), select “Find/Check Out As”
7. Select “Check out as project with the name specified (“forester”) and “Head Revision” and “Depth: Recursively” >> Next >> Finish
8. Switch to Java perspective by: Window|Open Perspective|Java, a Java project named “forester” should now be ready, with the source code in “java/src” (needs at least Java 1.6)
9. Test forester by running the “main” method in class “org.forester.test.Test”; the expected result is 0 (zero) failed tests
10. Build “forester.jar” by executing the “build.xml” ant-file in directory “java” [environment variable JAVA_HOME needs to point to a JDK (at least 1.6); furthermore, a “<jar> type doesn’t support the ‘level’ attribute” error is a likely sign that your Ant version is too old — at least version 1.7.1 is required]

Archaeopteryx adds capability to display images

Archaeopteryx (version 0.960 or higher) has now the capability to display images of organisms.

To do this, it takes advantage of the “uri” sub-element of the phyloXML “taxonomy” element, for example:

<taxonomy>
  <id provider="uniprot">27288</id>
  <scientific_name>Saccharomyces castellii</scientific_name>
  <uri type="image">http://www.diark.org/img/species_pict/Naumovia_castellii</uri>
</taxonomy>

For an example, go here

For web-masters/developers: Signing (Archaeopteryx) applets

Archaeopteryx applets versioned 0.960 or higher allow for the display of images (for an example, see here). In many cases, the corresponding image files do not originate from the same server as the applet itself, which leads to security related exceptions in case of unsigned applets. Thus, in order to distribute Archaeopteryx applets which are allowed to display images from arbitrary servers, the applet needs to be signed by the developer/web-master. For this, the two command line tools ‘keytool’ and ‘jarsigner‘ are needed, both of which are part of the JDK.

First, use keytool to generate a keystore:

% keytool -genkey -keystore <path/name for your keystore> -keyalg rsa
  -alias <alias> -keypass <key password> -storepass <store password>

keytool will then request the following information:

• What is your first and last name?
• What is the name of your organizational unit?
• What is the name of your organization?
• What is the name of your City or Locality?
• What is the name of your State or Province?
• What is the two-letter country code for this unit?

Second, use jarsigner to sign the archaeopteryx_applets.jar file:

% jarsigner -keystore <path/name for your keystore> -storepass <store password>
  -keypass <key password> -verbose archaeopteryx_applets.jar <alias>

Why are the applets of Archaeopteryx missing the menus “File” and “Analysis”?

The reason for the absence in the applets of the functionality found in the “File” and “Analysis” menus of the Archaeopteryx application are the security restrictions that are imposed on unsigned applets — for example, unsigned applets are not allowed to access the user’s file system and they are not allowed to print.

More information is available here.

Most the functions in the “Analysis” menu require to load an additional species tree, again something which unsigned applets are not allowed to do.

At this point I unfortunately do not have the resources to develop a “workaround” for these issues.

Importing forester into Eclipse IDE

08 FEB 2011: FORESTER SOURCE CODE IS NOW HOSTED BY GOOGLE CODE AT http://code.google.com/p/forester/ THUS THE MATERIAL BELOW DOES NOT APPLY ANYMORE!

SEE: https://aptxevo.wordpress.com/2011/02/08/importing-forester-from-google-code-subversion-into-eclipse-ide/

Mainly for those interested in developing/modifying Archaeopteryx and its underlying forester libraries.

This describes how to import forester into the Eclipse (Java) IDE:

• File | New | Project…
• CVS – Projects from CVS
• Next >
• Host: —
• Repository path: —
• Connection type: extssh
• Check: Use default port
• Next >
• Use specified module name: —
• Next >
• Finish

You will probably get two errors, to resolve them:

• Highlight “forester-atv” (in Package Explorer)
• Project|Properties
• highlight “Java Build Path”
• in “Libraries” tab:
  • Remove “gnujpdf.jar”, “iText-2.x.x.jar” (if there)
  • then, “Add External JARs…”:
  • 1. path/to/forester-atv/java/jars/iText-2.x.x.jar
    2. path/to/forester-atv/java/jars/fluorite.jar
• OK

two errors should be gone now.

Project can now be tested by:

• forester-atv/java/src/org.forester.test.Test.java right click “Run As” “Java application”

Project can now be built by (using Ant from within Eclipse):

• forester-atv/java/build.xml right click “Run As” “Ant Build”
• For this to work, environment variable JAVA_HOME needs to point to a JDK (at least 1.6)
• Furthermore, a “<jar> type doesn’t support the ‘level’ attribute” error is a likely sign that your Ant version is too old — at least version 1.7.1 is required.

How to add (typed) support values to a given tree

confadd is a simple command line tool to calculate typed confidence values for a given evolutionary tree.
Its input is typically one evolutionary tree which might or might not already have confidence values associated with its branches (the ‘target’) and a set (in the range of hundreds or more) of evolutionary trees (the ‘evaluators’) in which the frequency of splits represent confidences for the ‘target’. The ‘evaluators’ are typically the result of a bootstrap re-sampling analysis or of a Bayesian method.

See: http://www.phylosoft.org/forester/applications/confadd/

‘java.lang.NoClassDefFoundError’ in terminal mode

If you are getting a ‘java.lang.NoClassDefFoundError’ you most likely forgot the ‘-cp’ (classpath) option or the file forester.jar cannot be found where your ‘-cp’ points.

If you are in the same directory as the forester.jar you need to type:

% java -cp forester.jar org.forester.archaeopteryx.Archaeopteryx

If you are in a different directory than the jar file (the usual case), it is:

% java -cp /path/to/forester.jar org.forester.archaeopteryx.Archaeopteryx

In Windows, you need to use \ instead of /.

If you want to use a configuration file (example), you need to add:

-c path/to/_aptx_configuration_file

Branch/subtree colors as a function of taxonomy

Theory

In order to colorize subtrees/branches according to their associated taxonomies, the Archaeopteryx software needs to “know” two things:

1. The taxonomies (‘species’) associated with tree nodes (oftentimes only on external nodes, so-called ‘tips’ or ‘leaves’)
2. Information on what color to use for each taxonomy

In practice, the first information comes from the phyloXML formatted tree file, the second from a configuration file.

How-to

To colorize branches and (‘species specific’) subtrees according to their taxonomies:

1. Create a configuration file (see: http://www.phylosoft.org/forester/download/_aptx_configuration_file) containing lines like these:

species_color: NEMVE      0x00FFFF
species_color: MOUSE      0x9620F0

Colors need to be encoded in RGB hexadecimal format (more information). For example, red would be ‘0xFF0000’, green ‘0x00FF00’.

2. Your tree file needs to be in phyloXML format (see: phyloXML) and contain matching taxonomy information (relative to the configuration file). The following elements are used for taxonomy colorization (in this order: taxonomy code (e.g. ‘NEMVE” for the sea anemone Nematostella vectensis), scientific name, common name. See http://phylosoft.org/forester/applications/phyloxml_converter/ on how to transform Newick/New Hampshire formatted tree files into phyloXML.

3. Start Archaeopteryx with the following console command:

java -cp path\to\forester.jar org.forester.archaeopteryx.Archaeopteryx
 -c path\to\_aptx_configuration_file

Needless to say, it is much more convenient to use a .bat file (Windows) or a link (Unix/Linux) instead of typing into a console each time Archaeopteryx is to be started.

4. On the Archaeopteryx application, check ‘Colorize Branches’ checkbox (this simply turns colored branch display on and off, it does not perform any color calculation) and execute ‘Tools’|’Taxonomy Colorize Branches’ (which will infer taxonomies for species specific subtrees).