The Future of Scientific Software. BioTuple v1.0 User Guide

Transcription

1 The Future of Scientific Software BioTuple v1.0 User Guide

2 Copyright ichemlabs, LLC. All Rights Reserved. No part of this document may be reproduced or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of ichemlabs. BioTuple are trademarks of ichemlabs, LLC. All other trademarks are the property of their respective holders.

3 Contents CONTENTS... 3 CHAPTER 1: INTRODUCTION... 6 ABOUT BIOTUPLE... 6 ABOUT THIS MANUAL... 6 Typographical Conventions... 6 How to Use This Manual... 6 ADDITIONAL INFORMATION... 7 INSTALLATION AND SYSTEM REQUIREMENTS... 7 Microsoft Windows System Requirements... 7 MULTIPLE USERS ON A SINGLE COMPUTER... 7 Windows... 7 Mac OS X... 8 Linux... 8 BIOTUPLE FOLDERS... 8 Installation Folder... 8 Settings Folder... 9 PROGRAM ACTIVATION... 9 RESTRICTED USE VERSIONS... 9 Free Trial... 9 Student Version... 9 CONNECTION ISSUES... 9 Firewall Issues Proxy Issues ATTRIBUTIONS CHAPTER 2: BIOTUPLE BASICS THE BIOTUPLE GRAPHICAL USER INTERFACE Center Panel Scrollbars Tab Tray View Bar Application Menu Bar BioTuple Menu (Mac OS X Only) File Menu Edit Menu View Menu Sequence Menu Window Menu Purchase Menu Help Menu General Toolbar Files Toolbar Opening a document File Chooser... 22

4 Discard Recent Changes to a Document Saving Documents Autosaving Reversing Actions Selected Components Sequence list Sequence List Toolbar CHAPTER 3: EDIT VIEW THE EDIT TOOLBAR SEQUENCE TRANSFORMATIONS KEYBOARD USAGE ADDING SEQUENCES CHAPTER 4: ANNOTATE VIEW ANNOTATE TOOLBAR ORF SCAN THE FEATURE VIEW CHAPTER 5: CALCULATE VIEW CHAPTER 6: PROTEIN VIEW PROTEIN TOOLBAR CHAPTER 7: ALIGNMENT VIEW ALIGNMENT TOOLBAR PREPARING FOR AN ALIGNMENT Adding/removing sequences setting parameters for an alignment PERFORMING AN ALIGNMENT ANALYZING A COMPLETED ALIGNMENT Pairwise Alignment Multiple Sequence Alginment alignment information CHAPTER 8: STRUCTURE VIEW Importing PDB Files CHAPTER 9: SHARING INFORMATION OVERVIEW THE SYSTEM CLIPBOARD Clipboard Settings COPYING DATA TO OTHER APPLICATIONS Using the Copy Function Using the Copy As Function PASTING DATA FROM OTHER APPLICATIONS Where Content is Pasted BIOLOGICAL FORMAT COMPATIBILITY APPENDIX A: MANAGING BIOTUPLE... 40

5 OVERVIEW APPLICATION AND FILE ICONS UPDATING BIOTUPLE Windows Administrator Privileges Skipping Updates Purchasing Upgrades MOVING YOUR ACTIVATED COPY TO A NEW COMPUTER PREPARING FOR A SYSTEM RESTORE APPENDIX B: BIOLOGICAL FILE TYPES OVERVIEW ADHERENCE TO THIRD PARTY SPECIFICATIONS SUPPORTED BIOLOGICAL FILE TYPES FILE ANNOTATIONS REFERENCES APPENDIX C: TECHNICAL SUPPORT WHEN TO CONTACT CUSTOMER SERVICE HOW TO CONTACT CUSTOMER SERVICE FEATURE REQUESTS FOLLOWING BIOTUPLE DEVELOPMENT TROUBLESHOOTING Windows Mac OS X PERFORMANCE IMPROVEMENTS Hardware... 46

6 CHAPTER 1: INTRODUCTION ABOUT BIOTUPLE BioTuple is a software tool for editing, analyzing, and visualizing DNA, RNA, and protein sequences. BioTuple is cross platform, (Windows, Mac OS X, Linux) and can easily handle common file formats including FASTA, GenBank, PDB. Using external tools such as NCBI s databases, BLAST, and RCSB are available for easy importing sequences, alignments, and structures. ABOUT THIS MANUAL This User Guide contains information for the BioTuple application for the Windows, Mac OS X and Linux operating systems. It assumes you are familiar with the basics of your operating system. If necessary, please review your operating system manual before using BioTuple. TYPOGRAPHICAL CONVENTIONS The following typographical conventions are used in this manual: Item Convention Example Toolbar buttons, menu items, keys Bold Select Undo from the Edit menu Figure/Table captions, Folders Italicize Figure 1.4: The Doodle Board User inputs Monospace Series of menu items in a specific order Vertical bar File New means from the File dropdown menu choose New Important additional information Caution! / Warning! HOW TO USE THIS MANUAL It is not necessary to read this entire manual before proceeding to use BioTuple; however, it is recommended that you skim the table of contents (Contents at a Glance) and read Chapter 1 (Introduction). Once you have the program installed, read Chapter 2 (BioTuple Basics). Subsequent chapters can be consulted as questions arise during use of the program. This user s guide can be found by clicking on Help in the toolbar at the top of the program screen.

