From: kjvdheide Date: Fri, 26 Jan 2018 19:05:25 +0000 (+0000) Subject: JAL-1953 first pass of adding javadoc, some methods renamed X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=01982168e80062f30c7ea08ceced49030cbfaffd;p=jalview.git JAL-1953 first pass of adding javadoc, some methods renamed --- diff --git a/src/jalview/ext/archaeopteryx/AptxControlPanel.java b/src/jalview/ext/archaeopteryx/AptxControlPanel.java index 2744908..aa0ffc6 100644 --- a/src/jalview/ext/archaeopteryx/AptxControlPanel.java +++ b/src/jalview/ext/archaeopteryx/AptxControlPanel.java @@ -4,10 +4,23 @@ import jalview.ext.treeviewer.TreeControlsI; import org.forester.archaeopteryx.ControlPanel; +/** + * Wrapper for the Archaeopteryx control panel (left side panel) Currently just + * used for refreshing Aptx upon initialisation. + * + * @author kjvanderheide + * + */ public class AptxControlPanel implements TreeControlsI { ControlPanel aptxCp; + /** + * Note that this control panel MUST be part of an Archaeopteryx frame + * + * @param aptxControlPanel + * the original Control Panel from Archaeopteryx + */ protected AptxControlPanel(ControlPanel aptxControlPanel) { aptxCp = aptxControlPanel; @@ -15,13 +28,6 @@ public class AptxControlPanel implements TreeControlsI } @Override - public void defaultSettings() - { - // TODO Auto-generated method stub - - } - - @Override public void displayEntireTree() { aptxCp.showWhole(); diff --git a/src/jalview/ext/archaeopteryx/AptxFrame.java b/src/jalview/ext/archaeopteryx/AptxFrame.java index 919d00e..2cf7953 100644 --- a/src/jalview/ext/archaeopteryx/AptxFrame.java +++ b/src/jalview/ext/archaeopteryx/AptxFrame.java @@ -266,7 +266,7 @@ public class AptxFrame implements TreeFrameI } @Override - public void checkMultipleTrees() + public void enableMultipleTrees() { aptxFrame.activateSaveAllIfNeeded(); diff --git a/src/jalview/ext/archaeopteryx/AptxInit.java b/src/jalview/ext/archaeopteryx/AptxInit.java index 9b89cea..cbdd237 100644 --- a/src/jalview/ext/archaeopteryx/AptxInit.java +++ b/src/jalview/ext/archaeopteryx/AptxInit.java @@ -451,7 +451,7 @@ public final class AptxInit // APTX_CONFIG); aptxApp.getTreeControls().displayEntireTree(); - aptxApp.checkMultipleTrees(); + aptxApp.enableMultipleTrees(); aptxFrames[i++] = aptxApp; } } @@ -501,7 +501,7 @@ public final class AptxInit LoadedTreeAssociationI bindAptxNodes = new LoadedTreeSequenceAssociation( jalviewAlignport.getAlignment().getSequencesArray(), jalviewTree); - bindAptxNodes.associateLeavesToSequences(); + bindAptxNodes.associateNodesToSequences(); TreeViewerUtils.associateNodesWithJalviewSequences(aptxApp, jalviewAlignport, bindAptxNodes.getAlignmentWithNodes(), @@ -524,14 +524,13 @@ public final class AptxInit LoadedTreeAssociationI bindAptxNodes = new LoadedTreeSequenceAssociation( jalviewAlignport.getAlignment().getSequencesArray(), jalviewTree); - bindAptxNodes.associateLeavesToSequences(); + bindAptxNodes.associateNodesToSequences(); TreeViewerUtils.associateNodesWithJalviewSequences(aptxApp, jalviewAlignport, bindAptxNodes.getAlignmentWithNodes(), bindAptxNodes.getNodesWithAlignment()); TreeViewerUtils.addTreeViewFrameToJalview(aptxApp); - // adaptAptxGui(aptxApp); //moved to AptxFrame return aptxApp; } diff --git a/src/jalview/ext/archaeopteryx/JalviewBinding.java b/src/jalview/ext/archaeopteryx/JalviewBinding.java index 91ea7be..f0c2866 100644 --- a/src/jalview/ext/archaeopteryx/JalviewBinding.java +++ b/src/jalview/ext/archaeopteryx/JalviewBinding.java @@ -178,7 +178,7 @@ public final class JalviewBinding LoadedTreeSequenceAssociation bindAptxNodes = new LoadedTreeSequenceAssociation( parentAvport.getAlignment().getSequencesArray(), treeView.getTree()); - bindAptxNodes.associateLeavesToSequences(); + bindAptxNodes.associateNodesToSequences(); sequencesBoundToNodes = bindAptxNodes.getAlignmentWithNodes(); nodesBoundToSequences = bindAptxNodes.getNodesWithAlignment(); TreeViewerUtils.associateNodesWithJalviewSequences(aptxFrame, @@ -571,8 +571,6 @@ public final class JalviewBinding for (TreeNodeI childNode : childNodes) { - // childNode.getBranchData().setBranchColor(new BranchColor(Color.BLUE)); - SequenceI matchingSequence = nodesBoundToSequences.get(childNode); if (matchingSequence != null) { @@ -589,12 +587,7 @@ public final class JalviewBinding } - /** - * Refactored from TreeCanvas. - * - * @param sequence - * of the node selected in the tree viewer. - */ + @Override public void treeSelectionChanged(final SequenceI sequence) { @@ -732,6 +725,17 @@ public final class JalviewBinding .getAssociatedPanels(parentAvport.getSequenceSetId()); } + @Override + public Map getAlignmentWithNodes() + { + return sequencesBoundToNodes; + } + + @Override + public Map getNodesWithAlignment() + { + return nodesBoundToSequences; + } } diff --git a/src/jalview/ext/archaeopteryx/Tree.java b/src/jalview/ext/archaeopteryx/Tree.java index 8c1d0be..20c428d 100644 --- a/src/jalview/ext/archaeopteryx/Tree.java +++ b/src/jalview/ext/archaeopteryx/Tree.java @@ -188,7 +188,7 @@ public class Tree implements TreeI } @Override - public void writeToXml(File outputFile) throws IOException + public void outputAsFile(File outputFile) throws IOException { PhylogenyWriter treeWriter = new PhylogenyWriter(); treeWriter.toPhyloXML(tree, 0, outputFile); diff --git a/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java b/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java index 19cf834..6252a57 100644 --- a/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java +++ b/src/jalview/ext/treeviewer/LoadedTreeAssociationI.java @@ -5,18 +5,36 @@ import jalview.datamodel.SequenceI; import java.util.Map; /** - * Interface for associating the leaves of a loaded in (not calculated) tree to - * the alignment sequences in Jalview. + * Interface for associating the nodes of a loaded in (instead of calculated) + * tree to the sequences of an alignment in Jalview. * * @author kjvanderheide * - * */ public interface LoadedTreeAssociationI { - public void associateLeavesToSequences(); + /** + * Tries to match the loaded in tree nodes as best as possible with Jalview + * sequences + * + * Partially refactored from the old Jalview TreeModel + * associateLeavesToSequences method. + */ + public void associateNodesToSequences(); + /** + * See + * {@link jalview.ext.treeviewer.TreeViewerBindingI#getAlignmentWithNodes()} + * + * + */ public Map getAlignmentWithNodes(); + /** + * See + * {@link jalview.ext.treeviewer.TreeViewerBindingI#getNodesWithAlignment()} + * + * + */ public Map getNodesWithAlignment(); } diff --git a/src/jalview/ext/treeviewer/LoadedTreeSequenceAssociation.java b/src/jalview/ext/treeviewer/LoadedTreeSequenceAssociation.java index 479e450..c05a57c 100644 --- a/src/jalview/ext/treeviewer/LoadedTreeSequenceAssociation.java +++ b/src/jalview/ext/treeviewer/LoadedTreeSequenceAssociation.java @@ -8,6 +8,14 @@ import java.util.HashMap; import java.util.Iterator; import java.util.Map; +/** + * Generic implementation of {@link LoadedTreeAssociationI } that tries to + * associate tree nodes based on comparing Jalview's sequence IDs to tree node + * names. + * + * @author kjvanderheide + * + */ public class LoadedTreeSequenceAssociation implements LoadedTreeAssociationI { @@ -29,18 +37,8 @@ public class LoadedTreeSequenceAssociation } - /** - * Tries to match sequences from Jalview with tree nodes in Archaeopteryx and - * fills in the tree node with sequence data if a match is found. - * - * Partially refactored from the old Jalview TreeModel - * associateLeavesToSequences method. - * - * @param seqs - * @param aptxTree - */ @Override - public void associateLeavesToSequences() + public void associateNodesToSequences() { SequenceIdMatcher algnIds = new SequenceIdMatcher(alignSequences); diff --git a/src/jalview/ext/treeviewer/TreeBuilderI.java b/src/jalview/ext/treeviewer/TreeBuilderI.java index 37bad36..066caae 100644 --- a/src/jalview/ext/treeviewer/TreeBuilderI.java +++ b/src/jalview/ext/treeviewer/TreeBuilderI.java @@ -10,14 +10,14 @@ import java.util.Map; */ public interface TreeBuilderI { + public TreeI buildTree(); + public TreeI buildTree(TreeNodeI treeRoot); - public TreeI buildTree(); + public String generateTreeName(); public Map getAlignmentBoundNodes(); public Map getNodesBoundAlignment(); - public String generateTreeName(); - } diff --git a/src/jalview/ext/treeviewer/TreeControlsI.java b/src/jalview/ext/treeviewer/TreeControlsI.java index 9a209e7..d33c73b 100644 --- a/src/jalview/ext/treeviewer/TreeControlsI.java +++ b/src/jalview/ext/treeviewer/TreeControlsI.java @@ -1,9 +1,18 @@ package jalview.ext.treeviewer; +/** + * Interface for visually manipulating the tree with methods that might be user + * triggered. + * + * @author kjvanderheide + * + */ public interface TreeControlsI { - public void defaultSettings(); - + /** + * Resets the current view so that it shows the tree in its entirety (in case + * it was previously zoomed in etc.) + */ public void displayEntireTree(); } diff --git a/src/jalview/ext/treeviewer/TreeFrameI.java b/src/jalview/ext/treeviewer/TreeFrameI.java index fef927c..beadceb 100644 --- a/src/jalview/ext/treeviewer/TreeFrameI.java +++ b/src/jalview/ext/treeviewer/TreeFrameI.java @@ -10,43 +10,69 @@ import javax.swing.RootPaneContainer; import javax.swing.WindowConstants; import javax.swing.event.InternalFrameListener; +/** + * Interface for implementing the (probably) top level frame of an external tree + * viewer. Note that this extends many interfaces shared with Swing frames but + * doesn't demand that an implementation actually is a Swing frame. + * + * @author kjvanderheide + * + */ public interface TreeFrameI extends Accessible, WindowConstants, RootPaneContainer, ImageObserver, MenuContainer { - public abstract TreePanelI getTreePanel(); + public void addFrameListener(InternalFrameListener listener); - public abstract TreeI getTree(); + /** + * Method for adding the actual frame to Jalview, probably through + * {@link jalview.gui.Desktop#addInternalFrame(javax.swing.JInternalFrame, String, boolean, int, int, boolean, boolean)} + * + * @param title + * @param makeVisible + * @param width + * @param height + * @param resizable + * @param ignoreMinSize + */ + public void addFrameToJalview(String title, boolean makeVisible, + int width, int height, boolean resizable, boolean ignoreMinSize); + + /** + * If the tree viewer used supports multiple trees in one frame this method + * should perform the needed adaptations. + */ + public abstract void enableMultipleTrees(); - public abstract void checkMultipleTrees(); + public InternalFrameListener[] getFrameListeners(); public abstract int getNumberOfTrees(); - public TreeControlsI getTreeControls(); + public Container getTopLevelAncestor(); - public void addFrameListener(InternalFrameListener listener); + public abstract TreeI getTree(); - public void removeFrameListener(InternalFrameListener listener); + public TreeControlsI getTreeControls(); - public InternalFrameListener[] getFrameListeners(); + public abstract TreePanelI getTreePanel(); - public void repaint(); + public TreeViewerBindingI getViewBinding(); public boolean isShowing(); - public Container getTopLevelAncestor(); - - public void addFrameToJalview(String title, boolean makeVisible, - int width, int height, boolean resizable, boolean ignoreMinSize); + public void removeFrameListener(InternalFrameListener listener); - public TreeViewerBindingI getViewBinding(); + /** + * @see java.awt.Component#repaint() + */ + public void repaint(); - public void setViewBinding(TreeViewerBindingI alignmentBinding); + public void setMaximumSize(Dimension maximumSize); public void setMinimumSize(Dimension minimumSize); - public void setMaximumSize(Dimension maximumSize); - public void setPreferredSize(Dimension preferredSize); + public void setViewBinding(TreeViewerBindingI alignmentBinding); + } diff --git a/src/jalview/ext/treeviewer/TreeI.java b/src/jalview/ext/treeviewer/TreeI.java index 702ff61..fbda8f1 100644 --- a/src/jalview/ext/treeviewer/TreeI.java +++ b/src/jalview/ext/treeviewer/TreeI.java @@ -7,42 +7,70 @@ import java.io.IOException; import java.util.Iterator; import java.util.List; +/** + * Interface for a generic phylogenetic tree, this does not necessarily have to + * be part of a tree panel. + * + * @author kjvanderheide + * + */ public interface TreeI { - public TreeNodeI getRoot(); - - public TreeNodeI getNodeWithName(String name); + /** + * Uses this tree as the basis for a new tree frame. + * + * @param instanceTitle + * name of the new tree frame. + * @return + */ + TreeFrameI createTreeViewerFromTree(String instanceTitle); - public TreeNodeI getFurthestNode(); + public String[] getAllLeafNames(); public TreeNodeI[] getAllNodes(); - public String[] getAllLeafNames(); + public TreeNodeI getFurthestNode(); + + public double getHeight(boolean adjustForCollapsedSubtrees); public List getNodeSequences(); - public void setTreeName(String treeTitle); + public TreeNodeI getNodeWithName(String name); - public void setRerootable(boolean b); + public TreeNodeI getRoot(); - public void setRooted(boolean b); + public String getTreeName(); + /** + * Check if the tree actually contains any nodes. + * + * @return true if tree has no nodes (or is deleted), false otherwise. + */ public boolean isEmpty(); - public String getTreeName(); - - public void setRoot(TreeNodeI rootNode); + public Iterator iterateInLevelOrder(); - public double getHeight(boolean adjustForCollapsedSubtrees); + public Iterator iterateInPostOrder(); public Iterator iterateInPreOrder(); - public Iterator iterateInLevelOrder(); + /** + * This should write the tree to the richest file format available for + * compatibility reasons as this is the method used when Jalview saves a tree + * to its project. + * + * @param outputFile + * File that tree should be written to + * @throws IOException + */ + public void outputAsFile(File outputFile) throws IOException; - public Iterator iterateInPostOrder(); + public void setRerootable(boolean b); - TreeFrameI createTreeViewerFromTree(String instanceTitle); + public void setRoot(TreeNodeI rootNode); - public void writeToXml(File outputFile) throws IOException; + public void setRooted(boolean b); + + public void setTreeName(String treeTitle); } diff --git a/src/jalview/ext/treeviewer/TreeNodeI.java b/src/jalview/ext/treeviewer/TreeNodeI.java index 89de82f..0ea76f7 100644 --- a/src/jalview/ext/treeviewer/TreeNodeI.java +++ b/src/jalview/ext/treeviewer/TreeNodeI.java @@ -8,28 +8,28 @@ import java.util.List; public interface TreeNodeI { - public String getNodeName(); + public void addAsChild(TreeNodeI childNode); public List getAllDescendants(); - public List getExternalDescendants(); - public List getDirectChildren(); - public void setSequence(SequenceI seq); + public List getExternalDescendants(); - public SequenceI getSequence(); + public long getId(); - public void addAsChild(TreeNodeI childNode); + public String getNodeName(); - public long getId(); + public SequenceI getSequence(); public float getXcoord(); public float getYcoord(); + public boolean isInternal(); + public void setBranchColor(Color branchColor); - public boolean isInternal(); + public void setSequence(SequenceI seq); } diff --git a/src/jalview/ext/treeviewer/TreePanelI.java b/src/jalview/ext/treeviewer/TreePanelI.java index e0612d0..e3d5800 100644 --- a/src/jalview/ext/treeviewer/TreePanelI.java +++ b/src/jalview/ext/treeviewer/TreePanelI.java @@ -14,27 +14,25 @@ public interface TreePanelI extends Accessible, MenuContainer { - public abstract void setTreeFile(File file); - - public abstract File getTreeFile(); - - public abstract TreeI getTree(); + public void addMouseListener(MouseListener listener); public abstract TreeNodeI findNode(int x, int y); - public abstract void setMatchingNodes(Set matchingNodes); + public int getHeight(); public abstract Set getMatchingNodes(); - public void addMouseListener(MouseListener listener); + public MouseListener[] getMouseListeners(); - public void removeMouseListener(MouseListener listener); + public float getPartitionThreshold(); - public MouseListener[] getMouseListeners(); + public abstract TreeI getTree(); - public void repaint(); + public abstract File getTreeFile(); - public void registerWithPaintRefresher(String sequenceSetIdentifier); + public abstract Rectangle getVisibleArea(); + + public int getWidth(); public void notifyPaintRefresher(boolean alignmentChanged, boolean validateSequences); @@ -42,22 +40,24 @@ public interface TreePanelI extends Accessible, MenuContainer public void notifyPaintRefresher(String newSeqSetIdentifier, boolean alignmentChanged, boolean validateSequences); - public int getWidth(); - - public int getHeight(); - public abstract void paintToFile(Graphics2D pg, int width, int height); - public boolean showingSubTree(); + public void registerWithPaintRefresher(String sequenceSetIdentifier); - public float getPartitionThreshold(); + public void removeMouseListener(MouseListener listener); - public abstract Rectangle getVisibleArea(); + public void repaint(); - public void setMinimumSize(Dimension minimumSize); + public abstract void setMatchingNodes(Set matchingNodes); public void setMaximumSize(Dimension maximumSize); + public void setMinimumSize(Dimension minimumSize); + public void setPreferredSize(Dimension preferredSize); + public abstract void setTreeFile(File file); + + public boolean showingSubTree(); + } diff --git a/src/jalview/ext/treeviewer/TreeParserI.java b/src/jalview/ext/treeviewer/TreeParserI.java index 017d246..b339615 100644 --- a/src/jalview/ext/treeviewer/TreeParserI.java +++ b/src/jalview/ext/treeviewer/TreeParserI.java @@ -4,12 +4,12 @@ import java.io.IOException; public interface TreeParserI { - public TreeI[] parse() throws IOException; - - public void setSource(Object source) throws IOException; - public String getName(); public TreeI[] getParsedTrees(); + public TreeI[] parse() throws IOException; + + public void setSource(Object source) throws IOException; + } diff --git a/src/jalview/ext/treeviewer/TreeViewerBindingI.java b/src/jalview/ext/treeviewer/TreeViewerBindingI.java index da999c6..bb6eb19 100644 --- a/src/jalview/ext/treeviewer/TreeViewerBindingI.java +++ b/src/jalview/ext/treeviewer/TreeViewerBindingI.java @@ -28,11 +28,13 @@ import jalview.structure.SelectionSource; import java.awt.event.ActionListener; import java.awt.event.MouseListener; +import java.util.Map; /** * - * Interface for binding a tree viewer to Jalview alignments. Assumes a tree - * viewer will both want to receive and send selection events. + * Interface for associating the nodes of a tree viewer with Jalview alignment + * sequences and communicating between the two. Assumes a tree viewer will both + * want to receive and send selection events. * * @author kjvanderheide * @@ -43,20 +45,49 @@ public interface TreeViewerBindingI SelectionSource { /** + * Gets the mapping for sequences with their associated tree nodes + * + * @return + */ + public Map getAlignmentWithNodes(); + + /** + * Gets the mapping for tree nodes with their associated sequences + * + * @return + */ + public Map getNodesWithAlignment(); + + /** + * + * @param x + * coordinate that functions as the clustering threshold + */ + public void partitionTree(final int x); + + public void showMatchingChildSequences(TreeNodeI parentNode); + + public void showMatchingSequence(TreeNodeI nodeToMatch); + + /** * If a node is selected in the tree panel this method highlights the * corresponding sequence in the Jalview alignment view. If an internal node * is selected all child sequences get highlighted as well. */ public void showNodeSelectionOnAlign(TreeNodeI node); - public void treeSelectionChanged(SequenceI sequence); - - public void showMatchingSequence(TreeNodeI nodeToMatch); - - public void showMatchingChildSequences(TreeNodeI parentNode); + /** + * Sorts the given alignment by the order in which the sequences appear in the + * tree. + * + * @param alignPanel + * Panel containing the alignment to be sorted. + * @return the sorting Command + */ + public CommandI sortAlignmentIn(AlignmentPanel alignPanel); public void sortByTree_actionPerformed(); - public CommandI sortAlignmentIn(AlignmentPanel alignPanel); + public void treeSelectionChanged(SequenceI sequence); } diff --git a/src/jalview/ext/treeviewer/TreeViewerUtils.java b/src/jalview/ext/treeviewer/TreeViewerUtils.java index ed22dfa..d5c1327 100644 --- a/src/jalview/ext/treeviewer/TreeViewerUtils.java +++ b/src/jalview/ext/treeviewer/TreeViewerUtils.java @@ -14,21 +14,6 @@ public final class TreeViewerUtils { private static Map activeViews = new HashMap<>(); - public static TreeViewerBindingI associateNodesWithJalviewSequences( - final TreeFrameI treeFrame, - final AlignmentViewport jalviewAlignViewport, - final Map alignMappedToNodes, - final Map nodesMappedToAlign) - { - TreeViewerBindingI treeBinding = new JalviewBinding(treeFrame, - jalviewAlignViewport, - alignMappedToNodes, nodesMappedToAlign); - jalviewAlignViewport.setCurrentExtTree(treeFrame.getTree()); - activeViews.put(treeFrame, treeFrame.getViewBinding()); - - return treeBinding; - } - public static TreeFrameI addTreeViewFrameToJalview( final TreeFrameI treeFrame) { @@ -51,10 +36,26 @@ public final class TreeViewerUtils treeFrame.addFrameToJalview(frameTitle, true, width, height, true, false); + treeFrame.getTreeControls().displayEntireTree(); return treeFrame; } + public static TreeViewerBindingI associateNodesWithJalviewSequences( + final TreeFrameI treeFrame, + final AlignmentViewport jalviewAlignViewport, + final Map alignMappedToNodes, + final Map nodesMappedToAlign) + { + TreeViewerBindingI treeBinding = new JalviewBinding(treeFrame, + jalviewAlignViewport, + alignMappedToNodes, nodesMappedToAlign); + jalviewAlignViewport.setCurrentExtTree(treeFrame.getTree()); + activeViews.put(treeFrame, treeFrame.getViewBinding()); + + return treeBinding; + } + public static Map getActiveTreeViews() { return activeViews; diff --git a/src/jalview/gui/Jalview2XML.java b/src/jalview/gui/Jalview2XML.java index c0246c3..cf52231 100644 --- a/src/jalview/gui/Jalview2XML.java +++ b/src/jalview/gui/Jalview2XML.java @@ -1114,7 +1114,7 @@ public class Jalview2XML TreeI tree = treeView.getTree(); try { - tree.writeToXml(new File("word")); + tree.outputAsFile(new File("word")); copyFileToJar(jout, "word", "aptx-test");