Editing

From 6fc9aca27f606f6e3a0121597896e1a5dae35c36 Mon Sep 17 00:00:00 2001 From: jprocter Date: Sun, 9 Apr 2006 18:02:49 +0000 Subject: [PATCH] doco writing. --- help/help.jhm | 5 +- help/helpTOC.xml | 10 ++- help/html/editing/index.html | 20 +++--- help/html/features/annotationsFormat.html | 109 +++++++++++++++++++---------- help/html/features/featuresFormat.html | 99 ++++++++++++++++++-------- help/html/features/search.html | 8 ++- help/html/features/seqfeatures.html | 19 +++-- help/html/whatsNew.html | 57 ++++++++++----- 8 files changed, 222 insertions(+), 105 deletions(-) diff --git a/help/help.jhm b/help/help.jhm index 2dff0de..4ff7a28 100755 --- a/help/help.jhm +++ b/help/help.jhm @@ -8,7 +8,7 @@ - + @@ -21,7 +21,10 @@ + + + diff --git a/help/helpTOC.xml b/help/helpTOC.xml index c148afc..1bbe5c0 100755 --- a/help/helpTOC.xml +++ b/help/helpTOC.xml @@ -2,7 +2,15 @@ - + + + + + + + + diff --git a/help/html/editing/index.html b/help/html/editing/index.html index 8ff1cf6..bcb4e94 100755 --- a/help/html/editing/index.html +++ b/help/html/editing/index.html @@ -2,17 +2,15 @@ Editing

Editing

Jalview 2.08 Enhancements - Editing can be restricted to the current - selection area. This allows the user to "Lock" the alignment either - side of the selection area. Any gap insertions or deletions will only affect - the current selection area.

In this example, if Sequence IL2RA_MACMU has gaps removed from position 98-104, - the same number of gaps will be inserted at position 116, (between M and L). -

Editing is possible via the keyboard by toggling the Cursor mode on / off with - F2. A full list of keyboard editing actions is found here. -

There are two major ways to edit alignments - in 'Normal mode', +gaps are inserted and deleted at the mouse pointer in various ways by +clicking the left mouse button and pressing a combination of either +shift and control (or the apple key on Macs) and dragging the mouse. Pressing +F2 toggles the alternative 'Cursor +mode' keyboard editing facility, where the space bar and delete +keys add and remove gaps at the current editing position. The key +strokes for both these modes are summarised in the keystrokes table.

Tip: For large alignments, deselect "Calculate -> Autocalculate Consensus" to prevent the alignment performing lengthy calculations after every edit.

diff --git a/help/html/features/annotationsFormat.html b/help/html/features/annotationsFormat.html index d890321..18d773c 100755 --- a/help/html/features/annotationsFormat.html +++ b/help/html/features/annotationsFormat.html @@ -1,47 +1,82 @@ -Annotations File Format +The Alignment Annotations File -

Alignment Annotations File Format
-
- Note: This format is primarily intended to be used for the applet, which does - not have an XML parser and where file size must be kept to a minimum to reduce - download time.

A precalculated annotations fiile can read onto an alignment from the command - line ("-annotations"), by drag and dropping the the annotations file - onto an alignment or by selecting from the File menu "Load Features / Annotations".

The File is in tab delimited format. The file must have the line JALVIEW_ANNOTATION - as an identifier. Then a block of annotations are added in the form GRAPH_TYPE - Label Values

GRAPH_TYPE can be either BAR_GRAPH, LINE_GRAPH or NO_GRAPH. The values are - per alignment column, separated by "|". Multiple content per column - can be separated with commas, Jalview will display the content if it interprates - the content as a text label, or secondary structure character (H or E)

You can optionally associate an annotation with a sequence by adding a line - SEQUENCE_REFseq_namestartIndex All Annotations after a SEQUENCE_REF will be - associated with that sequence. Use SEQUENCE_REF ALIGNMENT to cancel the associtations.

The visual graphs can be coloured or combined with other graphs, or have an - arbitrary line drawn at a certain value using the following lines.

COLOUR<tab>graph name<tab>colour
- COMBINE<tab>graph 1 name<tab>graph 2 name
- GRAPHLINE<tab>graph name<tab>value<tab>label<tab>colour

An example Annotation file may look like this:

The Alignment Annotations File

Alignment annotations can be imported onto an alignment since + version 2.08 of Jalview, via an annotations file. It is a simple + ASCII text file consisting of tab + delimited records similar to the Sequence Features File, and + introduced primarily for use with the Jalview applet.

