skip to main content
Roche logo
1. GS Amplicon Variant Analyzer Application : 1.3 The Project Tab : 1.3.1 The “Project Tree” Sub-Tabs
1.3.1
The “Project Tree” Sub-Tabs
In a new Project, each “Project Tree” tab contains a single folder representing the Project itself. Right-clicking on this folder opens a contextual menu that includes a “Properties” option; this opens a “Project Properties” window in which you can enter or edit the name and description of the Project. You cannot modify the location of the Project from within the Project. (Note that changing the name of the Project this way will NOT also change the name of the folder that contains it, in your file-system, so be aware of the possibility of mismatch between the Project name and its file-system location.)
The “tree” Project views provide a convenient way to add, remove and organize (“associate”) the various elements that compose a Project, and to navigate it afterwards. There are 5 ways to construct or otherwise manipulate a tree.
•
You can use the buttons located to the left of the window’s left panel
•
You can right-click on an existing element in a Project Tree, which opens a contextual menu that includes the same actions of the buttons
•
You can drag elements from the Definition Tables on the right panel of the tab, to the appropriate element in a tree view (see section 1.3.2)
•
As a special case, the associations between Amplicons or Variants and their Reference Sequences can also be specified in the Definition Tables of these elements, and will then appear in the References Tree.
•
As another special case, when MIDs and Multiplexers are used, editing the associations between MIDs and Samples for a given Multiplexer (see section 1.3.2.7.3) may cause any Amplicons previously associated with Samples using that Multiplexer to shift to new positions in the tree, to reflect associations to the Multiplexer’s new Samples.
The functions of the five action buttons to the left of the Tree panel that are applicable to trees are described below. Right-clicking on an element in a tree opens a contextual menu that contains the same actions [plus, if you right-click on a Sample-Amplicon pair, the “Global Align” action (described in section 1.6.1)].
 
Button
Name – Description
Add – allows you to create a new element in the tree (except for Read Data Sets; see the “Import Data” button, below), as a branch under the element selected at the time you clicked, automatically creating an association between the two. This action is contextual, i.e. the type of element you can create with this button depends on which “tree” you are in and which type of element is selected at the time you click the button. When the context allows for the creation of more than one type of element, a contextual menu opens to let you choose; if there is only one possibility, the new element and association are created directly.
Remove from Project – deletes the element selected from the Project altogether. Of course, this severs all the associations it may have had with other elements. If the association is based on a definitional relationship then those other elements are deleted as well (specifically, deleting a Reference Sequence will delete any Amplicons or Variants that are defined based on their association with the Reference Sequence). If there are related elements in purely associational relationships, then it does NOT delete those other elements, even if they were in a lower branch of the tree in the particular tree view from which the operation is carried out. For example, if you remove a Sample from the Sample Tree, all Amplicons associated with that Sample remain in the Project (even if they are no longer associated with any Sample at all) and keep their full definition and all other associations they may have. In all cases, a warning message is displayed to indicate exactly what elements or associations will be removed from the project as a result of the removal action.
Remove association and remain in project – severs the association between the element selected at the time you click the button and the element above it in the tree, but leaves all elements otherwise fully defined in the Project. This button is contextual as well, as not all links can be severed. For example, you cannot sever the link between a Sample and an Amplicon in the References Tree (though you can in the Read Data and Samples Trees).
Select Amplicons associated with item – provides the ability to select, within the Definition Table, all the Amplicons associated with an item in the tree, based on the relationships of that item that exist in the tree.
For example, selecting a Reference, a Sample, or a Multiplexer in one of the trees, and clicking this button causes the Definitions Table panel to switch to the Amplicons Definition Table sub-tab. Within that Amplicon table, the subset of the Amplicons that are associated with the Reference, Sample, or Multiplexer used to trigger the operation will be multi-selected. This multi-selection in the Table can be dragged to another valid tree location by holding down the control key before left-clicking on one of the members of the multi-selection with the mouse. (Note: The Amplicon on which you clicked will initially become deselected, but it will be added back to the selection at the moment the selection gets dragged.)
The primary utility of this button is that it allows complex Sample-Amplicon or Multiplexer-Amplicon relationships to be cloned to another Sample or Multiplexer with a single drag-and-drop operation, rather than making many individual manual selections, drags, and drops to re-create the whole set. See also section 1.3.2 for information on how dragged Amplicons can “trickle” down a Tree.
Import data – allows you to either add Read Data Set(s) to the Project, or to import a file containing specifications to create any of the other project entities that have a dedicated tab in the Tree or Definition Table panel of the GUI (References, Amplicons, Samples, Variants, MIDs, Multiplexers). The “Import data” button operates on the item type which has focus when the button is clicked, as indicated by the rectangular blue outline (Figure 1‑8). More details on this function are provided below.
 