7 ADDITIONAL INFORMATION Additional information about BioTuple and its use can be found by following any of the links in the table below. BioTuple Support Pages ichemlabs Customer Support ichemlabs Website INSTALLATION AND SYSTEM REQUIREMENTS MICROSOFT WINDOWS SYSTEM REQUIREMENTS Windows Vista, 7, or 8+ A minimum of 1GB of memory. The Windows BioTuple distribution works with both 32 and 64-bit Windows. If installed on 64-bit Windows, it will install as a 64-bit application, and will default to using the 64-bit Java Runtime Environment if both 32 and 64-bit JREs are installed. Macintosh OS X Requirements Mac OS X (Snow Leopard, Lion, Mountain Lion or Mavericks). A minimum of 1GB of memory. Linux Requirements Any version of Linux (we test with Mint, Fedora, Debian and OpenSUSE Linux). Any GUI, although we recommend and test with GNOME. A minimum of 1GB of memory. MULTIPLE USERS ON A SINGLE COMPUTER Several users can set up accounts in BioTuple on a single computer. All preferences and settings files are user-specific; each user may save their own preferences. To create an account each user must have an activation code. Instructions for installing BioTuple for multiple users are operating system dependent and specifics for each operating system are given in the following subsections. WINDOWS During the installation, keep the install folder in C:\Program Files\. All users will be able to execute BioTuple from within this folder. There will be periodic updates to BioTuple. For Windows BioTuple requires administrator privileges to update. Updates are installed only once on a given computer; all users then have access to the updated program.

8 MAC OS X During the installation, drag the BioTuple folder to the /Applications folder as instructed. All users will be able to execute BioTuple from within this folder. There will be periodic updates to BioTuple. Only superusers are able to update BioTuple. Updates are installed only once on a given computer; all users then have access to the updated program. LINUX Run the Linux BIN in a folder that all users have rights to execute binaries from. After the installation, verify that all users that will be using BioTuple have the necessary permissions to do so. There will be periodic updates to BioTuple. You may want to restrict write privileges to the BioTuple installation folder to a single user. This user will then need to update BioTuple as root on the computer. This only needs to be done once for the computer, and all users will then have access to the updated program. BIOTUPLE FOLDERS There are two folders that the BioTuple application uses: the main BioTuple installation folder and the BioTupleSetting folder. INSTALLATION FOLDER The contents of the main BioTuple installation folder are specified in the table below: Name Type Description of Contents BioTuple Application Program BioTuple.exe on Windows, BioTuple.app on Mac OS X, and the BioTuple shell script on Linux Config directory Folder Various configuration files, such as proxy.config, for setting BioTuple to use your proxy. It also contains the site license configuration file for site licenses. docs directory Folder Documentation, such as this user guide. external directory Folder Required packages that BioTuple needs to start up and run properly. Any licenses associated with these packages are also provided. resources directory Folder Native application icon images and other resources such as the auto-updater, and native plugins BioTuple.jar File Executable java jar of BioTuple. DO NOT REMOVE THIS FILE! This jar is not present in the Mac OS X distribution of BioTuple. BioTuple.ini File Contains parameters for the Java virtual machine. Only present in the Windows distribution of BioTuple.

9 Do not remove or alter the contents of the BioTuple installation folder or unexpected behavior may occur. To move the application, you must move the entire BioTuple folder. SETTINGS FOLDER The BioTupleSettings folder can be found in the operating system s standard Documents folder. The location of the standard operating system Documents folder for the different platforms on which BioTuple runs are indicated below: Windows Vista/7/8+ Mac OS X Linux PROGRAM ACTIVATION C:\Users\[username]\My Documents /Users/[username]/Documents /Home/[username]/Documents Activation occurs when a purchased activation code is used to associate a license with the BioTuple application for a given user account. Activation is achieved in one of two ways: (1) the activation code is entered in the activation screen of a newly purchased or free trial copy of BioTuple, or (2) the user clicks on the Activate BioTuple menu item in the Purchase menu while a trial is active. The activation code may be manually typed into the activation form or copied and pasted (in its entirety) from the receipt into the form. Once activated with a purchased license, all restrictions from the trial are removed. Activation requires an active Internet connection. Our server is sent the activation code, which is validated and grants permission to create the license file. RESTRICTED USE VERSIONS FREE TRIAL A free trial may be initiated by clicking the Free Trial button on the activation screen when BioTuple is opened. Trials will remain active for 14 days and cannot be renewed. Free trials are subject to the following restrictions: INSERT HERE STUDENT VERSION The student version of BioTuple is subject to the following restrictions: INSERT HERE CONNECTION ISSUES

10 Connectivity issues may arise during activation. These are most likely to occur in corporate environments and are usually related to the firewall or the proxy server. FIREWALL ISSUES If your firewall blocks Internet connections from Java applications, then BioTuple will not be allowed to connect to the internet. An administrator should set up a special exception to allow BioTuple to connect to the Internet, at least for activation. PROXY ISSUES If you use a proxy to access the Internet, BioTuple will use the default system proxy information to connect to the internet. If that fails, then you will need to manually define the proxy settings in the proxy.config file that can be found in the config folder in the BioTuple installation folder. ATTRIBUTIONS Attribution of graphics and output to BioTuple

11 CHAPTER 2: BIOTUPLE BASICS THE BIOTUPLE GRAPHICAL USER INTERFACE Although the Windows, Mac OS X and Linux versions of the BioTuple graphical user interface (GUI) differ slightly, the main elements of the GUI are consistent across platforms. The common elements of the GUI are shown in Figure 2.1 below. Figure 2.1: BioTuple Graphical User Interface BioTuple s functions are accessed through interaction with several types of components as indicated in Table 2.1 below. Table 2.1: Elements of BioTuple GUI Component Center Panel View Bar Menus Toolbars Sequence List Description The main window where sequence components are added Allows switching between functionality of the Center Panel Core application functions Quickly access functions List of sequences in the current file with metadata

12 CENTER PANEL The Center Panel is the main window and contains all of the sequences you create and edit, as well as components to help visualize your sequence. The Center Panel is populated with different components depending on which view is currently selected. Each view will be explained later in this document. Scrollbars Figure 2.1: An Empty Center Panel Scrollbars will appear to the right of the document if the height of the sequences in the document are too large to fit on the Center Panel You can click and drag the scroll bars to move up and down the Center Panel. You can also use the mouse scroll gesture to change the perspective. Tab Tray The Center Panel stores the current state of the program and organizes it into documents that can be individually saved as files. Each document has a corresponding tab, located at the bottom of the Center Panel in the tab tray. When a tab is pressed, the corresponding document will be selected and viewed. This allows you to manage a large number of files at once, without having to manage a large number of windows.

