Tutorial: Using the GrandUnifiedReader, adding new properties.

Using the GrandUnifiedReader class.

The "GrandUnifiedReader" class is class which combines the power of "UniversalTreeReader" and UniversalMetadataReader".

• The first thing you need to do is to prepare a tree file and an array of meta files. One for each tree in the tree file.

    File treeFile = new File("samples\\mammals\\mammalsTree.xml");
    File metaFile = new File("samples\\mammals\\mammals_in_tree.txt");        
  
    File[] metaFiles = new File[]{metaFile};
  

• Now prepare a new GrandUnifiedReader object and set its parameters as.

    GrandUnifiedReader gur = new GrandUnifiedReader();
    gur.setTreeFile(treeFile).setMetaFile(metaFiles).setDelim('\t').setCladeDiv(6);
  

In the above line you have set the tree file and meta file array to be used. You have tab as the delimiter character, and you have specified the values in column 6th of the input file to be used a clade division.

If you are not giving any clade information, you can set it to zero. setCladeDiv(0); In this case all clades will be given a single color.

• The last thing you have to specify is to set the arguments. That is to say which columns correspond to what values in the input file. Doing this gives you the freedom to prepare your input file in any consistent manner and then specify the columns.

    gur.setArgs(5,3,4,1,2);
  

The order of the properties is given in PhylogenyKitchen class array.

private final static String[] PROPERTIES = {"label",
                                            "latitude",
                                            "longitude",
                                            "id",
                                            "sname",    //Scientific Name
                                            "cname",    //Common Name
                                           };

gur.setArgs(5,3,4,1,2) means that the third column in the input file is to be used as the label. The third column is to be used as the longitude, the fourth column as the longitude, the first column as the id, the second column as the scientific name. Nothing has been specified for common name that is to say you do not have / or do not want any column to be read as cname.

In fact the trailing unused properties can be left unspecified gur.setArgs(5,3,4,1,2,0) is the same as the above. A value of zero means that you have no column/or you do not want any column to be read as cname.

As an another example gur.setArgs(5,3,4,0,2) means that you have no column/ or do not any column to be read as id.

• Once this is done you need to invoke the following function.

    gur.buildUnifiedPhylogeny();
  

• And now you can extract the phylogeny using the following two functions. Remember that these methods should be invoked only after buildUnifiedPhylogeny() has been invooked.

    Phylogeny phy = gur.getPhylogeny();
    Phylogeny phyArray[] =  gur.getPhylogenyArray();
  

• And now how do we use these properties. Well that is something only an advanced user would want. But doing this is also easy. There is a method named mixIngredients(PhylogenyNode node) in PhylogenyKitchen class. It is here where you can get these values. As an example see the function setNodeData(NodeData nodeData)

    Taxonomy taxo = new Taxonomy();
    nodeData.setTaxonomy(taxo);
    taxo.setScientificName(get("sname"));
    taxo.setCommonName(get("cname"));
  
    Distribution dist = new Distribution(get("label"));
    nodeData.setDistribution(dist);
    Float lat = Float.parseFloat(get("latitude"));
    Float lon = Float.parseFloat(get("longitude"));
    dist.setLatitude(new BigDecimal(lat));
    dist.setLongitude(new BigDecimal(lon));
    dist.setAltitude(BigDecimal.ZERO);
  

Here all we have used the function get() to get the value of that property. If the column number for that property is zero or unspecified. Then get() returns a value of null.

All the properties that the user specifies the columns of it is the user who is responsible for storing them somewhere in the phylogeny. Rest all columns are read as a String and stored in the PhylogenyMould as it is.