Clicking the “Import data” button when the ReadData Tree or Table has focus opens a “Choose Read Data” window from which you can browse your file-system to select the Read Data Set(s) of interest. This can be:
•
The Data Processing (‘D_’) folder of a sequencing Run: select ‘454 Data Processing Folders’ in the ‘Files of Type’ drop down menu, at the bottom of the window; (Figure 1‑9A; Data Processing directories are marked by a special icon: ).
•
Individual SFF file(s): select ‘454 SFF Files’ in the ‘Files of Type’ drop down menu (Figure 1‑9B).
Note that the data set(s) must comprise reads from an Amplicon library(ies) to be useable in the AVA software.
A
B
Figure 1‑9: The Choose Read Data window showing (A) an example with a Data Processing Directory selected, and (B) an example with some SFF files selected.
When the selection is made and you click the “OK” button to accept it, an “Import Read Data” window opens (Figure 1‑10). In this window, you can:
•
select the exact file(s) to import (e.g. from the list of SFF files corresponding to the sequencing Run, if a Data Processing (‘D_’) folder was selected in the previous step) by clicking the “Import all” or the appropriate check box(es) to the left of the Read Data Set name(s);
•
determine whether to import full copies of the Read Data Set(s) into the Project, or only symbolic links to the Set(s) selected, by clicking the “Link all” or the appropriate check box(es) to the right of the Read Data Set name(s) (see first Note below);
•
incorporate the Read Data Set(s) you are importing into an existing Read Group or into a new one (which you can name in the appropriate field, in this window) (see second Note below).
Figure 1‑10: The Import Read Data window
 
•
All the files related to an Amplicon Project are collected in a single folder, at a location determined by the user at the time the Project was created (or as modified thereafter). To save file transfer time and disk space, you can choose to import only a symbolic link to the data file(s) rather than the files themselves. However, be aware that if you do this and then the file that is the target of the link is moved, the AVA software will not be able to compute (or re-compute) the Project.
•
Read Groups are distinct entities (which can be created at the root node of the Read Data Tree, using the “Add” button), and although you can rename an existing Read Group to match the name of another pre-existing Read Group, this will not cause the Read Data Sets to be merged into the same group.
 
Clicking the “Import data” button, when a non-Read Data Tree or Table has focus, opens a “Choose File to Import” window from which you can browse your file-system to select a tab- or comma-delimited file containing definition information for the selected entity type (Figure 1-11). The content of the file being imported should be of the same format as one that would be provided as the “-file” option for the AVA Command Line Interface (CLI) “create” command for that entity (“create entity -file providedFile”, see section 3.4.4).
Figure 1-11: A "Choose Reference Sequences File to Import" window has been opened by clicking on the “Import data” button. The Tree view is displaying Samples and the Table view is displaying references. The import window label mentions “Reference Sequences” rather than Samples because the References Table has focus, as indicated by the blue outline.
When a file is imported, it is subjected to the same error checking as if it was being provided to the CLI. The header line should contain field names that are appropriate for the entity being created and the file should only be used to create new entities. If the file uses unknown fields in the header, or attempts to create an entity that already exists, an error window will be generated. If no errors are encountered, the newly created entities will appear in the appropriate Tree and Table. The newly created entities are not permanent until the project gets saved.
 
•
Importing the incorrect file type: Because the “Import data” button is context-sensitive, care should be taken to make sure that the window that pops up is for the expected object by checking the title of the window. Some entities, such as the Sample, have header fields that are not unique compared to other entities, so it is possible to select a file for that entity by accident without triggering any error. In Figure 1-11, for example, suppose the intent was to import a Sample file, and the blue focus outline and window title indicating Reference import were ignored, and a Sample file was chosen. In such a case, the Samples would end up being created as incomplete References without triggering any warning or error.
•
Partial file imports: If an import operation is terminated due to an attempt to create an entity that already exists or some other error condition (e.g. attempting to create a Variant while referring to a non-existent Reference), the import halts at the point where the error is encountered. Any entities created prior to the error will have been successfully added to the project, and any entities after the error are never encountered, resulting in a partial upload. The simplest way to back out of such a situation is to reopen the project without saving the results of the partial import. This provides an opportunity for a corrected file to be re-imported without running into conflicts with partially imported files.
 