13 The number of tabs present in the tab tray will change depending on how many documents are open. If only a single document is present, then only one tab is displayed and will be selected. Selected tabs are brighter and shown popped forward (see Figure 2.3a). When multiple documents are open, multiple tabs will be displayed in the tab tray. The tab corresponding to the currently selected document will appear brighter and forward of the other tabs (see Figure 2.3b). Figure 2.3a: Single Tab Figure 2.3b: Multiple Tabs If there are more tabs than can fit in the tab tray not all the tabs will be displayed in the tray. Only the most recently viewed tabs will be displayed. Two right-oriented chevrons and a number are displayed to the right of the last tab to notify you that there are undisplayed tabs (see Figure 2.4a). Click on the chevrons and number to open a popup menu that lists the undisplayed tabs (see Figure 2.4b). Click on an item in the list to select that document. Figure 2.4a: Single Undisplayed Tab Figure 2.4b: List of Undisplayed Tabs The name of the file is displayed on the tab. If the name is too long, it may be cropped and appended with.... You may also see a '*' and/or '^' displayed before a file name in a tab. The '*' is a reminder that the file has been changed since the last save, and the '^' marks it as an online file. Tab specific functions that can be accessed by right-clicking on any given tab are: Close - Close the current tab. This option is only enabled if multiple tabs are present. Close Others - Close the other tabs, but leave the current one open. This option is only enabled if multiple tabs are present. New Document - Create a new document and tab. Restore - If the corresponding document was created by opening a file, then this function will be enabled, allowing you to undo all of your changes and reload the file. VIEW BAR The view bar contains buttons that allow the user to select what the functionality of the Center Panel will be. Each view has a dedicated chapter to explain what functions can be performed, but as an overview: Edit: Compose sequences and perform translations or transcriptions Annotate: Feature selection and orf scanning Calc: Sequence properties and measurements Protein: Visualization of protein reading frames Align: Perform and qualify pairwise and multiple sequence alignments

14 Structure: Visualize the 3D structure of a sequence APPLICATION MENU BAR Menus are located on the top of the BioTuple application. On Mac OS X, the BioTuple menu bar is displayed in the screen menu bar. For menu item keyboard shortcuts, consult the KeyboardShortcuts.pdf document in the docs folder in the BioTuple installation folder. There are 6 menus in the menu bar (7 on Mac OS X), not including the Purchase menu that is present during the free trial: BioTuple - This is a Mac OS X specific menu bar and contains access to several Mac OS X specific tasks as well as the About, Preferences and Quit menu items. File - This menu handles all input and output of data, file specific functions such as Annotations..., and the Quit menu item is located here on non-mac OS X platforms. Edit - Standard global document functions are located here including Cut, Copy and Paste. View - Functions for changing how documents are shown are located here as well as access to the elemental and biological data provided with BioTuple. The dynamic periodic table is also accessible through this menu. View - Menu items for showing supplemental information such as monomer data Sequence - Contains all functions related to editing and analyzing sequences. Window - Manage your workspace and the entire BioTuple application window. Purchase - This menu is only present during the free trial and provides functions for purchasing and activating licenses for BioTuple. Help - This menu contains several functions to access this user guide, list references, contact customer service and other common help items.

15 BioTuple Menu (Mac OS X Only) This is a Mac OS X specific menu bar and provides access to several Mac OS X specific tasks as well as the About, Preferences and Quit menu items. About BioTuple - Display information about BioTuple, your activation code and your license expiration. This menu item is in the Help menu on Windows and Linux. Preferences... - Open the Preferences window to edit BioTuple preferences. Services - Standard Mac OS X submenu that will likely be empty. Hide BioTuple - Hide the BioTuple application. Hide Others - Hide other applications. Show All - Show all hidden applications. Quit BioTuple - Quit the BioTuple application.

16 File Menu New - Add a new blank document to the Center Panel. Open - Open a recognized biological file that you locate with a file chooser. Open Recent - The 10 most recently opened biological files are listed here. Click a file to open it. Import - Add the sequences from an existing recognized biological file to the current document that you locate with a file chooser. Import From - Add the sequences from an external service by entering a identifier into the text field. Sequences will be loaded into the current file Export Allows saving copies of selected sequences from the current document to a new document Close - Close the current document. This function is only enabled if two or more documents are present. Close Others - Close all but the current document. This function is only enabled if two or more documents are present. Restore - Restores a file from its last save. This function will only be enabled for files that have been previously saved or were opened from a preexisting file. Annotations - Associate annotations with the current document or view previously set annotations. Save - Saves the current file with the present save settings determined when opening the file or by previously saving it. Save As - Saves the current document as a new file or overwrites an existing file.

17 Edit Menu Undo - Undo the last action. Redo - Redo the last undone action Cut - Copy the selected objects to the system clipboard in addition to removing them from the document. Copy - Copy the selected objects to the system clipboard. Copy As > - Contains convenience functions for quickly placing specific data on the system clipboard as text and as a biological to be transferred to a range of 3rd party applications that use that data type. This submenu is only enabled if content is selected. FASTA - Place a FASTA string for the currently selected content on the system clipboard as a header with appropriate sequence text Plain Text Place only monomer text on the clipboard Paste - Paste the system clipboard data of highest priority into the document. Paste Special... - Lists all data that BioTuple can interpret from the system clipboard. You may then choose the data of choice to be pasted into the document. Clear - Remove all content from the current document. Purge Clipboard - This function clears the system clipboard. Purge History - This function clears the undo/redo history, which will reset the History widget. This may be convenient if the action list gets so long that it becomes unmanageable and causes memory issues, or if you would like to prevent yourself from undoing past a certain action. View Menu Amino Acid Data Shows a formatted table containing properties of all amino acids supported by BioTuple Nucletide Data Shows a formatted table containing properties of all Nucleotides supported by BioTuple

