Synthesis guide

There are many ways to synthesize the tree. Here is a guide to the code that allows for flexible construction of synthetic trees.

First, here is an example of use (the draft synthesis method modified from GraphExplorer.java):

        // To define a synthesis protocol, first we initialize a RelationshipEvaluator object
        RelationshipEvaluator draftSynthesisMethod = new RelationshipEvaluator();

        // To set filtering criteria, initialize a RelationshipFilter object
        RelationshipFilter rf = new RelationshipFilter();

        (include filtering example here)

        // Now assign the filtering method to the synthesis protocol
        draftSynthesisMethod.setFilter(rs);

        // To set ranking criteria, initialize a RelationshipRanker object
        RelationshipRanker rs = new RelationshipRanker();

        // We will rank using a priority list, so we need to build it first. The datatype of the priority 
        // list will be inferred by the ranking criterion. The values should be of the same type as the
        // property used for ranking, but for now we must store them as a list of <Object>
        ArrayList<Object> sourceIdPriorityList = new ArrayList<Object>();
        for (String sourceId : preferredSourceIds) {
        	sourceIdPriorityList.add((Object) sourceId);
        }

        // Now add ranking criteria to the ranker. the orderings will be executed in reverse order,
        // so that ranking criteria added first have higher priority

        // Rank relationships by source property "studyId", according to the specified priority list.
        // All available source properties are defined in the opentree.synthesis.SourceProperty enum.
        rs.addCriterion(new SourcePropertyPrioritizedRankingCriterion(
            SourceProperty.STUDYID, sourceIdPriorityList, sourceMetaIndex));

        // Do a secondary ranking according to the source property "studyYear" (this is probably
        // meaningless in this case, since rels the same study id should have the same year as well)
        rs.addCriterion(new SourcePropertyRankingCriterion(
            SourceProperty.YEAR, RankingOrder.DECREASING, sourceMetaIndex));
        
        // Now assign the ranking method to the synthesis protocol
        draftSynthesisMethod.setRanker(rs);

        // Set the conflict resolution criterion
        RelationshipConflictResolver rcr = new RelationshipConflictResolver(new AcyclicRankPriorityResolution());
        draftSynthesisMethod.setConflictResolver(rcr);

        // We can now use the RelationshipEvaluator that defines our synthesis method to do a synthesis traversal.
        // Below we supply it to the draftSynthesisRecur method (defined in GraphExplorer.java), which will traverse
        // the graph and store the synthesized relationships. Alternatively we could define other recursive functions
        // to store the synthesized rels in other ways, etc. Refer to GraphExplorer.java for more details.  
        
        // Set empty parameters for initial recursion
        Node originalParent = null;
        
        // Since we are saving rels to the graph, we need to have a transaction
        Transaction tx = graphDb.beginTx();
        try {
        	draftSynthesisRecur(startNode, originalParent, draftSynthesisMethod, DRAFTTREENAME);
        	tx.success();

        } catch (Exception ex) {
        	tx.failure();
        	ex.printStackTrace();

        } finally {
        	tx.finish();
        }

Synthesis is performed as a traversal that makes decisions at each node about which relationships to follow from that node to its children. There are essentially three elements of a synthesis query:

1. A relationship filter
2. A relationship ranker
3. A conflict resolution method

Decisions are made using information supplied to each of these elements. The decision making-process first filters the set of all incoming STREECHILDOF relationships, then ranks the remaining relationships, and then chooses some set of these according to the conflict resolution method. Any number of methods could be defined to perform each of these steps in various ways; there are (very simple) Java interfaces defined for each of these steps--new methods must of filtering, ranking, and conflict resolution must implement the appropriate interface.

Filtering and ranking methods implement FilterCriterion and RankingCriterion, respectively. Currently, there is a filtering method that allows source properties to be filtered using the comparison methods defined in FilterComparisonMethod (>, <, <=, >=, ==, !=). Available ranking methods allow ranking based on source properties in a regular order (increasing or decreasing), or ranking based on source properties using an arbitrary order that is pre-defined (i.e. a priority list, see examples above). There is currently only one conflict-resolution method (see example above), it uses the order-preference defined by the RelationshipRanker to prefer paths and guarantees a fully acyclic result. Multiple filtering and ranking criteria can be combined, but that is not an option for conflict resolution at this point.

Future additions should include a conflict resolution class for the branch and bound approach that Stephen built, and may also include other things like the possibility of node-based filtering, and more specific relationship ranking (e.g. if condition A is met, then do ranking X, otherwise do ranking Y).

The appropriate classes are all in the opentree.synthesis package.