•
Files can only be imported for project entities that have a dedicated tab in the Tree or Definition Table panel of the GUI (References, Amplicons, Samples, Variants, MIDs, Multiplexers). Entities such as Read Data Groups and MID Groups can not be imported in this manner; they must be created using the GUI or the CLI.
•
Since the files to be loaded must be compatible with the CLI “create” command, they can only be used to create basic versions of more complex entities such as Multiplexers. The only associations that can be created are the ones inherent to the creation command for the entity, so an Amplicon can be created that is associated with a Reference because “-reference” is one of the keywords available to the “create amplicon” command. A Multiplexer can be created and assigned an annotation and an encoding, but the association of MIDs to the multiplexer and the associations of Samples to MID combinations are not accessible via the create command and those associations must be established via the GUI or via the “associate” command using the CLI (3.4.1).
 
The “Add” action above will only create empty Project elements with generic names. You can re-name an element from either a Project Tree or a Definition Table. In a Project Tree, click twice with a slight pause between the clicks to activate an editor directly on the name of the element in the tree. (Note that you can also change the name of the Project this way but that this will NOT also change the name of the folder that contains it, in your file-system, so be aware of the possibility of mismatch between the Project name and its file-system location.) Once elements are created (and possibly named), they can be fully defined in the corresponding “Definition Table” tab for the element type (see section 1.3.2). The approach of creating Project elements in a Project Tree view before fully defining them is convenient because it allows the user to set the structure of the Project up-front, possibly even before any sequencing reads are imported; see the documentation on “Samples” (sections 1.1.1.6, 1.3.1.3, 1.3.2.4, and 2.6.1) for an explanation of the usefulness (and complexity) of this.
 
For large Projects, especially when large amounts of data need to be imported into, exported from, or automated within a Project, the Command Line Interface (CLI) of the AVA software may be more appropriate than the Graphical User’s Interface (GUI) described in the present section. See section 3 for a full description of the CLI, the language that was developed for it, and all the commands it includes.
 
1.3.1.1
The References Tree
The References Tree sub-tab shows the Reference Sequences as the main limbs of the Project Tree, with the Amplicons and Variants associated with each Reference Sequence as the next branching level, and the Samples associated with each Amplicon in the third level (Figure 1‑12). This tree is useful to easily visualize all the Amplicons and defined Variants that are associated with each Reference Sequence, and all the Samples that will report on each Amplicon. You can also use this tree to populate the Global Align tab with the multi-alignment of the reads of any Sample-Amplicon pair you have created in your Project that has had computations run for it (see section 1.6.1).
Figure 1‑12: The References Tree sub-tab of the Project Tab’s left-hand panel
 
1.3.1.2
The Read Data Tree
The Read Data Tree sub-tab shows the Read Groups / Read Data Sets as the main limbs of the Project Tree, with the Samples associated to each Read Data Set as the next branching level, and the Amplicons associated to each Sample in the last level (Figure 1‑13). If the libraries were prepared with MIDs and Multiplexers are defined in the Project, the Multiplexers are displayed in this Tree, between the Read Data Sets and the Samples. (Read Groups are only a means to associate several Read Data Sets together, e.g. the various PicoTiterPlate Device regions of a GS FLX+ sequencing Run, for better ease of handling.)
You can use this tree to populate the Global Align tab with the multi-alignment of the reads of any Sample-Amplicon pair you have created in your Project that has had computations run for it (see section 1.6.1). The principal use of the Read Data Tree, however, is to establish which Read Data sets supply the Amplicon reads to particular Samples. Thus, rather than merely establishing that reads from some Amplicon generally exist in the Project for a given Sample (as on the Sample Tree; see section 1.3.1.3), the Read Data Tree represents specifically which Read Data Set supplies those reads (and which Multiplexer defines the read assignments to the Samples, if applicable).
 
The AVA software will not allow you to associate a given Amplicon with more than one Sample or Multiplexer within the branch of a Read Data Set. This is important because the demultiplexing phase of computation (see section 1.4) depends on the uniqueness of such associations.
 
False Amplicon associations in the Read Data Tree:
 
Be careful to limit the Amplicons “lower” branches of this tree to those to which the specific Read Data Set truly contributes. False Sample-Amplicon associations could easily creep into a Read Data Set branch of your Project set up when you use the dragging method (section 1.3.2) to associate Samples with Read Data Sets; while convenient, this method brings the Sample with all its associated Amplicons into the Read Data Tree (unless any of these Amplicons are already associated with another Sample in this branch of the tree; see Note above). Similarly, if you drag one or more Amplicons to the root node or to a Read Group node in the Read Data Tree, they will get associated with every eligible Sample under the receiving node (see section 1.3.2). After you create such associations, therefore, make sure to “prune” the tree of any Amplicons that don’t belong to any given Read Data Set branch or to any given Sample, by using the “Remove association and remain in project” button or its equivalent right-click contextual menu option. (Note that deleting an association between a Sample and an Amplicon within the Read Data Tree has no effect on the association between those entities in the Samples Tree; see section 1.3.1.3.)
 