18 Sequence Menu New Sequence Add a new sequence to the current document. Remove Sequence Deletes the currently selected sequence from the center panel Highlight Query Opens a dialog, which allows for specific monomer patterns to be highlighted in the Center Panel. If a current sequence is selected, highlights will only be applied to that sequence, otherwise highlights will be applied to all sequences in the Center Panel. Remove Highlights If a sequence is selected, all highlights will be removed from that sequence, otherwise highlights will be removed from all sequences in the Center Panel. Jump to Index Allows the user to set the cursor to a single index in the selected sequence if the Index radio button is selected. If the Range radio button is selected, the monomers within this range will be selected in the selected sequence. View Features Opens a dialog displaying any features that have been specified for the selected sequence in the Annotate View. Phylogenetic Tree Opens the Tree Editor panel, which will show the phylogenetic tree constructed by a Multiple Sequence Alignment. A Multiple Sequence Alignment can be run in the Alignment View. BLAST Selection- Opens a dialog allowing the user to search the selected NCBI database using their BLAST tool. Results can be imported into the current document. View Alignment Data- Opens a dialog which shows the detailed information for an alignment that was completed in the Alignment View. Toggle Double Stranded Allows the user to toggle a DNA or RNA sequence between single and double stranded visualizations. Toggle Wrapped Sequence Toggles between a horizontal scrolling sequence, or a vertically scrolling wrapped sequence.

19 Complement Sequence Converts the selected sequence into the complementary strand according to standard base pairing rules. Reverse Sequence Reverses the order of monomers in the selected sequence. Reverse Complement Sequence Combines the Reverses and Complement functions and returns the reverse of the complementary strand of the selected sequence. Transcribe Sequence Converts a selected DNA sequence to RNA according to the genetic code specified in Preferences. Translate Sequence Adds a new protein sequence based on the selected RNA sequence according to the specific genetic code in Preferences. If a DNA sequence is selected, the user will be prompted as to whether or not the RNA intermediate should be added to the document. Reverse Translate Sequence Adds a new DNA sequence to the document based on the protein sequence selected. The codon chosen is selected based on overall codon frequency in the specified genetic code. Window Menu Minimize - Iconify the main BioTuple window to the dock or system tray. BioTuple s menu bar will remain focused on Mac OS X. Zoom - Expand the BioTuple window to fill the entire screen without overlapping any docks or system trays. Select Tab Right - This function is enabled if there are one or more tabs present in the tab tray. This function will select the tab to the right of the currently selected tab. If the currently selected tab it the rightmost tab, then the first tab is selected. Select Tab Left - This function is enabled if there are one or more tabs present in the tab tray. This function will select the tab to the left of the currently selected tab. If the currently selected tab it the leftmost tab, then the last tab is selected.

20 Purchase Menu This menu is only present during the free trial, and is removed when BioTuple is activated with a purchased activation code. Activate BioTuple - Displays the activation form to input a purchased activation code and generate the license for the BioTuple application. Buy an Activation Code - Opens the default internet browser to the purchase page of the BioTuple website. Help Menu BioTuple User Guide - View this user guide in the program most appropriate for opening PDF files. Quick Start Guide - Provides a basic overview of program functionality. By default the Quick Start Guide appears at startup. BioTuple Keyboard Shortcuts View a cheat sheet for all keyboard shortcuts and actions available in BioTuple in the program most appropriate for opening PDF files. References - View an organized list of references for the data and algorithms used in BioTuple. You can use this list to assess BioTuple quality. View User License - View the user license that you accepted when you activated BioTuple. Deactivate BioTuple BioTuple can only be used on the number of computers determined in your license. To switch from one computer to another, use this function first. This function is also useful if you need to reinstall your operating system. Contact Customer Service - Open the ichemlabs customer support form and prepopulate fields. This is the preferred way to contact ichemlabs customer service. ichemlabs Newsfeed - View the ichemlabs newsfeed RSS. Check for Updates - Check for updates to BioTuple. If any are found, you will see the changes listed and you will be requested to update BioTuple. If allowed, BioTuple will automatically update itself. There is no need to redownload or reinstall BioTuple for updates.

21 GENERAL TOOLBAR The general toolbars are located at the top-left of the BioTuple window (see Figure 2.1). They contain buttons for changing some overall aspects of the document. There are also buttons for quickly accessing menu items. Files Toolbar Figure 2.5: Files Toolbar Create a new blank document Open a file Save a file Import Copy Paste Zoom In Zoom Out Export Cut Undo Redo OPENING A DOCUMENT To open a document, select the Open... menu item from the File menu, locate the file you would like to open with the file chooser that appears and click the Open button. BioTuple can read many file formats, and the default file type the file chooser searches for is a BioTuple Project (BTP). To allow other file types, click on the format drop down selection at the bottom of the file chooser and select the file type you would like to open, or select the All Files type. Selecting All Files will allow you to select any file, including files that BioTuple cannot read. If such a file is chosen, you will see a file read error displayed. Otherwise, BioTuple will attempt to open the file by analyzing the file extension and file content to determine its type. To open a recently opened document, enter the Open Recent submenu in the File menu and select the document you would like to open. The 10 most recently opened files are remembered.

