public abstract class SequenceGraph extends Object implements MouseListener, MouseMotionListener
SequenceGraphFactory which is provided from a plugin
via GeneiousPlugin.getSequenceGraphFactories().
Simple SequenceGraphs (for example, hydrophobicity and similarity) can be created by via helper
functionality in DefaultSequenceGraphFactories.
More complex graphs (such as the sequence logos) are created via your
own SequenceGraphFactory and SequenceGraph
implementations.| Modifier and Type | Class and Description |
|---|---|
static class |
SequenceGraph.Location |
static class |
SequenceGraph.SequencePropertyRetriever
Provides additional information about the sequence(s) (e.g.
|
| Constructor and Description |
|---|
SequenceGraph() |
| Modifier and Type | Method and Description |
|---|---|
abstract void |
draw(GeneiousGraphics2D graphics,
int startResidue,
int endResidue,
int startX,
int startY,
int endX,
int endY,
double averageResidueWidth,
int previousSectionWidth,
int nextSectionWidth,
int previousSectionResidueCount,
int nextSectionResidueCount)
Draws a section of this graph.
|
void |
drawScaleBar(GeneiousGraphics2D graphics,
int startX,
int startY,
int endX,
int endY)
Optionally draw a scale bar next to the name of the graph.
|
int |
getApproximateCalculationWorkRequiredPerResidue()
Estimate an amount of work required to calculate graph values per residue.
|
protected Color |
getCurrentBackgroundColorFor(char residue)
Get the current background color for a given residue using the current sequence viewer color scheme.
|
protected Color |
getCurrentForegroundColorFor(char residue)
Get the current foreground color for a given residue using the current sequence viewer color scheme.
|
Cursor |
getCursor()
Returns a cursor that will appear when the mouse is over the graph.
|
int |
getDefaultHeight()
Supply a default height for this graph.
|
SequenceGraph.Location |
getDefaultLocation()
Determines whether this graph should appear above or below the sequence residues.
|
boolean |
getDefaultVisibility()
Returns whether this graph is visible by default.
|
String |
getDescription()
Provides a more verbose description for this graph than
getName(). |
String |
getLegendName()
Provides an alternative name displayed to the user.
|
abstract String |
getName()
Provides the name displayed to the user.
|
Options |
getOptions()
Provides options associated with this graph.
|
int |
getScaleBarWidth()
Supply a width of the scale bar for this graph.
|
SequenceGraph.SequencePropertyRetriever |
getSequencePropertyRetriever()
Gets a SequencePropertyRetriever for providing additional information (e.g.
|
Double |
getValue(int position) |
boolean |
hasValues() |
boolean |
isAnimated() |
boolean |
isProOnly()
Does this graph require an active license?
The default implementation returns false.
|
void |
mouseClicked(MouseEvent event)
The mouse has been clicked in this sequence graph.
|
void |
mouseDragged(MouseEvent event)
The mouse has been dragged in this sequence graph (with a drag starting inside the graph, not outside it).
|
void |
mouseEntered(MouseEvent event)
The mouse has left this sequence graph.
|
void |
mouseExited(MouseEvent event)
The mouse has left this sequence graph.
|
void |
mouseMoved(MouseEvent event)
The mouse has been moved in this sequence graph.
|
void |
mousePressed(MouseEvent event)
The mouse has been pressed in this sequence graph.
|
void |
mouseReleased(MouseEvent event)
The mouse has been released in this sequence graph.
|
void |
performBackgroundCalculations(ProgressListener progress)
Perform some background calculations in a non AWT thread before this graph is drawn.
|
void |
setCurrentColorScheme(Color[] backgroundColors,
Color[] foregroundColors)
Sets the current color scheme used by the sequence viewer.
|
void |
setPropertyRetrievalCallback(SequenceGraph.SequencePropertyRetriever sequencePropertyRetriever)
Sets the SequencePropertyRetriever that will be returned from future calls to
getSequencePropertyRetriever(). |
void |
setResidues(List<CharSequence> sequences,
List<NucleotideGraph> nucleotideGraphs,
boolean ignoreEndGaps)
Sets the residues of the sequence or alignment document that the graph applies to.
|
boolean |
supportsRenderingLargeRegions()
True if the graph supports rendering large regions at one time.
|
boolean |
supportsSlidingWindows()
Determine if the "sliding window size" option should apply to this graph.
|
public abstract String getName()
public String getLegendName()
getName() is displayed in the controls on the right.
For example, the chromatogram graph does not display its name
to the left of the graph (since it is obvious what graph it is)
The default implementation returns getName().public String getDescription()
getName(). Displayed as a tool tip.public void setResidues(List<CharSequence> sequences, List<NucleotideGraph> nucleotideGraphs, boolean ignoreEndGaps)
draw.
This method will only be called on residue based graphs (see SequenceGraphFactory). Only residue based graphs should and must implement this method.
This method will be called each time the user modifies a sequence or alignment
(potentially after each residue is typed). Therefore any implementation of this method should do very little work and instead calculate
anything necessary on demand when drawing.
Further information about the sequences (e.g. sequences names) can be obtained via getSequencePropertyRetriever() .sequences - The sequence residues the graph applies to. If this is not an alignment graph then this will be a one element array.
For those wondering why this is a CharSequence rather than a String, it is so that sequence editing
can rapidly insert residues into large sequences without being forced to construct new String instances every time a residue is typed.nucleotideGraphs - An array equal in length to residues.length. Each element will be non-null
if that sequence has an associated NucleotideGraph (chromatogram trace).ignoreEndGaps - If gaps at either end of sequences should be ignored when calcuating the graph.public Cursor getCursor()
public final void setPropertyRetrievalCallback(SequenceGraph.SequencePropertyRetriever sequencePropertyRetriever)
getSequencePropertyRetriever().
A plugin should not need not call this method. The sequence viewer sets it immediately after being given the graph by a SequenceGraphFactory.sequencePropertyRetriever - the SequencePropertyRetriever that will be returned from future calls to getSequencePropertyRetriever().public final SequenceGraph.SequencePropertyRetriever getSequencePropertyRetriever()
public abstract void draw(GeneiousGraphics2D graphics, int startResidue, int endResidue, int startX, int startY, int endX, int endY, double averageResidueWidth, int previousSectionWidth, int nextSectionWidth, int previousSectionResidueCount, int nextSectionResidueCount)
supportsRenderingLargeRegions(), and/or supportsSlidingWindows() and
the user has set the sliding window size is something greater than 1.
For example this method may receive calls like:
draw(g, 0, 0, 10, 0, 12, 20, 3.5, 4, 4, 1, 1) // draw a graph section for residue 0 between x coordinates 10 and 12 inclusive.draw(g, 1, 1, 13, 0, 16, 20, 3.5, 3, 3, 1, 1) // draw a graph section for residue 1 between x coordinates 13 and 16 inclusive.draw(g, 2, 2, 17, 0, 19, 20, 3.5, 4, 4, 1, 1) // draw a graph section for residue 2 between x coordinates 17 and 19 inclusive.draw(g, 0, 1, 10, 0, 10, 20, 0.4, 1, 1, 2, 3) // draw a graph section averaged over residues 0 and 1 at x coordinate 10.draw(g, 2, 4, 11, 0, 11, 20, 0.4, 1, 1, 2, 2) // draw a graph section averaged over residues 2 to 4 at x coordinate 11.draw(g, 5, 6, 12, 0, 12, 20, 0.4, 1, 1, 3, 2) // draw a graph section averaged over residues 5 and 6 at x coordinate 12.supportsRenderingLargeRegions()
draw(g, 0, 99, 10, 10, 389, 20, 3.8, 0, 0, 0, 0) // draw a graph section for residues 0 to 99 between x coordinates 10 and 389 inclusive.Graphics.drawRect(int, int, int, int) rather than Graphics2D.draw(java.awt.Shape)
The reason is that on large sequences,
where co-ordinates can be in the millions, floating point numbers do not provide
sufficient accuracy to draw in the correct location.
Alternatively, translate the graphics by -startX,-startY before drawing using
floating point accuracy, then undo the translation afterwards.graphics - graphics to draw tostartResidue - the first residue number which this graph section applies to (0 being the first residue)endResidue - the last residue number (inclusive) which this graph section applies to (0 being the first residue)startX - leftmost coordinate the graph section is allowed to render to.startY - topmost coordinate the graph section is allowed to render to.endX - rightmost coordinate the graph section is allowed to render to.endY - bottommost coordinate the graph section is allowed to render to.averageResidueWidth - the average horizontal width per residue.
Useful in situations where you want to vary behaviour depending on the width available.
The difference between startX and endX is not useful for doing this as it may
alternate between 1 and 2 if for example the average width is 2.5.
For example, the sequence logo graph does not wish to render text when then average width is less than 3.previousSectionWidth - (endX-startX+1) for the section drawn immediately to the left of this section. Useful when drawing line graphs between sections and we need to know exactly where the previous section was rendered. If there is no section immediately to the left of this section, this value is the section width of this section.nextSectionWidth - (endX-startX+1) for the section drawn immediately to the right of this section. Useful when drawing line graphs between sections and we need to know exactly where the previous section was rendered. If there is no section immediately to the right of this section, this value is the section width of this section.previousSectionResidueCount - (endResidue-startResidue+1) for the section drawn immediately to the left of this section. Useful when drawing line graphs between sections and we need to know exactly where the previous section was rendered. If there is no section immediately to the left of this section, this value is the residue count of this section.nextSectionResidueCount - (endResidue-startResidue+1) for the section drawn immediately to the right of this section. Useful when drawing line graphs between sections and we need to know exactly where the previous section was rendered. If there is no section immediately to the right of this section, this value is the residue count of this section.public boolean hasValues()
getValue(int). These graphs will be exportable to CSV or WIG files and their value will be displayed in the sequence viewer when the mouse is over the a point in the graph.getValue(int)public Double getValue(int position)
position - the 0-based position in the graph to get the value forhasValues() will always return null. Graphs that return true from hasValues() may return null for position which they don't assign a value to.hasValues()public int getDefaultHeight()
public boolean getDefaultVisibility()
public int getScaleBarWidth()
public void drawScaleBar(GeneiousGraphics2D graphics, int startX, int startY, int endX, int endY)
getScaleBarWidth()
to return something greater than 0.
The default implementation of this method does nothing.graphics - graphics to draw tostartX - leftmost coordinate the scale bar is allowed to render to.startY - topmost coordinate the scale bar is allowed to render to.endX - rightmost coordinate the scale bar is allowed to render to.endY - bottommost coordinate the scale bar is allowed to render to.public boolean supportsSlidingWindows()
draw
method may receive calls like:
draw(0,4,g,10,0,12,20,3.0) // draw a graph section averaged over residues 0 to 4 between x coordinates 10 and 12 inclusive.draw(1,5,g,13,0,15,20,3.0) // draw a graph section averaged over residues 1 to 5 between x coordinates 13 and 15 inclusive.draw(2,6,g,16,0,18,20,3.0) // draw a graph section averaged over residues 2 to 6 between x coordinates 16 and 18 inclusive.draw(GeneiousGraphics2D,int,int,int,int,int,int,double,int,int,int,int)public boolean isAnimated()
public Options getOptions()
public boolean supportsRenderingLargeRegions()
draw(GeneiousGraphics2D, int, int, int, int, int, int, double, int, int, int, int)public SequenceGraph.Location getDefaultLocation()
SequenceGraph.Location.BELOW_RESIDUESpublic int getApproximateCalculationWorkRequiredPerResidue()
performBackgroundCalculations(jebl.util.ProgressListener).
For example, when zoomed out viewing a large sequence, Geneious may request that
the graph render a range of 10,000 residues into the region a single horizontal coordinate wide.
Calculating the value the graph at this point is probably too time-consuming to be performed
in the AWT thread for every graph point.
Geneious evaluates the total work required to render the currently visible
section of the graph. If this is greater than 500,000, it will call performBackgroundCalculations
instead of calling draw.
The default implementation of this returns 0, which means that performBackgroundCalculations(jebl.util.ProgressListener) is never called.
Graphs may also wish to return Integer.MAX_VALUE. For example those that need to calculate all values before drawing the scale bar,
or those where the value of a single residue depends on all others
should do this. Geneious will then call
performBackgroundCalculations
before any calls to
draw
or
drawScaleBar
are made.
As a guideline, if it would take longer than about 1/2 a second of calculation
before anything can be drawn,
return Integer.MAX_VALUE from this method. Any implementation may (and is recommended to) vary its
result depending on the sequence lengths,
so that for short sequences, it may choose not to return Integer.MAX_VALUE
setResidues (for residue based graphs)
is guaranteed to be called before
this method.Integer.MAX_VALUE for graphs that need to calculate everything before drawing anythingpublic void performBackgroundCalculations(ProgressListener progress)
progress.isCanceled() and return immediately
if that method returns true. Failure do so will seriously degrade performance when editing
a sequence or alignment or when zooming in/out.
Geneious will not simultaneously make calls to draw
or setResidues(java.util.List, java.util.List, boolean) while this method is executing. Geneious will never invoke
this method simultaneously on the same SequenceGraph instance.progress - Currently this progress is unused, except for its cancellation functionality.
Nevertheless, it would be wise to report progress in case it is reported to the user in future versions.protected final Color getCurrentBackgroundColorFor(char residue)
residue - the residue to get the color for.protected final Color getCurrentForegroundColorFor(char residue)
residue - the residue to get the color for.public final void setCurrentColorScheme(Color[] backgroundColors, Color[] foregroundColors)
getCurrentBackgroundColorFor(char) or getCurrentForegroundColorFor(char).backgroundColors - an array of colors to be used where the array index is the character. e.g. backgroundColors['A']==backgroundColors['a]==Color.REDforegroundColors - an array of colors to be used where the array index is the character. e.g. backgroundColors['A']==backgroundColors['a]==Color.REDpublic boolean isProOnly()
public void mouseClicked(MouseEvent event)
InputEvent.consume() if it processes the click and doesn't want the sequence viewer to continue processing.mouseClicked in interface MouseListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.public void mousePressed(MouseEvent event)
InputEvent.consume() if it processes the press and doesn't want the sequence viewer to continue processing.mousePressed in interface MouseListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.public void mouseReleased(MouseEvent event)
mouseReleased in interface MouseListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.public void mouseEntered(MouseEvent event)
mouseEntered in interface MouseListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.public void mouseExited(MouseEvent event)
mouseExited in interface MouseListenerevent - the MouseEvent x and y are both 0 as of Geneious 5.3.public void mouseDragged(MouseEvent event)
InputEvent.consume() if it processes the event to cause a repaint of the viewmouseDragged in interface MouseMotionListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.public void mouseMoved(MouseEvent event)
mouseMoved in interface MouseMotionListenerevent - the MouseEvent where the y value is relative to the top of the graph and the x value is the logical x co-ordinate in the sequence viewer.