Alignment annotations files are imported into Jalview in the +following ways:
+

from the command line
+ -annotations <Annotations filename>
Dragging an annotations file onto an alignment window
Via the "Load Features / Annotations" entry in the +File menu of an alignment window.

Annotations File Format

The File consists of lines containing an instruction followed by + tab delimited fields, and any lines starting with "#" are + ignored. The first non-commented out line of a valid Annotations file must begin with :

JALVIEW_ANNOTATION

A row of annotation is added with a line like +

GRAPH_TYPE	Label	Values

GRAPH_TYPE
This is can be either of "BAR_GRAPH", + "LINE_GRAPH" or "NO_GRAPH", defining the type of + annotation row that is being described. +
Values
This field is a series + of symbols and/or quantities separated by the pipe symbol "|", + mapped onto the columns of the alignment.
Some types of annotation + can display both text, symbols and quantities at each column, and these are + separated with commas within the pipe-delimited Value field. Jalview + will display the content if it's values are appropriate for the type + of the annotation being defined:
- BAR_GRAPH
  text + character,number
- LINE_GRAPH
  number
- NO_GRAPH
  text label,H or E for helix or strand + symbol
+

You can associate an annotation with a sequence by preceding its + definition with the line: +

SEQUENCE_REF	seq_name	[startIndex]

+All Annotations defined after a SEQUENCE_REF command will then be + associated with that sequence, and the first field in the Value + field list will (optionally) be + placed at the startIndex'th column.

Sequence associations + are turned off for subsequent annotation definitions by: +

SEQUENCE_REF	ALIGNMENT

LINE_GRAPH type annotations can be given a colour, + combined onto the same vertical axis, and have abscissa (lines of + constant value - so they are horizontal) at particular + values using the following lines (respectively): +

COLOUR	graph name	colour
+COMBINE	graph 1 name	graph 2 name
+GRAPHLINE	graph name	value	label	colour

An example Annotation file is given below:

#Comment lines follow the hash symbol
JALVIEW_ANNOTATION
SEQUENCE_REF FER1_MESCR 5
- BAR_GRAPH<tab>Bar Graph 1<tab>||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
- LINE_GRAPH<tab>Green Values<tab>1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
- LINE_GRAPH<tab>Red Values<tab>2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
- BAR_GRAPH<tab>Bar Graph<tab>2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
- NO_GRAPH<tab>Icons <tab>||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
- NO_GRAPH<tab>Purple Letters<tab>m|y|p|r|o|t|e|i|n

COLOUR<tab>Bar Graph 2<tab>blue
- COLOUR<tab>Red Values<tab>255,0,0
- COLOUR<tab>Green Values<tab>green
- COLOUR<tab>Purple Letters<tab>151,52,228
- COMBINE<tab>Green Values<tab>Red Values

GRAPHLINE<tab>Red Values<tab>2.6<tab>threshold<tab>black + BAR_GRAPH Bar Graph 1 ||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
+ LINE_GRAPH Green Values 1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
+ LINE_GRAPH Red Values 2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
+ BAR_GRAPH Bar Graph 2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
+ NO_GRAPH Icons ||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
+ NO_GRAPH Purple Letters m|y|p|r|o|t|e|i|n

COLOUR Bar Graph 2 blue
+ COLOUR Red Values 255,0,0
+ COLOUR Green Values green
+ COLOUR Purple Letters 151,52,228
+ COMBINE Green Values Red Values

GRAPHLINE Red Values 2.6 threshold black

diff --git a/help/html/features/featuresFormat.html b/help/html/features/featuresFormat.html index a97d957..77d62a7 100755 --- a/help/html/features/featuresFormat.html +++ b/help/html/features/featuresFormat.html @@ -1,38 +1,77 @@ -Features File Format +Sequence Features File +

Sequence Features File

The Sequence features file (which used to be known as the "Groups +file" prior to version 2.08) is a simple way of getting +your own sequence annotations into Jalview. It was introduced to allow +sequence features to be rendered in the Jalview applet, and so is +intentionally lightweight and minimal because the applet is often used +in situations where data file size must be kept to a minimum, and no +XML parser is available.

Features files are imported into Jalview in the following ways:
+

from the command line
+ -features <Features filename>
Dragging a features file onto an alignment window
Via the "Load Features / Annotations" entry in the +File menu of an alignment window.

Sequence Features File Format

Note: This format is primarily intended to be used for the applet, which does - not have an XML parser and where file size must be kept to a minimum to reduce - download time.