22 FILE CHOOSER The file choosers that you use to open your files will closely resemble the standard file choosers that in use in other applications. DISCARD RECENT CHANGES TO A DOCUMENT To retrieve the last saved version of a file without using Undo functions, select the Restore menu item in the File menu. All changes made to the file since it was last saved are discarded and the saved version of the file will appear. SAVING DOCUMENTS To save your document as a file, select the Save or Save As... menu item from the File menu. Save will automatically save the document to the file it is associated to, while Save As... will allow you to save that file to a new location or overwrite another file. If there is no file associated with a document, the Save function will work identically to the Save As... function. When saving a new file or using the Save As... function a file chooser will appear. Select the location to save the document to and type file name or accept the default name. You do not need to type in an extension. Only the BioTuple Project can store your document with 100% accuracy. Other file types, designed for other purposes, may define different objects and properties in BioTuple. A warning will pop up when saving to a file type other than a BioTuple Document. These warnings can be disabled in the Preferences window under the Saving tab. After selecting the file type to be used, press the Save button to save your document as a file. AUTOSAVING BioTuple will automatically save unsaved content for you at regular intervals. If your computer shuts off unexpectedly, the next time BioTuple opens, all autosaved content will be displayed. You can turn off autosaving in the Preferences window under the Saving tab. You can also specify the autosave interval in the same section. The default autosave interval is 5 minutes. REVERSING ACTIONS BioTuple keeps track of the actions you perform. You can reverse actions one at a time by selecting the Undo menu item in the Edit menu then restore them with the Redo menu item in the Edit menu. Once you close your document, the undo queue is reset. SELECTED COMPONENTS In the Center Panel, click anywhere on the sequence component to select it. You will see the title bar become red. This indicates a sequence is selected, which will focus functionality on this sequence.

23 SEQUENCE LIST The Sequence List is a visualization of all sequence currently in the document. Here you can select or deselect sequences that you want to be visible in the center panel. You can also use the down arrows to display any relevant metadata for a specific sequence. A toolbar is present with a few supplementary features. Figure 2.5 The Sequence List Sequence List Toolbar Select/Deselect All Sorting options (Default, Alphabetical, Selected) Deselected sequences will not appear in the Center Panel, or be subjected to functions that apply to the document as a whole. They also cannot be selected in views that contain sequence selection combo boxes.

24 CHAPTER 3: EDIT VIEW Figure 3.1 Example of sequences in the Edit View The Edit View is used for importing, visualizing, editing, and performing transformations on sequences. The keyboard can be used to insert or delete specific monomers from a sequence, as well as shortcut key combinations to access various functions including converting between DNA, RNA, and protein. Often toggling between double stranded and wrapped views can aid in visualizing sections of a sequence. The font, and size of the monomers be controlled with the Sequence Font Family and Sequence Font Size in the General Panel of the Preference Panel.

25 THE EDIT TOOLBAR Create a new blank sequence Remove Selected Sequence Translate Edit Sequence Information Reverse Translate Reverse Toggle Double Stranded Complement Toggle Wrapped Reverse Complement Transcribe SEQUENCE TRANSFORMATIONS Often it is beneficial to convert sequences between DNA, RNA and protein. These transformations can be performed with Transcribe, Translate, and Reverse Translate. Transcribe Sequence Converts a selected DNA sequence to RNA according to the genetic code specified in General Panel of Preferences. Translate Sequence Adds a new protein sequence based on the selected RNA sequence according to the specific genetic code in the General Panel of Preferences. If a DNA sequence is selected, the user will be prompted as to whether or not the RNA intermediate should be added to the document. Reverse Translate Sequence Adds a new DNA sequence to the document based on the protein sequence selected. The codon chosen is selected based on overall codon frequency in the specified genetic code. KEYBOARD USAGE When working with a sequence, the keyboard is essential for editing. When working with a sequence, using the keys associated with a monomer will add a new monomer at the selected location. For adding an unknown character, use the space bar. Using the backspace key will remove

26 either a single monomer, or a segment of monomers if a selection is highlighted. You can also use the arrow keys to change the position of the cursor. Single letter abbreviations for monomers can be found under View in the application menu bar. Keyboard shortcuts can be found under Help in the application menu bar. ADDING SEQUENCES There are a few ways to add new sequences to the current document. First, you can add a new sequence with the Add New Sequence button. This will make a new blank sequence for you to work with after selected the sequence type, and adding a name from the dialog. You can also import sequences from the NCBI by using the File->Import From ->NCBI Entrez. This will prompt the user, asking for a sequence ID, and if the sequence is a Nucleotide or Protein. Either a GI or Accession number will work here. For loading sequences from a specific PDB file, select File- >Import From ->Protein Data Bank to import the chains from a sequence with the given protein ID. By default, any imported PDB Sequence will not be saved to the hard drive unless done manually. Turn on Download PDB Files on Import to save any imported PDB files to the specified directory

27 CHAPTER 4: ANNOTATE VIEW Figure 4.1 Example of sequence annotation The Annotate View is useful when the user needs to find potential reading frames, denote features, or label restriction enzymes. A sequence is selected in the combo box, which loads three components into the Center Panel. The first is a linear representation of the sequence, which will highlight the location of any selected features. The second is a finer grain representation showing individual monomers. The last is a feature view, which will show the location, type, and name of all features of the selected sequence. ANNOTATE TOOLBAR ORF Scan Toggle Wrapped Map Restriction Enzymes Toggle Double Stranded Add a Feature

28 ORF SCAN The ORF Scan feature will display all potential open reading frames for the selected sequence. And open reading frame is defined as a start codon (AUG), the frame, and an end codon (TAG, TAA, or TGA). The frame length threshold can be set in the General Panel in Preferences. The higher the threshold, the more potential ORFS will be rejected. To view reverse ORFS, press the Toggle Double Stranded button in the toolbar. The ORF Scan Results dialog will show each potential ORF with start index, end index, the number of 3 monomer codons, and which frame the ORF is present in. The frame is represented as a sign (+ forward, - reverse) with a number indicating the offset. In order to add an ORF to the Center Panel, check the box to the left of the ORFS desired and press done. This will add the ORFS in the feature view. THE FEATURE VIEW Figure 4.2 ORF Scan Results Dialog Once some features have been added to the Feature View. The user has the ability to interact with them. By clicking a feature, both views above will show a highlight of where the ORF is located. Information about the ORF will also be shown in the bottom left of the Feature View. By double clicking an ORF, the user can change the title of a feature in the prompted text box. Features in the forward orientation will be shown going to the right, whereas features in the reverse orientation will be going to the left

