commands,
boolean getReply, String msg)
{
return executeCommand(getReply, msg,
commands.toArray(new StructureCommandI[commands.size()]));
}
/**
* Executes one or more structure viewer commands, optionally returning the
* reply, and optionally showing a status message while the command is being
* executed.
*
* If a reply is wanted, the execution is done synchronously (waits),
* otherwise it is done in a separate thread (doesn't wait). WARNING: if you
* are sending commands that need to execute before later calls to
* executeCommand (e.g. mouseovers, which clean up after previous ones) then
* set getReply true to ensure that commands are not executed out of order.
*
* @param getReply
* @param msg
* @param cmds
* @return
*/
protected List executeCommand(boolean getReply, String msg,
StructureCommandI... cmds)
{
JalviewStructureDisplayI theViewer = getViewer();
final long handle = msg == null ? 0 : theViewer.startProgressBar(msg);
if (getReply)
{
/*
* execute and wait for reply
*/
List response = new ArrayList<>();
try
{
for (StructureCommandI cmd : cmds)
{
List replies = executeCommand(cmd, true);
if (replies != null)
{
response.addAll(replies);
}
}
return response;
} finally
{
if (msg != null)
{
theViewer.stopProgressBar(null, handle);
}
}
}
/*
* fire and forget
*/
String threadName = msg == null ? "StructureCommand" : msg;
new Thread(new Runnable()
{
@Override
public void run()
{
try
{
for (StructureCommandI cmd : cmds)
{
executeCommand(cmd, false);
}
} finally
{
if (msg != null)
{
SwingUtilities.invokeLater(new Runnable()
{
@Override
public void run()
{
theViewer.stopProgressBar(null, handle);
}
});
}
}
}
}, threadName).start();
return null;
}
/**
* Colours any structures associated with sequences in the given alignment as
* coloured in the alignment view, provided colourBySequence is enabled
*/
public void colourBySequence(AlignmentViewPanel alignmentv)
{
if (!colourBySequence || !isLoadingFinished() || getSsm() == null)
{
return;
}
Map colourMap = buildColoursMap(ssm, sequence,
alignmentv);
List colourBySequenceCommands = commandGenerator
.colourBySequence(colourMap);
executeCommands(colourBySequenceCommands, false, COLOURING_STRUCTURES);
}
/**
* Centre the display in the structure viewer
*/
public void focusView()
{
executeCommand(false, null, commandGenerator.focusView());
}
/**
* Generates and executes a command to show only specified chains in the
* structure viewer. The list of chains to show should contain entries
* formatted as "pdbid:chaincode".
*
* @param toShow
*/
public void showChains(List toShow)
{
// todo or reformat toShow list entries as modelNo:pdbId:chainCode ?
/*
* Reformat the pdbid:chainCode values as modelNo:chainCode
* since this is what is needed to construct the viewer command
* todo: find a less messy way to do this
*/
List showThese = new ArrayList<>();
for (String chainId : toShow)
{
String[] tokens = chainId.split("\\:");
if (tokens.length == 2)
{
String pdbFile = getFileForChain(chainId);
String model = getModelIdForFile(pdbFile);
showThese.add(model + ":" + tokens[1]);
}
}
executeCommands(commandGenerator.showChains(showThese), false, null);
}
/**
* Answers the structure viewer's model id given a PDB file name. Returns an
* empty string if model id is not found.
*
* @param chainId
* @return
*/
protected abstract String getModelIdForFile(String chainId);
public boolean hasFileLoadingError()
{
return fileLoadingError != null && fileLoadingError.length() > 0;
}
/**
* Returns the FeatureRenderer for the given alignment view
*
* @param avp
* @return
*/
public FeatureRenderer getFeatureRenderer(AlignmentViewPanel avp)
{
AlignmentViewPanel ap = (avp == null) ? getViewer().getAlignmentPanel()
: avp;
if (ap == null)
{
return null;
}
return ap.getFeatureRenderer();
}
protected void setStructureCommands(StructureCommandsI cmd)
{
commandGenerator = cmd;
}
/**
* Records association of one chain id (formatted as "pdbid:chainCode") with
* the corresponding PDB file name
*
* @param chainId
* @param fileName
*/
public void addChainFile(String chainId, String fileName)
{
chainFile.put(chainId, fileName);
}
/**
* Returns the PDB filename for the given chain id (formatted as
* "pdbid:chainCode"), or null if not found
*
* @param chainId
* @return
*/
protected String getFileForChain(String chainId)
{
return chainFile.get(chainId);
}
@Override
public void updateColours(Object source)
{
if (getViewer() == null)
{
// can happen if a viewer was not instantiated or cleaned up and is still
// registered - mostly during tests
return;
}
AlignmentViewPanel ap = (AlignmentViewPanel) source;
// ignore events from panels not used to colour this view
if (!getViewer().isUsedForColourBy(ap))
{
return;
}
if (!isLoadingFromArchive())
{
colourBySequence(ap);
}
}
public StructureCommandsI getCommandGenerator()
{
return commandGenerator;
}
protected abstract ViewerType getViewerType();
/**
* Builds a data structure which records mapped structure residues for each
* colour. From this we can easily generate the viewer commands for colour by
* sequence. Constructs and returns a map of {@code Color} to
* {@code AtomSpecModel}, where the atomspec model holds
*
*
* Model ids
* Chains
* Residue positions
*
*
* Ordering is by order of addition (for colours), natural ordering (for
* models and chains)
*
* @param ssm
* @param sequence
* @param viewPanel
* @return
*/
protected Map buildColoursMap(
StructureSelectionManager ssm, SequenceI[][] sequence,
AlignmentViewPanel viewPanel)
{
String[] files = getStructureFiles();
SequenceRenderer sr = getSequenceRenderer(viewPanel);
FeatureRenderer fr = viewPanel.getFeatureRenderer();
FeatureColourFinder finder = new FeatureColourFinder(fr);
AlignViewportI viewport = viewPanel.getAlignViewport();
HiddenColumns cs = viewport.getAlignment().getHiddenColumns();
AlignmentI al = viewport.getAlignment();
Map colourMap = new LinkedHashMap<>();
Color lastColour = null;
for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
{
final String modelId = getModelIdForFile(files[pdbfnum]);
StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
if (mapping == null || mapping.length < 1)
{
continue;
}
int startPos = -1, lastPos = -1;
String lastChain = "";
for (int s = 0; s < sequence[pdbfnum].length; s++)
{
for (int sp, m = 0; m < mapping.length; m++)
{
final SequenceI seq = sequence[pdbfnum][s];
if (mapping[m].getSequence() == seq
&& (sp = al.findIndex(seq)) > -1)
{
SequenceI asp = al.getSequenceAt(sp);
for (int r = 0; r < asp.getLength(); r++)
{
// no mapping to gaps in sequence
if (Comparison.isGap(asp.getCharAt(r)))
{
continue;
}
int pos = mapping[m].getPDBResNum(asp.findPosition(r));
if (pos < 1 || pos == lastPos)
{
continue;
}
Color colour = sr.getResidueColour(seq, r, finder);
/*
* darker colour for hidden regions
*/
if (!cs.isVisible(r))
{
colour = Color.GRAY;
}
final String chain = mapping[m].getChain();
/*
* Just keep incrementing the end position for this colour range
* _unless_ colour, PDB model or chain has changed, or there is a
* gap in the mapped residue sequence
*/
final boolean newColour = !colour.equals(lastColour);
final boolean nonContig = lastPos + 1 != pos;
final boolean newChain = !chain.equals(lastChain);
if (newColour || nonContig || newChain)
{
if (startPos != -1)
{
addAtomSpecRange(colourMap, lastColour, modelId, startPos,
lastPos, lastChain);
}
startPos = pos;
}
lastColour = colour;
lastPos = pos;
lastChain = chain;
}
// final colour range
if (lastColour != null)
{
addAtomSpecRange(colourMap, lastColour, modelId, startPos,
lastPos, lastChain);
}
// break;
}
}
}
}
return colourMap;
}
/**
* todo better refactoring (map lookup or similar to get viewer structure id)
*
* @param pdbfnum
* @param file
* @return
*/
protected String getModelId(int pdbfnum, String file)
{
return String.valueOf(pdbfnum);
}
/**
* Saves chains, formatted as "pdbId:chainCode", and lookups from this to the
* full PDB file path
*
* @param pdb
* @param file
*/
public void stashFoundChains(StructureFile pdb, String file)
{
for (int i = 0; i < pdb.getChains().size(); i++)
{
String chid = pdb.getId() + ":" + pdb.getChains().elementAt(i).id;
addChainFile(chid, file);
getChainNames().add(chid);
}
}
/**
* Helper method to add one contiguous range to the AtomSpec model for the
* given value (creating the model if necessary). As used by Jalview,
* {@code value} is
*
* - a colour, when building a 'colour structure by sequence' command
* - a feature value, when building a 'set Chimera attributes from features'
* command
*
*
* @param map
* @param value
* @param model
* @param startPos
* @param endPos
* @param chain
*/
public static final void addAtomSpecRange(Map map,
Object value, String model, int startPos, int endPos,
String chain)
{
/*
* Get/initialize map of data for the colour
*/
AtomSpecModel atomSpec = map.get(value);
if (atomSpec == null)
{
atomSpec = new AtomSpecModel();
map.put(value, atomSpec);
}
atomSpec.addRange(model, startPos, endPos, chain);
}
/**
* Returns the file extension (including '.' separator) to use for a saved
* viewer session file. Default is to return null (not supported), override as
* required.
*
* @return
*/
public String getSessionFileExtension()
{
return null;
}
/**
* If supported, saves the state of the structure viewer to a temporary file
* and returns the file. Returns null and logs an error on any failure.
*
* @return
*/
public File saveSession()
{
String prefix = getViewerType().toString();
String suffix = getSessionFileExtension();
File f = null;
try
{
f = File.createTempFile(prefix, suffix);
saveSession(f);
} catch (IOException e)
{
Console.error(String.format("Error saving %s session: %s", prefix,
e.toString()));
}
return f;
}
/**
* Saves the structure viewer session to the given file
*
* @param f
*/
protected void saveSession(File f)
{
StructureCommandI cmd = commandGenerator.saveSession(f.getPath());
if (cmd != null)
{
executeCommand(cmd, false);
}
}
/**
* Returns true if the viewer is an external structure viewer for which the
* process is still alive, else false (for Jmol, or an external viewer which
* the user has independently closed)
*
* @return
*/
public boolean isViewerRunning()
{
return false;
}
/**
* Closes Jalview's structure viewer panel and releases associated resources.
* If it is managing an external viewer program, and {@code forceClose} is
* true, also asks that program to close.
*
* @param forceClose
*/
public void closeViewer(boolean forceClose)
{
getSsm().removeStructureViewerListener(this, this.getStructureFiles());
releaseUIResources();
/*
* end the thread that closes this panel if the external viewer closes
*/
if (externalViewerMonitor != null)
{
externalViewerMonitor.interrupt();
externalViewerMonitor = null;
}
stopListening();
if (forceClose)
{
StructureCommandI cmd = getCommandGenerator().closeViewer();
if (cmd != null)
{
executeCommand(cmd, false);
}
}
}
/**
* Returns the URL of a help page for the structure viewer, or null if none is
* known
*
* @return
*/
public String getHelpURL()
{
return null;
}
/**
*
* Helper method to build a map of
* { featureType, { feature value, AtomSpecModel } }
*
*
* @param viewPanel
* @return
*/
protected Map> buildFeaturesMap(
AlignmentViewPanel viewPanel)
{
Map> theMap = new LinkedHashMap<>();
String[] files = getStructureFiles();
if (files == null)
{
return theMap;
}
FeatureRenderer fr = viewPanel.getFeatureRenderer();
if (fr == null)
{
return theMap;
}
AlignViewportI viewport = viewPanel.getAlignViewport();
List visibleFeatures = fr.getDisplayedFeatureTypes();
/*
* if alignment is showing features from complement, we also transfer
* these features to the corresponding mapped structure residues
*/
boolean showLinkedFeatures = viewport.isShowComplementFeatures();
List complementFeatures = new ArrayList<>();
FeatureRenderer complementRenderer = null;
if (showLinkedFeatures)
{
AlignViewportI comp = fr.getViewport().getCodingComplement();
if (comp != null)
{
complementRenderer = Desktop.getAlignFrameFor(comp)
.getFeatureRenderer();
complementFeatures = complementRenderer.getDisplayedFeatureTypes();
}
}
if (visibleFeatures.isEmpty() && complementFeatures.isEmpty())
{
return theMap;
}
AlignmentI alignment = viewPanel.getAlignment();
SequenceI[][] seqs = getSequence();
for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
{
String modelId = getModelIdForFile(files[pdbfnum]);
StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
if (mapping == null || mapping.length < 1)
{
continue;
}
for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
{
for (int m = 0; m < mapping.length; m++)
{
final SequenceI seq = seqs[pdbfnum][seqNo];
int sp = alignment.findIndex(seq);
StructureMapping structureMapping = mapping[m];
if (structureMapping.getSequence() == seq && sp > -1)
{
/*
* found a sequence with a mapping to a structure;
* now scan its features
*/
if (!visibleFeatures.isEmpty())
{
scanSequenceFeatures(visibleFeatures, structureMapping, seq,
theMap, modelId);
}
if (showLinkedFeatures)
{
scanComplementFeatures(complementRenderer, structureMapping,
seq, theMap, modelId);
}
}
}
}
}
return theMap;
}
/**
* Ask the structure viewer to open a session file. Returns true if
* successful, else false (or not supported).
*
* @param filepath
* @return
*/
public boolean openSession(String filepath)
{
StructureCommandI cmd = getCommandGenerator().openSession(filepath);
if (cmd == null)
{
return false;
}
executeCommand(cmd, true);
// todo: test for failure - how?
return true;
}
/**
* Scans visible features in mapped positions of the CDS/peptide complement,
* and adds any found to the map of attribute values/structure positions
*
* @param complementRenderer
* @param structureMapping
* @param seq
* @param theMap
* @param modelNumber
*/
protected static void scanComplementFeatures(
FeatureRenderer complementRenderer,
StructureMapping structureMapping, SequenceI seq,
Map> theMap,
String modelNumber)
{
/*
* for each sequence residue mapped to a structure position...
*/
for (int seqPos : structureMapping.getMapping().keySet())
{
/*
* find visible complementary features at mapped position(s)
*/
MappedFeatures mf = complementRenderer
.findComplementFeaturesAtResidue(seq, seqPos);
if (mf != null)
{
for (SequenceFeature sf : mf.features)
{
String type = sf.getType();
/*
* Don't copy features which originated from Chimera
*/
if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
.equals(sf.getFeatureGroup()))
{
continue;
}
/*
* record feature 'value' (score/description/type) as at the
* corresponding structure position
*/
List mappedRanges = structureMapping
.getPDBResNumRanges(seqPos, seqPos);
if (!mappedRanges.isEmpty())
{
String value = sf.getDescription();
if (value == null || value.length() == 0)
{
value = type;
}
float score = sf.getScore();
if (score != 0f && !Float.isNaN(score))
{
value = Float.toString(score);
}
Map featureValues = theMap.get(type);
if (featureValues == null)
{
featureValues = new HashMap<>();
theMap.put(type, featureValues);
}
for (int[] range : mappedRanges)
{
addAtomSpecRange(featureValues, value, modelNumber, range[0],
range[1], structureMapping.getChain());
}
}
}
}
}
}
/**
* Inspect features on the sequence; for each feature that is visible,
* determine its mapped ranges in the structure (if any) according to the
* given mapping, and add them to the map.
*
* @param visibleFeatures
* @param mapping
* @param seq
* @param theMap
* @param modelId
*/
protected static void scanSequenceFeatures(List visibleFeatures,
StructureMapping mapping, SequenceI seq,
Map> theMap, String modelId)
{
List sfs = seq.getFeatures().getPositionalFeatures(
visibleFeatures.toArray(new String[visibleFeatures.size()]));
for (SequenceFeature sf : sfs)
{
String type = sf.getType();
/*
* Don't copy features which originated from Chimera
*/
if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
.equals(sf.getFeatureGroup()))
{
continue;
}
List mappedRanges = mapping.getPDBResNumRanges(sf.getBegin(),
sf.getEnd());
if (!mappedRanges.isEmpty())
{
String value = sf.getDescription();
if (value == null || value.length() == 0)
{
value = type;
}
float score = sf.getScore();
if (score != 0f && !Float.isNaN(score))
{
value = Float.toString(score);
}
Map featureValues = theMap.get(type);
if (featureValues == null)
{
featureValues = new HashMap<>();
theMap.put(type, featureValues);
}
for (int[] range : mappedRanges)
{
addAtomSpecRange(featureValues, value, modelId, range[0],
range[1], mapping.getChain());
}
}
}
}
/**
* Returns the number of structure files in the structure viewer and mapped to
* Jalview. This may be zero if the files are still in the process of loading
* in the viewer.
*
* @return
*/
public int getMappedStructureCount()
{
String[] files = getStructureFiles();
return files == null ? 0 : files.length;
}
/**
* Starts a thread that waits for the external viewer program process to
* finish, so that we can then close the associated resources. This avoids
* leaving orphaned viewer panels in Jalview if the user closes the external
* viewer.
*
* @param p
*/
protected void startExternalViewerMonitor(Process p)
{
externalViewerMonitor = new Thread(new Runnable()
{
@Override
public void run()
{
try
{
p.waitFor();
JalviewStructureDisplayI display = getViewer();
if (display != null)
{
display.closeViewer(false);
}
} catch (InterruptedException e)
{
// exit thread if Chimera Viewer is closed in Jalview
}
}
});
externalViewerMonitor.start();
}
/**
* If supported by the external structure viewer, sends it commands to notify
* model or selection changes to the specified URL (where Jalview has started
* a listener)
*
* @param uri
*/
protected void startListening(String uri)
{
List commands = getCommandGenerator()
.startNotifications(uri);
if (commands != null)
{
executeCommands(commands, false, null);
}
}
/**
* If supported by the external structure viewer, sends it commands to stop
* notifying model or selection changes
*/
protected void stopListening()
{
List commands = getCommandGenerator()
.stopNotifications();
if (commands != null)
{
executeCommands(commands, false, null);
}
}
/**
* If supported by the structure viewer, queries it for all residue attributes
* with the given attribute name, and creates features on corresponding
* residues of the alignment. Returns the number of features added.
*
* @param attName
* @param alignmentPanel
* @return
*/
public int copyStructureAttributesToFeatures(String attName,
AlignmentPanel alignmentPanel)
{
StructureCommandI cmd = getCommandGenerator()
.getResidueAttributes(attName);
if (cmd == null)
{
return 0;
}
List residueAttributes = executeCommand(cmd, true);
int featuresAdded = createFeaturesForAttributes(attName,
residueAttributes);
if (featuresAdded > 0)
{
alignmentPanel.getFeatureRenderer().featuresAdded();
}
return featuresAdded;
}
/**
* Parses {@code residueAttributes} and creates sequence features on any
* mapped alignment residues. Returns the number of features created.
*
* {@code residueAttributes} is the reply from the structure viewer to a
* command to list any residue attributes for the given attribute name. Syntax
* and parsing of this is viewer-specific.
*
* @param attName
* @param residueAttributes
* @return
*/
protected int createFeaturesForAttributes(String attName,
List residueAttributes)
{
return 0;
}
}