(Prior to version 2.08 known as the "Groups file")
- A precalculated Features file can read onto an alignment from the command line - ("-features"), by drag and dropping the features file onto an alignment - or by selecting from the File menu "Load Features / Annotations".

Specify the feature types first, then refer to the feature type for each sequence.

featureType<tab>colour
- description<tab>sequenceId<tab>sequenceIndex<tab>start<tab>end<tab>featureType

eg
- domain red
- metal ion-binding site 00ff00
- transit peptide 0,105,215
- chain 225,105,0
- modified residue 105,225,35
- signal peptide 0,155,165
- Your Own description here FER_CAPAA -1 3 93 domain
- Your Own description here FER_CAPAN -1 48 144 chain
- Your Own description here FER_CAPAN -1 50 140 domain
- Your Own description here FER_CAPAN -1 136 136 modified residue
- Your Own description here FER1_LYCES -1 1 47 transit peptide
- Your Own description here Q93XJ9_SOLTU -1 1 48 signal peptide
- Your Own description here Q93XJ9_SOLTU -1 49 144 chain

An additional option in Jalview 2.08 is to group features in the following - way:

STARTGROUP<tab>My feature groupA
- ....Many Feature descriptions here
- ENDGROUP<tab>My feature groupA
+

A features file is a simple ASCII text file, where each line +contains tab separated text fields. No comments are +allowed.

The first set of lines contain type definitions: +

Feature label	Feature Colour

+A feature type has a text label, and a colour (specified as a +red,green,blue 24 bit triplet either in hexadecimal (eg. 00ff00) or as comma +separated numbers (ranging from 0 to 255)). +

The remaining lines in the file are the sequence annotation +definitions, where the now defined features are attached to regions on +particular sequences, optionally with some descriptive text (displayed +in a tooltip when the mouse is near the feature on that sequence). There are two alternate ways of referring to a +sequence, either by its text ID, or its index in an associated +alignment.

+description	sequenceId	sequenceIndex	start	end	featureType

Normally, +sequence features are associated with sequences rather than +alignments, and the sequenceIndex field is given as "-1". In +order to specify a sequence by its index in a particular alignment, the +sequenceId should be given as "ID_NOT_SPECIFIED", otherwise the +sequenceId field will be used in preference to the sequenceIndex field.

+Feature annotations can be collected into named groups by prefixing +definitions with lines of the +form:

startgroup	groupname

.. and +subsequently post-fixing the group +with:endgroup groupname
Feature grouping +was introduced in version 2.08, and used to control whether a set of features +are either hidden or shown together in the sequence Feature settings +dialog box.

A complete example is shown below :

+domain	red
+metal ion-binding site	00ff00
+transit peptide	0,105,215
+chain	225,105,0
+modified residue	105,225,35
+signal peptide	0,155,165
+helix	ff0000
+strand	00ff00
+coil	cccccc
+Your Own description here	FER_CAPAA	-1	3	93	domain
+Your Own description here	FER_CAPAN	-1	48	144	chain
+Your Own description here	FER_CAPAN	-1	50	140	domain
+Your Own description here	FER_CAPAN	-1	136	136	modified residue
+Your Own description here	FER1_LYCES	-1	1	47	transit peptide
+Your Own description here	Q93XJ9_SOLTU	-1	1	48	signal peptide
+Your Own description here	Q93XJ9_SOLTU	-1	49	144	chain
+startgroup	secondarystucture
+PDB secondary structure annotation	FER1_SPIOL	-1	52	59	strand
+PDB secondary structure annotation	FER1_SPIOL	-1	74	80	helix
+endgroup	secondarystructure
+