29 CHAPTER 5: CALCULATE VIEW Figure 5.1 Properties shown in the Calculate View The Calculate View is used for displaying properties of the selected sequence. These properties include, length, molecular weight, a breakdown of content, and some thermodynamic properties. Once a sequence is selected from the combo box, the view will be populated with these properties in a formatable table. Units can be selected between kj/mol and kcal/mol in the General Panel of the Preferences Panel

30 CHAPTER 6: PROTEIN VIEW Figure 6.1 Example of the 3 forward and 3 reverse reading frames in the Protein View The Protein View is helpful when we want to look at the reading frames of a given DNA or RNA sequence. This view will automatically load in all nucleotide sequences possible, and ignore protein sequences. Each reading frame is given a identifying color and is aligned with the starting monomer. When a reading frame is selected, the starting sequence will gain an alternating red and blue highlight to make codon identification easier (Forward Reading frame +0 is selected in the bottom sequence in Figure 6.1). The user can select which reading frames they want to see with the combo box at the top of the toolbar. Reading frames can also be added to the document for closer inspection using the checkboxes and clicking add. PROTEIN TOOLBAR Figure 6.2 The protein toolbar in the Protein View used for importing protein reading frames

31 Using the Number of Reading Frames combo box. The user can select which reading frames they would like to see in the Center Panel. If the user wants to import some of these reading frames to the document, this can be done by selecting the sequence in the Center Panel, clicking the checkbox next to which reading frames you want to import (multiple can be selected), then clicking Add. This will add each checked reading frame as a protein sequence with the same title as the selected sequence with the suffix -rx where X is the reading frame number.

32 CHAPTER 7: ALIGNMENT VIEW Figure 7.1 Multiple Sequence Alignment completed in the Alignment View The Alignment View is where the user can perform pairwise and multiple sequence alignments. These types of alignments are helpful when looking for sequence similarity, which can indicate a functional, structural or evolutionary relationship. ALIGNMENT TOOLBAR Align Remove Alignment Sequence Alignment Settings Clear Alignment Add Alignment Sequence

33 PREPARING FOR AN ALIGNMENT ADDING/REMOVING SEQUENCES When entering the Alignment View, the program will guess which sequence type would be most appropriate given the sequences in the document. If possible, the view will be populated with Sequence Selection Boxes, where a sequence can be selected from the dropdown. These Sequence Selection Boxes can be dynamically added or removed using either the Add Sequence or Remove Sequence buttons in the toolbar. Alternatively the + and - buttons to the right of the dropdown serve the same purpose. To change the type of alignment, use the Alignment Selector located at the top of the Center Panel. If there are not enough sequences of the selected type, a message will show, and no sequences will be displayed. In this case, choose another sequence type, or add new sequences of this type to the document. SETTING PARAMETERS FOR AN ALIGNMENT Once the sequences desired have been selected, the user can choose the settings for the pairwise alignments using the Alignment Settings Button or in the Functions Panel of the Preferences Panel. Here you can the pairwise alignment settings for either protein or nucleic alignments. The user can select between using a substitution matrix, or defined match/mismatch score, as well as gap penalties and affine scoring. Protein and nucleotides have independent settings. PERFORMING AN ALIGNMENT Once the sequences are added, and the settings are correct. Pressing the Align Button will bring up a dialog where the user can specify which type of alignment will be performed. For pairwise, the local alignment uses a Smith-Waterman algorithm, global alignment uses the Smith-Waterman algorithm. Multiple Sequence alignment uses a Progressive Alignment where a Guide Tree is constructed using pairwise scores and a neighbor-joining algorithm. References for these algorithms can be found in the References section of the Help Menu. ANALYZING A COMPLETED ALIGNMENT PAIRWISE ALIGNMENT After an alignment is complete, the results will be displayed in the bottom panel. If the alignment was pairwise, the two resulting sequences will be displayed with a default color scheme. Green indicates matched pyrimidines, whereas blue indicates matched purines. Red indicates a mismatched monomer. In addition the header on this panel will show an alignment score, Percent Identity, and Percent Similarity.

34 MULTIPLE SEQUENCE ALGINMENT Figure 7.2 Completed Multiple Sequence Alignment If a multiple sequence alignment is performed, some more information will be shown. The same color scheme is applied here, but there will also be a consensus sequence added in black. This consensus is determined using the majority rules scheme. In addition, two bars will be added to the bottom of the Center Panel. The two bar graphs have the same data points, which are calculated based on how strong the evidence for the consensus is. The top bar uses a Red-Blue-Green color scheme which uses green as the highest similarity, blue as moderate, and red as low. The bottom bar uses the color of the monomers above, but with varied intensity. For example, if a column of monomers is red, the bar will be red, but the more monomers that are closer to the consensus, the brighter the color will be, whereas columns with many different monomers will have a darker color. ALIGNMENT INFORMATION In order to show a more detailed view of the alignment results, pressing the Alignment Information button on the top right of the panel ( i ), will open a dialog where the user can see the number of sequences aligned, the length, as well as a table that can be selected to show either similarity or identity. Similarity will group monomers that have the same chemical group ( Polar, Nonpolar, Acidic ), whereas Identity only groups based on matching monomers.