This is important because the Read Data Tree provides the specific Run information for each of the Sample-Amplicon pairs used by the AVA software to determine which read sequences (Amplicons) to look for in each Read Data Set at the time of computation (and to which Sample each read belongs). The presence of false Amplicon associations in this tree would not only needlessly lengthen the Trimming step computing time (as the software would search all the reads for primer pairs that are, in fact, not present), but it could even result in the assignment of a read to a non-existent Amplicon should a spurious match occur.
 
Note that the Samples Tree, by comparison, represents all the Sample-Amplicon associations relevant to the Project design, whether or not any Read Data Set(s) containing such reads have (yet) been imported into the Project (see section 1.3.1.3): all Sample-Amplicon associations seen in any branch of the Read Data Tree are also seen in the Samples Tree; but Sample-Amplicon associations present in the Samples Tree do not (or should not) necessarily be present in any given branch of the Read Data Tree.
 
•
Dragging a Sample from its Definition Table onto a Read Data Tree node that already contains this Sample will not create a duplicate “Sample” sub-branch on the tree. However if, at the time of this dragging action, the Sample has Amplicon associations that are not displayed in the tree node, these associations will be added to the branch (unless any of these Amplicons are already associated with another Sample in this branch of the tree; see the first Note above). As explained above, you should then “prune” the Read Data Tree of any false Read Data-Amplicon associations that may have been created.
•
A Sample must have at least one Amplicon associated with it to be associated with a Read Data. This is because, as seen above, the association of Amplicons to Read Data is intrinsic to this tree, just as the Sample-Read Data is. One can view the information contained in this tree as Read Data-Sample-Amplicon association triads.
•
For Amplicon libraries created with MIDs, the method of dragging a Sample with its associated Amplicons to a Read Data Tree node is NOT used. Rather, a Multiplexer is first associated with the Read Data Tree node, and then one or more Amplicons are dragged to the Multiplexer node. All Sample associations (to Read Data Sets and to Amplicons) are made indirectly, as defined by the Multiplexer i.e., using the MIDs.
 
Figure 1‑13: The Read Data Tree sub-tab of the Project Tab’s left-hand panel. In this example we see that Sample1 has reads for Amplicon EGFR_20_3 which can be found in Read Data Set DGVS90J01. Sample5 also has reads for EGFR_20_3, but those are found in a different Read Data Set (DGVS90J03), which is allowed. Read Data Set DGVS90J04 has been imported into the Project, but no Sample-Amplicon pairs have yet been associated with it. Hence, DGVS90J04 would be excluded from Computations if carried out at this point, since the AVA software would not know to which Samples and Amplicons its reads belong (see section 1.4).
 
1.3.1.3
The Samples Tree
The Samples Tree sub-tab shows the Samples as the main limbs of the Project Tree, with the Amplicons associated to each Sample as the next branching level, and the Read Group / Read Data Sets associated to each Amplicon in the third/fourth level (Figure 1‑14). Since this tree representation lists together all the Amplicons associated with each Sample, it is useful to navigate the results for a given Sample, irrespective of which Read Data Set supplied the reads for each Amplicon. You can use it to design your project, showing not only Sample-Amplicon pairs for which Read Data Set(s) already exists in your Project (shown in the Read Data Tree), but also any other Sample-Amplicon pairs that you expect to see over the course of the entire Project, irrespective of whether the Read Data has yet been imported into the Project (or even yet exists). As such, this tree does not have the functional constraints of the Read Data Tree which provides the specific Run information for each of the Sample-Amplicon pairs, to be used for computation by the AVA software (see section 1.3.1.2). You can also use this tree to populate the Global Align tab with the multi-alignment of the reads of any Sample-Amplicon pair you have created in your Project that has had computations run for it (see section 1.6.1).
Figure 1‑14: The Samples Tree sub-tab of the Project Tab’s left-hand panel
 
1.3.1.4
The MIDs Tree
This is the simplest of the Tree sub-tabs, as it simply lists the MIDs that are defined in the Project, with the optional MID Groups if applicable (Figure 1‑15).
Figure 1‑15: The MIDs Tree sub-tab of the Project Tab’s left-hand panel