diff --git a/help/html/features/search.html b/help/html/features/search.html index 21126a1..c1ad561 100755 --- a/help/html/features/search.html +++ b/help/html/features/search.html @@ -18,9 +18,6 @@ td { the alignment window view to show it, and "Find all" highlights all matches for a pattern. The "New Feature" is a quick way to highlight and group residues matching the specified search pattern throughout the alignment. - If "New Feature" is selected, the feature can be given a name from - a popup input box. Use the "Feature Settings" under the "View" - menu to change the visibility and colour of the new sequence feature.

The search uses regular expressions. (understands a mixture of posix and perl style regex - see below for a summary)
To quickly clear the current selection, press the "Escape" key.

Creating Features from Search Results

+ If "New Feature" is selected, the feature can be given a name from + a popup input box. Use the "Feature Settings" under the "View" + menu to change the visibility and colour of the new sequence feature.

A quick Regular Expression Guide

A regular expression is not just a simple text query - although it can be used like one, the query is not parsed literally, but diff --git a/help/html/features/seqfeatures.html b/help/html/features/seqfeatures.html index 07b36e1..2a57e63 100755 --- a/help/html/features/seqfeatures.html +++ b/help/html/features/seqfeatures.html @@ -1,19 +1,30 @@ Sequence Features +

Sequence Features

Jalview can colour parts of a sequence based on the presence of +sequence features - which may be retrieved from database records (such +as Uniprot), the result of sequence motif +searches or simply read from a sequence features file.

View→Fetch Sequence Features

When this option is selected, sequence features extracted from the Uniprot record for each sequence are displayed on the alignment.

Jalview will attempt to retrieve sequence features from Uniprot files using - the EBI dbFetch web service using the given sequence names. A 100% match with - the Uniprot record is required to view the Sequence Features.

+ the EBI dbFetch web service using the given sequence names (or + Uniprot ID, if available). A 100% match with + the Uniprot record is required for Uniprot features to be view on a sequence.

More information about the feature is given in a tooltip, which is viewed by moving the mouse pointer over a sequence feature. The description associated with the feature will then be displayed in a small label near the pointer.

View→Show Sequence Features

Select whether to view the sequence features added to this alignment or not.

Toggle the display of sequence features in this alignment.

View→Feature Settings... -

Once sequence features have been loaded onto an alignment features can be hidden +

Once sequence features have been loaded, their display can be fully + controlled using the alignment window's Feature Settings dialog box + :

+ +

features can be hidden or have their rendering priority changed using the Feature Settings dialog. This displays all the features loaded, the colour and whether to display the feature or not. You can easily change the colour by clicking the colour box.
diff --git a/help/html/whatsNew.html b/help/html/whatsNew.html index 7fa9806..b5f5c78 100755 --- a/help/html/whatsNew.html +++ b/help/html/whatsNew.html @@ -8,26 +8,47 @@

Keyboard editing - press F2 to toggle cursor mode On / Off. For a full list of keyboard controls, look here.

Create sequence features from searches. - Previously results from searches were added as alignment positions, which was - wrong. Now the search results are saved as sequence features and their visibility - and colour can be modified using the Sequence - Feature Settings window.

Precalculated annotations can be loaded onto alignments. The Annotation - File format is a tab delimited set of values.

Features file allows grouping of - features. The Sequence Feature Settings - window then makes it very easy to set the visibility of groups of features. -

Annotation Colouring - scheme added. A new colour scheme which colours columns on a per-column value.

Smooth fonts off by default - faster rendering. Toggle on / off from the View - menu, or can be set in Preferences.

Choose to toggle Autocalculate Consensus On/Off from the Calculate menu.
+ Previously, the regions of sequences highlighted as the result of + searches were added as new regions in the alignment. Now, the sequence region + selected by a search can be used to define named sequences features + attached to the sequence, rather than the alignment. +

Sequence feature display and rendering has also been enhanced, with + the addition of sequence feature groups (which can be used to show + or hide a set of feature types en masse) and user defined + feature colours as well as transparency controls, using the Sequence Feature Settings + window. The Features file + has also been extended to accomodate these enhancements.

Alignment annotation and colouring is also considerably + enhanced. Precalculated symbolic and quantitative annotations (text labels, + secondary structure symbols and multiple scalar graphs) can now be + loaded onto alignments via the Annotation + File. Additionally, the Annotation + Colouring dialog box allows an alignment to be coloured based on + any of the graphed quantities with which it is annotated.

Rendering speed has been improved by disabling anti-aliasing via + the Smooth Fonts + option in the View + menu (its default set in Preferences). In addition, response + times when editing alignments can be reduced by turning off the automatic + calculation of amino acid property Consensus (which has been + reintroduced to the Calculate menu as Autocalculate Consensus).

Issues Resolved

Drag & Drop fixed on Linux

Jalview Archive file faster to load/save, sequence descriptions saved.
-

Drag & Drop now works on common Linux desktops (at least KDE +and Gnome)
Jalview XML Archive Input/Output is now faster (using an +internal Jalview schema), and sequence description strings are now +preserved in the archive.
Jalview can now correctly read and write MODELLER style +PIR description lines for proteins with a PDB reference. +

See the Release History page for details of all new features and resolved issues.

-- 1.7.10.2