35 CHAPTER 8: STRUCTURE VIEW Figure 7.1 Hemoglobin shown in the Structure View This view uses only portions of the features present in ChemDoodle3D. For more details on ChemDoodle3D, chemdoodle3d.com The Structure View is used to visualize the 3D structure of the selected sequence. This view works by querying the RCSB protein data bank with the selected sequence, downloading a PDB file, and loading this into the View. The 3D canvas allows for some basic functionality such zoom in/out and rotation. The user can also select the color scheme for either Amino Acids or Nucleotides. Try double clicking the 3D canvas. This will toggle auto rotate on the structure. Double click again to turn this off. IMPORTING PDB FILES When opening the Structure View, any PDB files associated with the sequence will automatically be loaded. If no PDB file is found, the user will be prompted if they want to import one. If yes is selected, the program will query the RCSB, and load the closest matching PDB file (assuming it is within a threshold of accuracy). By default, any imported PDB Sequence will not be saved to the hard drive unless done manually. Turn on Download PDB Files on Import to save any imported PDB files to the specified directory

36

37 CHAPTER 9: SHARING INFORMATION OVERVIEW BioTuple has advanced functions for interacting with other applications on your computer. This is essential for importing graphics into word processors or for transferring biological data into online forms This section introduces the new user to BioTuple s system clipboard capabilities. It covers the following topics: Introducing the system clipboard. How to copy data and graphics from BioTuple into other applications. How to copy data and graphics from other applications into BioTuple. What types of data can be transferred. THE SYSTEM CLIPBOARD The system clipboard is a construct of the operating system that contains data for sharing between applications. Only one application can place data on the system clipboard at a time. Other applications can then see that data and load it. This system forms the basis for copy and paste functionality. BioTuple will place text data on the clipboard in the specified file type for pasting into online forms or other applications. CLIPBOARD SETTINGS BioTuple can transfer data to almost any application that has been created. But it is impossible for BioTuple to determine which data should be transferred. Therefore, you need to set the appropriate Copy Settings to make sure any ambiguities are resolved with the application to which you are pasting. Copy Settings can be set in the Preferences window under the Advanced tab as shown in Figure These settings will allow you to explicitly control what data BioTuple will transfer to other applications.

38 Figure 11.1: Copy Settings There are a few types of common formatted text types that may be transferred: Plain Text (Unformatted) - Only the text is present in this data, no formatting. FASTA Uses the FASTA format with the header of the selected sequence followed by monomer data There are two main types of sequence data that may be transferred: BioTuple Uses the BioTuple specified file format, which contains all relevant sequence and view data. FASTA - Uses the FASTA format with the header of the selected sequence followed by monomer data Therefore, to work with other applications, first decide what type of data you would like to transfer and what types of data the other application accepts. Then set the appropriate copy settings to continue. COPYING DATA TO OTHER APPLICATIONS USING THE COPY FUNCTION To copy data from BioTuple into other applications, execute the following steps: 1. Determine which data you would like to transfer and the types of data that the other application can accept and configure the copy settings in the Preferences window under the Advanced tab accordingly. 2. Select sequence or segment of monomers you want to copy

39 3. Click on the Copy menu item in the Edit menu or press its menu accelerator keyboard shortcut, which is ctrl-c (command-c on Mac OS X). 4. Use the paste function present in the other application to paste the content. If the other application has a Paste Special... function, you may use that to specify which data type to paste. USING THE COPY AS FUNCTION The copy as functions are preset shortcuts for placing certain data forms on the system clipboard without changing the data types to be copied in the Advanced tab of the Preferences window. Select the content in the document to be copied and then select one of the menu items in the Copy As... submenu of the Edit menu. The most popular data types are supported. These functions will copy the selected sequence or sequence segment as whichever format is selected. PASTING DATA FROM OTHER APPLICATIONS To paste data from other applications into BioTuple, execute the following steps: 1. Use the copy function present in the other application. 2. Click on the Paste menu item in the Edit menu or press its menu accelerator keyboard shortcut, which is ctrl-v (command-v on Mac OS X) to paste the highest priority data to the Center Panel. WHERE CONTENT IS PASTED The pasted content will be located according to the following rules: 1. If no sequences are selected, the data will be added as a new file. 2. If a sequence is selected, the data will be pasted where the cursor is located. BIOLOGICAL FORMAT COMPATIBILITY BioTuple supports many of the most common biological file types and can interpret various biological formats for input to and output from other biological applications. Biological formats are discussed in detail in Appendix B: Biological File Types.

40 APPENDIX A: MANAGING BIOTUPLE OVERVIEW The chapters in this user guide explain how to use BioTuple to input and manipulate biological data. There are other functions for managing the application itself. This section shows the new user how to manage BioTuple. It covers the following topics: Updating BioTuple. Deactivating and restoring BioTuple. Using your ichemlabs account. APPLICATION AND FILE ICONS You may wish to associate file icons and application icons with BioTuple if BioTuple does not already do this for you, such as on Linux. In the resources folder in the main BioTuple installation folder, operating system specific graphics will be provided for BioTuple and recognized biological file types. Use you operating system s documentation to associate those icons with the application and file types. UPDATING BIOTUPLE BioTuple will check for official ichemlabs updates and will automatically update to the latest available version for you if you allow it to do so. To check for updates, just click the Check For Updates menu item in the Help menu. If no update is available, you will see a confirmation message stating that your copy of BioTuple is up to date. If there is an update available, you will see an Update Available window appear listing all the changes introduced by the update. Just click the Update button to proceed. BioTuple will close to perform the update, so make sure to save your files before continuing. NOTE: You must have administrator privileges to update BioTuple. If you see a message stating that you cannot update because you do not have the necessary permissions, please double check that you ran BioTuple as administrator (on Windows for instance) or contact your system administrator to help you. The auto-updater will then open. It will download the latest BioTuple updates, verify the contents with our server, and then proceed to update BioTuple. The updater can may take several minutes to complete. After the updater completes, it will notify you that it is ready and that BioTuple will be reopened. Just click the Ok button to close the updater and continue. Your version of BioTuple has now been updated. Enjoy!

41 By default, BioTuple will automatically check for updates while loading. You can disable this feature in the Preferences window under the Online tab. You may always manually check for updates by using the menu item mentioned above. WINDOWS ADMINISTRATOR PRIVILEGES A common issue on Windows Vista/7+ is to enable administrator privileges for BioTuple to update. If BioTuple states that you do not have the necessary administrator privileges on these platforms, perform the following steps: 1. Exit BioTuple. 2. Locate the BioTuple icon (shortcut or actual application). 3. Right-click on the icon and select Run as administrator. 4. Accept the security request. You will then be able to update BioTuple. If this process does not work, you will need to consult with a system administrator to update BioTuple. SKIPPING UPDATES If you wish to ignore the current update, when the Update Available window is displayed, just select the Skip this Version button. You will no longer be notified that this update is available. You will still be notified of subsequent updates, which you may also skip. To obtain an update that was skipped, select the Check For Updates menu item in the Help menu. PURCHASING UPGRADES Major version upgrades to BioTuple must be purchased. When a major version upgrade becomes available, you will still be presented with the Update Available window. However, instead of an Update button, a Purchase Upgrade button will be presented. Click on the Purchase Upgrade button to be directed to the upgrade purchase page. After purchasing the upgrade, again check for updates. The Update button will then be showing and you may proceed with the update as described in the previous sections. MOVING YOUR ACTIVATED COPY TO A NEW COMPUTER At some point, you may want to switch to a different computer. Your purchased BioTuple activation code is restricted by the number of computers BioTuple is activated on. Therefore, we provide you the ability to deactivate BioTuple and reactivate it on a new computer. To begin, just click the Deactivate BioTuple menu item in the Help menu. NOTE: When deactivating BioTuple and switching to a new computer, your custom preferences and other user settings will be lost. If you have settings files (templates, biological document settings), those can be copied to the new BioTupleSettings folder that will appear after BioTuple is activated on the new computer.

42 Once the deactivation procedure has begun, it cannot be cancelled. Make sure you record your activation code, which will be displayed in the Details section of the deactivation confirmation message, so you can use it again. You should also have a record of your code from the receipt you received upon purchasing it. Once you accept the confirmation message, BioTuple will close and your copy will be deactivated. You may now use your activation code to activate BioTuple on a new computer. PREPARING FOR A SYSTEM RESTORE If you do anything to your system that will remove or eliminate the BioTuple license file, such as performing a system restore or installing your operating system from scratch, you will need to first deactivate your copy of BioTuple. Instructions for deactivating BioTuple can be found in the previous section.

43 APPENDIX B: BIOLOGICAL FILE TYPES OVERVIEW BioTuple can currently read and write 6 different biological file types. This section discusses the following issues: BioTuple adherence to third party file type specifications. What biological file types are supported. How to annotate your files. ADHERENCE TO THIRD PARTY SPECIFICATIONS File formats implemented in BioTuple strictly follow their published specifications. BioTuple does not take liberties with their rules or inject BioTuple -only content into them. All file format objects and properties are mapped as closely as possible to objects and properties in BioTuple. Thorough implementation details are also provided in the following sections. Specification references can be found by selecting the References menu item in the Help menu. BioTuple will try to interpret all 3rd party files as best as possible, so if you do find a file that doesn t read well, please send it to us so we can improve our compatibility. SUPPORTED BIOLOGICAL FILE TYPES 1. ichemlabs BioTuple Document (.btp) 2. FASTA (.fasta,.fna,.fsa,.fa,.mpfa) 3. RCSB Protein Data Bank (.pdb) 4. GenBank Flat File (.gen) 5. ichemlabs Sequence Line Query (.slq) 6. Plain Text (.seq) FILE ANNOTATIONS Annotations can be read and written to files where possible. Each document has its own set of annotations. To view previously defined annotations, edit them or create your own, select the Annotations... menu item in the File menu. Then edit the fields shown in Figure B.1. Figure B.1: File Annotations Window

44 Figure B.1: File Annotations Window All data associated with a file will be saved in BioTuple Documents. Other users that open your annotated BioTuple Documents files will be able to easily access them. Other file types may be able to save annotations as well, read their documentation in the following sections for the extent of annotation functionality. REFERENCES All data within BioTuple s databases are associated with a unit (if not unit-less) and the reference source it originated from so you may assess its quality. The entire set of references can be viewed at any time by selecting the References menu item in the Help menu as shown in Figure D.1. Nondata related references are also displayed in this list, including filetype specifications and algorithms. Figure D.1: BioTuple s References List

45 APPENDIX C: TECHNICAL SUPPORT WHEN TO CONTACT CUSTOMER SERVICE While we do our best to debug and test BioTuple, a few bugs will always slip past us. Because of this, you may have encountered an issue with BioTuple. We certainly want your experience with ichemlabs software to be as enjoyable and hassle free as possible and we will do our best to address any issues you bring to our attention. In fact, we encourage you to report any bugs that you find to help us perfect BioTuple. Before contacting us, please do the following: Check the system requirements for BioTuple at the beginning of this user guide to ensure that your system is supported. Search this user guide to see if your issue is addressed here. Read the Troubleshooting section of this appendix and follow the possible resolution tactics outlined there. Double check that your issue is reproducible and outline the exact steps performed to cause it. Take screenshots of any relevant graphical issues or popup errors in their entirety. Make note of anything you have tried to correct the problem. HOW TO CONTACT CUSTOMER SERVICE After collecting all relevant information, click on the Contact Customer Service menu item in the Help menu as shown in Figure H.1. This is the best way to contact ichemlabs customer service and to receive fast support. We always respond to inquiries within one business day, will most likely answer your within a few hours and very often respond within an hour. Figure C.1: Contact Customer Service Menu Item This function will automatically pre-populate fields as appropriate in our support ticket system at support.ichemlabs.com. Just fill in the remaining fields and open a ticket. You can also attach supporting files.