Chapter 1. Getting Started Double Digester (DD) is a program designed to help you make restriction maps from gel data. You give it fragment sizes from two different single restriction digests together with the fragments from the double digest done with both enzymes. Data entry can be done with the mouse, the keyboard or from a file. Using the mouse allows you to work directly from a picture of your gel. DD works on a Macintosh, and also on Unix using the X Window System (X11). With a few small exceptions, DD behaves the same on both platforms. This manual is intended for both platforms. It assumes that you know the basics of starting an application under either system. This manual has three chapters. This introductory section is designed to teach you the basics of DD as rapidly and smoothly as possible. Chapter 2 is a reference section, which describes everything that DD can do. Chapter 3 tells you how to install DD on your system and keep it working. 1.1 A Simple Example Start DD. On a Macintosh, you do this by double clicking. Under Unix/X11, just type "double-digester" after the command prompt in a terminal em- ulation window (do not run it in the background). After a pause, the DD window will appear. You can learn about DD by moving the pointer around the DD window. For example, if the pointer is over the word "Digests", a message appears in the top window that tells you that the Digests command is used to "enter, load or select a double digest data set". 1.1.1 The Main DD Window The main window of DD is divided into four areas: "Digest Data", "Constraints", "Maps" and an area across the top used for displaying messages. Each area (window) has a menu bar. The "Digest Data" window is for input data. It contains a representation of the data that looks like a gel on which these di- gests have been run. DD's results will be displayed in the "Maps" window. The "Constraints" window is used to keep track of additional information about your data. Notice the "Exit" on the top menu bar: it will get you out of DD. You can also exit by using the normal close-box, menu or other options provided on your computer. 1.1.2 Loading a File To see how DD works, click once on the word "Digests" in the "Digest Data" menu bar. A menu appears. You can get out of this or any other pop-up menu by clicking on "CANCEL". The menu contains a list of options, including an indented list of files that starts under the heading "Files in Data Directory". Try clicking on pD4321, which contains (EcoRI/HindIII) and DdeI double digest data for that plasmid. A dialog box will appear pointing out that you are probably working with circular DNA (true, since pD4321 is a plasmid). DD always checks your data for internal consistency before making maps (see 2.3.4.4). Just click on "OK", and a diagram of a gel will appear in the "Digest Data" window. 1.1.3 Making a Restriction Map Click on "Make Maps" in the "Maps" window. A restriction map appears, in linear, circular and text form. The text map shows fragments labeled by their sizes, with vertical lines for cut sites. The linear and circular maps each have three lines, one for each digest. The double digest is in the center, and restriction sites are labeled by vertical tics. Notice that putting the pointer over a fragment causes information about that fragment to appear in the window. For example, if you put the pointer over the 1.12 or 0.67 kb Dde fragments, DD will tell you that they are unordered within the 2.92 kb E/H fragment. 1.1.4 The Importance of Constraints Now look at the "Constraints" window. It says that the DdeI 1.12 fragment is identical to the DdeI-E/H 1.12 fragment, and similarly for the 0.67 and 0.47/0.45 kb fragments. These constraints are important facts about your data that cannot be easily expressed in terms of fragment size. On many gels you can tell by inspection that a pair of bands in two different lanes are the same fragment, or different fragments. Imposing constraints is how you tell DD about important things that you know about your data. To see how important constraints are, try removing them. Just click on "Drop", then click on the constraint. You can also click directly on the con- straint, and pick "Drop" from the pop-up menu. After you have removed all three constraints, click again on "Make Maps". With the constraints DD found 1 map, but now it has found 11. The map displayed fits the data best, to within 2 % of the assigned fragment sizes. The maps are listed in order of goodness of fit, and you can step through them by clicking on "Next" and "Prev" in the "Maps" window. 1.1.5 Experimental Error You can tell DD about the accuracy of your data as well. Look at the text representation of map 2 of the 11 maps you just made by removing the three constraints. Notice that the 0.67 kb Dde I fragment was matched with the 0.78 kb E/H-Dde I fragment. This means that DD treated them as the same fragment because of experimental uncertainty about their size. You can see why by looking at the "Digest Data" window. Each band on the gel has error bars on each side which graphically show how much uncertainty there is about the fragment sizes. The error bars of the 0.67 kb DdeI fragment overlap with the error bars of the 0.78 kb E/H-Dde I fragment. When DD first comes up, the error bars are set to a very rough estimate of the reliability of a typical gel. You may know considerably more than that about the reliability of your data, and you can tell DD about that as well. You can change error ranges in a variety of ways: for the whole gel, for a single lane, or one band at a time. In this example, we'll do it for the whole gel. Click on "Error" in the "Digest Data" window. A popup menu ap- pears. Click on "Change Size-Estimate Error Ranges (default now 2.0 Standard Deviations)". Another popup menu appears with a choice of error ranges. You can specify them either as fragment size error in %, or as Standard Deviation. Suppose for a moment that you had run this gel very carefully, and were quite certain that your fragment sizes were accurate to 5 %. Click on 5 % in the "Global Error Level" popup. Now click on "Make Maps" again. You are down to two maps. 1.1.6 Asserting Constraints There are 2 maps because DD does not know whether the 0.47 E/H fragment matches the 0.45 E/H-Dde I fragment or the 0.35 kb E/H-Dde I fragment together with a very small fragment that ran off the gel (see 2.3.3.3). To assert the constraint that the 0.47 kb E/H fragment is the same as the 0.45 kb E/H-Dde I fragment, click on "Add" in the constraints window, and choose "Identical" from the popup menu that appears. Then, simply click once on each of the two bands. The constraint will appear in the "Constraints" window. Now click on "Make Maps" and you'll get just one map. 1.1.7 Saving to a File You can save your map to file, which can be printed. Just click on "Save" in the "Maps" window. A popup menu appears. Choose "Save Current Map to File". Another popup appears: choose "Save Map in a New File". A dialog box appears; type in the name of the file you want to save your map in, then hit the "return" key (and, for the X11 version, click on "ACCEPT"). Your map is on disk. 1.2 Data Entry Data can be entered into DD by three methods: by placing bands on the gel with the mouse, by typing in fragment sizes, or reading a file made with DD or a text editor. To use any of these methods, click on "Digests". The popup menu that appears has two choices at the top under "Interactive Data Entry": one that reads "Method 1: Graphical Interface" and another that says "Method 2: Type in Values". You have already loaded a file: the available files in your current directory or folder are also listed on the menu. In this example, you'll see how to use the mouse. 1.2.1 Graphical Data Entry With this method of data entry, you place bands in the DD gel in the same places relative to standards as they are in your gel. Choose "Method 1: Graphical Interface" from the "Digests" popup menu. You will need a set of standards. Choose the standards you used in your gel by clicking on "Other" under "Digest Data", and choose "Choose Lane Standard" from the popup menu. The next popup menu gives you a choice of the available standards. Notice that the standards come up with a default error of zero. Now you can name your data set by clicking on the title ( "New-1" ) after the word "Digest:" that appears under the menu bar. A dialog box will appear to enter the name of your data set. You tell DD which enzymes you are us- ing by clicking on the enzyme names above the single digest lanes, choosing "Change Enzyme" from the popup menu, and entering a new enzyme name in the dialog box that appears. To place your fragments on the gel, click on the name of your enzyme, and then choose "Add New Fragments via Mouse" from the popup menu. Now as you place the pointer in a gel lane, DD shows the equivalent fragment size in kb on the top of the gel lane. Move the pointer to the approximate place where your band is, and press down the mouse button. While holding the mouse button down, make fine adjustments to the position of the band while watching the fragment size readout. When the band is in the correct position, release the mouse button. Repeat for all the bands in that lane. You get out of data entry mode by moving the pointer out of the "Digest Data" window. Notice that DD displays the total size of all fragments in a lane at the bottom of that lane. At any point, you can edit the data that you are entering. To edit, get out of data entry mode if you are in it. Click on the band you want to adjust or remove, the choose the appropriate option from the popup (see 2.3.1.1 for more ways of editing). When you are done, you will probably want to save your new data: select "Save" (see 2.3.2 for details) in the "Digest Data" window. 1.2.2 Typing in Values Choose "Method 2: Type in Values". You will need to tell DD the name of your data set, the name of each of the two enzymes you used, and the fragment sizes in each of the three lanes. You type data into all six areas in the same way. Point at a data entry area. A box appears. Click the mouse. You are ready to enter data. As you type, the letters and numbers appear in a typewriter-style font which tells you which input area is active. When you are done, press "return". The type will go back to the usual DD font. When entering fragment sizes, you can use bp or kb; be sure to separate the fragment sizes by spaces. You can change the data entered in a given field by clicking on it again. When you are done entering data, click on "ACCEPT". You can save this data set to a file by choosing "Save" in the "Digest Data" window. 1.3 Doing More With DD DD gives you many ways to express facts about your data. You can set error ranges by gel, by lane, and by fragment. These errors can be specified by size error or by error based on migration distance. You can tell DD that a fragment in one lane is identical to, is bigger than, is smaller than, contains, or doesn't contain a fragment in another lane. You can display maps starting from any double digest fragment. DD allows you to manage your data and maps by keeping them in whatever files you like. Moreover, you can store your maps as text or postscript graphics. You probably noticed many of these possibilities as you went through the first example. They are discussed in the reference section of this manual. Chapter 2. Reference In this chapter you will find a list of all of the capabilities of DD and how to use them. You probably won't want to read this section all the way through. You may want to look things up in it from time to time, and so the first section of this chapter explains how the reference section is organized and how to use it. This manual is also available as online help. To make DD more convenient to use, there is usually more than one way to do something. Every command has a heading in this chapter although we have used cross references to cut down on redundancy. 2.1 Six Main Windows DD has four subwindows of its main window and optional ones for help and showing match details. For each of the four subwindows and the optional "Match Details" window there is a section like this one. If you give DD a command, you are doing it from a certain window, and that is the section of the manual that you look in to find the command. The subheadings in this manual have the same names as the commands they describe. The beginning of a section about a particular window briefly describes the information displayed in that window as well as the things that DD does that you control from that window. 2.1.1 Buttons You give commands to DD by clicking with the mouse and choosing from menus. In this manual, a place you can click on to give a command is called a button. Most buttons are words, like "Make Maps", and most of these are located in a row across the top of each subwindow. We refer to this row of buttons as the menu bar for that subwindow (not to be confused with the Macintosh menu bar). Some buttons, like the bands on the gel in the "Digest Data" window, are not words. Every button that is visible on the main window has its own subsection. The beginning of a subsection describes what the button does, if it does some- thing by itself. Most buttons expect you to make further choices from a menu. If so, there will be further subsections about each menu choice. 2.1.1.1 Popup Menus. DD has many popup menus. They are menus of a few items that appear after clicking on a button or an item of another menu. They go away after you click on a menu choice or, in X11, if you click outside the menu. Each also has a "CANCEL" button. Usually you give DD a command by clicking on a button and choosing from a popup, but sometimes you will need to choose further, either through another popup menu or a dialog box. Dialog Boxes. Dialog boxes expect you to type something in or read a message, and won't let you proceed further until you do. If you change your mind about using a dialog box, just click "CANCEL". You may have to hit "return" first. You can get out of a dialog box with a message by clicking on "OK". Under X11, you may have to click on a dialog box to type in it, depending on how your window manager is set up. How Do I Give This Command? Occasionally the command you want will be rather deeply buried in a chain of submenus. This chapter is organized to help you find it easily. For example, suppose that this paragraph described what you wanted to do. That means the bold heading of this paragraph is the name of the command as it appears on a menu. You'd give the command by going to the window described in 2.1, clicking on the button described in 2.1.1, choosing 2.1.1.1, choosing the menu item "Dialog Boxes", and finally choosing the command described here, which would appear on the menu as "How do I give this command?". 2.2 The Top Window This is the general information window of DD. Usually, it describes important information about whatever component of DD the mouse is pointing to. For example, when the mouse is pointing to a band on the gel, it gives information about the size range of that fragment. When DD is calculating maps, it shows the status of the calculation. When defining a constraint, the top window informs you that DD is waiting for you to select a fragment. The top window is also used for the display of match information selected in the optional "Match Details" window (see 2.6). The menu bar of this window has three buttons, called "Help", "Configure", and "Exit". 2.2.1 Help Gets you this manual online. When you choose "Help", a popup menu appears with the main headings of this manual listed. Click on a heading to make the corresponding section of the manual come up in a help window. To scroll up or down in the help window, use the scroll bar on the side. The entire scroll bar represents the whole manual, and the stippled part represents the part that is in the window. When you click with the mouse, the top of the stippled area of the scroll bar will move to the pointer, and the corresponding part of the manual will become visible. You can get rid of the help window by using the close box (Mac) or your window manager (X11). Unlike a menu, the help window does not go away unless you explicitly dismiss it. You can use DD with the help window up. If you need to find something from the menu of topics after using "Help", just choose "Help" again, and select from the menu. The appropriate section of the manual will appear in the "Help" window. 2.2.2 Configure Use this button to set the default data directory, color, and whether details of map building are shown. 2.2.2.1 Display in Monochrome/Color. Toggle between color and monochrome versions of DD. DD is easier to see in monochrome on monochrome monitors and certain grayscale or color monitors. 2.2.2.2 Set Default Data Directory. The default data directory (or "folder" ) is the directory that DD starts from to look for and create datafiles and maps. This option allows you to find out which folder DD is now using as a default, and change it if necessary. Accept Directory . Choosing this option tells DD that you want to use the current directory (folder) as the default. Use this to keep your current directory or choose a new one after moving through the directory tree with the "Subdirectories of Current Directory" or "Move Up Directory Tree" options. Subdirectories of Current Directory. A list of subdirectories (folders) of the the current default directory (folder). Choosing one of these will cause a new menu to appear with the chosen subdirectory as the new current directory. Move Up Directory Tree. Move to the parent directory (folder) of the current directory (folder). Choosing this option will cause a new menu to appear with the former parent directory (folder) as the new current directory (folder). Macintosh Dialog Box. Set the default directory with a standard Macin- tosh dialog box. 2.2.2.3 Show Details of Map Building. Choosing this option causes the "Match Details" window to be displayed. This window shows details of the intermediate stages of DD's calculations (see 2.6). To stop showing the details of map building, click on the "Close Window" button, the close box (Macintosh) or use your window manager to quit the window (X11). 2.2.3 Exit Quit DD. On a Macintosh, you can also quit by clicking on the close box or choosing "quit" from the Macintosh "file" menu. If you are using DD under X11, you can also quit using your window manager. If you have data or maps that have not yet been saved to disk, DD will put up a dialog box that warns you about this and asks if you really want to exit. Click on "Stop to Save Data" to abort the "Exit" command, or click on "Exit DD" to exit anyway. 2.3 The Digest Data Window The "Digest Data" window is divided into three sections, of which the bottom one (settings) can be suppressed, leaving only two sections. The top section is the menu bar. It has buttons labeled "Digests", "Save", "Error", and "Other". The middle part is the gel section. It shows a gel with three lanes; an optional standards lane may be shown. A size scale is provided on the right. The name of the data set is shown at the top following the word "Digest:". It is a button. Each lane is labeled at the top, and the labels are also buttons. On each lane of the gel fragments are displayed with error bars, and each fragment is an active button. The fragments in the two enzyme lane have two sets of error bars. When DD is told the data is from the same gel, both sets are shown. The inner ones are used for "same gel" data and the outer ones for data from different gels. When DD is told the data is from different gels, only the error bars appropriate for that situation are shown. At the bottom of each lane the total size of fragments in that lane is shown, together with the minimum and maximum limits of that total consistent with the error. The settings section, if present, shows the default error limits, whether or not DD is treating the data as being from the same gel, the maximum size of unseen fragments for DD to use in fits, and the maximum number of such fragments that DD can use per matched group of fragments. 2.3.1 Digests This button pops up a menu that is used for entering a new data set or choosing one on disk. Data Sets on disk can be chosen from the default directory or any other. 2.3.1.1 Method 1: Graphical Interface. Choose this in order to enter new digest data with the mouse. DD will remind you to save your data to a file before you quit. Name of Lane. Click on the name of the gel lane to add new fragments to that lane (by mouse or keyboard), to change the name of the lane, or to change the default error estimate for that lane. Add New Fragments via Mouse. Choose this to add one or more fragments to that lane with the mouse. Once you choose this option, DD will be in data entry mode for that lane until the pointer leaves the Digest Data window. You can enter as many bands as you want without leaving data entry mode. In data entry mode, DD shows the molecular weight corresponding to the current pointer position at the top of the lane that data is being entered in. Depressing the mouse button places a thin band with no error bars on the lane, but fine scale adjustments to the location of the band are made while the button remains depressed. When the button is released, the band is placed on the gel. The line representing the band becomes thicker and now has error bars. Add New Fragments via Keyboard. Choosing this option brings up a dialog box that allows you to type in the size of a new fragment. Type in the new value, press "Return", and click on "ACCEPT" to enter the new fragment. Between the time you click on the value field and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". If you want this fragment's error range to be different from the default, click on "Set Error Range". You can then select a new error range from the popup menu. Change Enzyme. Choose this to enter a new enzyme name at the top of a gel lane or change the one that is already there. DD will include all the enzymes that have been entered as possible choices. If the one you want is not there, choose "Enter Enzyme Name". A dialog box will come up for you to enter the name of your enzyme. Enter the name of your enzyme, press "return", and click on "ACCEPT". Until you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". Change Size-Estimate Error Ranges. This gives you a menu that you can use to input the error range for the gel lane you have chosen. For details, see 2.3.3.1. 2.3.1.2 Method 2: Type in Values. Use this to type fragment sizes directly from the keyboard. You will get a "Define New Data Set" dialog box, which will ask you for the name of your data set, the name of each of the two enzymes you used, and the error range for the entire gel ("Global Error Range"). Define New Data Set Dialog Box. There are six areas for entering data in this dialog box. One is to the right of "Name:", that is for the name of your data set. Two others are to the right of "Enzyme 1:" and "Enzyme 2:". Those are for the names of these enzymes. Three data entry areas are to the right of "Sizes:". These are for entering the actual fragment sizes. A button, "Set Global Error Range", allows you set the default error range for the whole gel. You type data into all six input areas in the same way. Point at a data entry area. A box appears. Click the mouse. You are ready to enter data. As you type, the letters and numbers appear in a typewriter-like font which tells you which input area is active. When you are done, press "return". The type will go back to the usual DD font. When entering fragment sizes, you can use bp or kb; be sure to separate the fragment sizes by spaces. For certain sizes that make sense as bp or kb, DD may ask you which of these you meant. You can change the data entered in a given field by clicking on it again. When you are done entering data, click on "ACCEPT". Global Error Range. This gives you a menu that you can use to input the error range for the entire gel. For further details, see 2.3.3.1. 2.3.1.3 Loaded Files and Double Digests. This menu choice allows you pick a digest from a file that has already been loaded by DD, or to reload a file after it or the active data set have changed. Each loaded file is shown, followed by an indented list of of each data set in that file. If you choose the filename, DD will pop up a menu and ask which of the data sets in that file you want. Alternatively you can simply choose the desired data set from the indented list. 2.3.1.4 Other Files in Data Directory. This heading on the menu is followed by a list of all of the files in the current directory. Click on a file name to load that file. If DD cannot interpret the file you have selected, it will print an error message. 2.3.1.5 Subdirectories of Data Directory. This heading on the menu is followed by a list of subdirectories (folders) of the present directory. If the datafile you want is in a certain subdirectory, click on its name. A new menu will appear of the files in that subdirectory (folder). Load the file you want or move to a new directory. 2.3.1.6 Move Up Directory Tree. If the datafile you want is in the parent directory (folder) of the current direc- tory, click on this choice. A new menu will appear of the files in the parent directory. Load the file you want or move to a new directory. 2.3.2 Save Use this button to save your data to a file. Together with your data, DD will save all current constraints and error ranges. You can save your data to any file, whether new or previously existing. If the file you are saving to exists, you can append your data to the end of it or overwrite the file. This "Save" button is only for saving data. To save maps, use the "Save" button in the menu bar of the "Maps" window. 2.3.2.1 Save Data in a New File. Choose this to save data to a new file. A dialog box will appear so that you can tell DD the name of the file to save to. Save Data In New File Dialog Box. Enter the name of the file you want to save your data to, press "return", and click on "ACCEPT". The "CANCEL" button won't work until you press "return", so if you've started typing and change your mind, press "return" and then click on "CANCEL". If you enter the name of a file that already exists, DD will complain about your choice and leave that file intact. 2.3.2.2 Append Data to an Existing File. Choose this to save data by appending it to the end of an existing file. Under X11, you have the first two menu choices listed below, while on the Macintosh you get the Mac file dialog box. Contents of Current Data Directory < directory name >. This header appears above a list of all files and subdirectories in the current directory. Files are listed simply by name; subdirectories are listed as a complete path with leading and trailing slashes. Choosing a file name will cause DD to append your data to the end of that file. Caution: DD will not check if the file you are appending to contains valid DD data. If it does not, DD will append the data anyway but may not be able to read it. In that case you will have to edit the saved file by hand. Clicking on the name of a subdirectory will cause a new menu to appear that contains the files and subdirectories in the chosen subdirectory. Save to the file you want or move to a new directory. Move up Directory tree. Moves you to the parent directory. A new menu will appear of the files and subdirectories of the parent directory. Save to the file you want or move to a new directory. Macintosh File Dialog Box. On the Macintosh, you will get the usual Mac dialog box for choosing files. Use it as you would in any other Macintosh application. 2.3.2.3 Replace Data in an Existing File. Choose this to save data in an existing file by replacing the data that is already there. Caution: DD will erase the old data in your file if you choose this. For options, see preceding section 2.3.2.2. 2.3.3 Error This button allows you to control how DD deals with experimental error over the entire gel. You can use this button to set default uncertainty for each band on the gel. You can use it to tell DD that your data came from the same or different gels, so that DD deals with the error accordingly. You also use this button to tell DD the size of the largest unseen fragment that DD can use to make a map, and how many such unseen fragments it is allowed to use per map. 2.3.3.1 Change Size-Estimate Error Ranges. Choosing this gives you a menu that you can use to input the error range for the entire gel. Note that the current range for the whole gel is given. You can give different error ranges for particular lanes by clicking on the name of the lane and for particular fragments on the gel by clicking on them. You can spec- ify error either as fragment size error in %, or as standard deviation. Loosely speaking, standard deviation is an error estimate based on measurement un- certainty of the location of a band on the gel. This estimate is combined with an estimate of likely systematic errors for small fragments to get an overall confidence level for errors. 2.0 standard deviations is our best guess for 95 % confidence limits on a typical gel. 2.3.3.2 Change Basis of Size Comparisons. Use this menu choice to control how error is treated in the two-enzyme digest lane. The current setting is shown in parentheses. There are two possible settings, "Same Gel" or "Separate Gels". Smaller error ranges are used in the two-enzyme lane if the data were from the same gel. If DD is set to "Same Gel", both sets of error bars are shown. The smaller "Same Gel" error bars are closest to the center. This menu choice gets you a submenu that lists both choices. Same Gel. Treat errors for the doubly digested fragments as if all the data came from the same gel. Separate Gels. Treat errors for the doubly digested fragments as if the data came from separate gels. 2.3.3.3 Unseen Fragments: Size Ceiling. Use this menu choice to tell DD the size of the largest undetected fragment on your gel. You might not have detected fragments smaller than this because they ran off the end of the gel or stained too weakly. The current size ceiling is shown in parentheses. Choosing this causes a new popup menu to appear that gives you a choice of possible size ceilings. Size Ceiling Menu (0 bp to 4000 bp). Pick your choice for a new unseen fragment size ceiling from this menu. 2.3.3.4 Unseen Fragments: Number Allowed Per Match. Use this menu choice to control how many undetected fragments DD can use in matching each single digest fragment with fragments from the double digest lane (see 2.6). Choosing this causes a new popup menu to appear that lists the available choices. The current number is given in parentheses. Number of Unseen Fragments menu: (0, 1, 2). Use this menu to pick your choice for the maximum number of unused fragments to be used in each group of matched fragments. 2.3.4 Other Use the "Other" button to tell DD how to display DNA size standards, to ask DD about possible inconsistencies in your data, to control whether the bottom section of the "Digest Data" window is displayed, to rename your digest, and (if you know) to tell DD if your DNA is linear or circular. 2.3.4.1 Choose Lane Standard. Use this menu choice to choose a set of size standards to display. You will get a popup menu that gives the currently available standards as a choice, as well as "None", which removes the standards lane. The currently available standards include lambda HinDIII and BstEII fragments as well as the 1 kb ladder, 123 kb ladder, and high molecular weight markers from BRL. If the standards you use are not on the menu, you can add them. Look for a file called "standards" in the data folder that came with DD. Add your standard in the same format used for the others. Be sure the first line of your standards data reads "dataset: restriction-gel-standard", put the name of your set of standards after "name:", and place the fragment sizes in a column starting on the line following "fragments:". When you are finished, save the file as ASCII text. Be careful not to save it as a formatted word processor file. You can put you definitions in a separate file, and load them using the "Digests" file selection menu, or you can append them to the file named "standards" which is loaded automatically when DD starts up. 2.3.4.2 Drop Lane Standard. Choose this to stop displaying the standards lane, and drop its association with the data set. The other three gel lanes will widen to fill the extra space. It is an available choice only if standards are currently being displayed. 2.3.4.3 Hide/Show Lane Standard. This menu choice turns display of the standards lane on or off, but maintains the association of a standard with the data set. It is only displayed when a standard has been chosen, and reads "Hide" or "Show" depending on whether standards are currently shown or hidden. The other three gel lanes will widen to fill the extra space, or narrow to make room for the standards lane. 2.3.4.4 Critique Current Data. Choose this to check your data for consistency. DD will check that all lanes add up to the same molecular weight (within error limits). DD will also count fragments in the double digest lane compared to the single digest lanes and tell you if the fragment numbers look strange or suggest linear or circular DNA. After you have read the critique, click on "OK". It is a good idea to use this capability of DD after entering a new data set. Data is critiqued automatically after being loaded from a file. Also, data that you have entered will be critiqued automatically when you click on "Make Maps" if it has not been critiqued before or if it has been edited since being critiqued. 2.3.4.5 Hide/Show Settings. Use this menu choice to hide or show the settings section at the bottom of the "Digest Data" window. The gel lanes will expand and use the extra space. Hiding this section is often useful when entering data graphically on a small monitor. 2.3.4.6 Rename Digest. Use this menu choice to rename your data set. An "Enter New Digest Name" dialog box will appear. Type in the name of your digest and click on "ACCEPT". Between the time you bring up the dialog box and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". 2.3.4.7 Set DNA Type. Use this menu choice to tell DD if you know whether your DNA is linear or circular. Choosing this will cause a popup menu to appear with the choices "Circular", "Linear", or both. Choosing "Linear" will constrain DD to find maps with at least one coincidence (common cutting site for both enzymes). 2.3.5 Digest: Click on this button to rename your digest. An "Enter New Digest Name" dialog box will appear. Type in the name of your digest and click on "ACCEPT". Between the time you bring up the dialog box and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". 2.3.6 Gel Lane Title Click on the gel lane title to add new fragments to the lane by mouse or keyboard, and to change error range for that lane. If you click on the title of a single enzyme lane, you can also change the name of the enzyme in that lane. Clicking on the title of the standards lane enables you to choose a different set of standards. 2.3.6.1 Add New Fragments via Mouse. Choose this to add one or more fragments to that lane with the mouse. Once you choose this option, DD will be in data entry mode for that lane until the pointer leaves the Digest Data window. You can enter as many bands as you want without leaving data entry mode. In data entry mode, DD shows the molecular weight corresponding to the current pointer position at the top of the lane that data is being entered in. Depressing the mouse button places a thin band with no error bars on the lane, but fine scale adjustments to the location of the band are made while the button remains depressed. When the button is released, the band is placeed on the gel. The line representing the band becomes thicker and now has error bars. 2.3.6.2 Add New Fragments via Keyboard. Choosing this option brings up a dialog box that allows you to type in the size of a new fragment. Click on the number to right of "Size:". Type in the new value, press "Return", and click on "ACCEPT" to enter the new fragment. Between the time you click on the value field and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". If you want its error range to be different from the default, click on "Set Error Range". You will get the error range popup menu to choose an error range from. 2.3.6.3 Change Size-Estimate Error Ranges. This gives you a menu that you can use to input the error range for the gel lane you have chosen. You can give different error ranges for particular fragments on the gel by clicking on them. For further details, see 2.3.3.1. 2.3.6.4 Change Enzyme (or Lane Standard). Choose this to enter a new enzyme name at the top of a gel lane or change the one that is already there. If you clicked on the standards lane, the choice will be among the available standards. DD will include all the enzymes that have been entered as possible choices. If the one you want is not there, choose "Enter Enzyme Name". A dialog box will come up for you to enter the name of your enzyme. Click on the dialog box, enter the name of your enzyme, press "return", and click on "ACCEPT". Between the time you click on the dialog box and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". 2.3.7 Band on Gel Each band on the gel is also an active DD button that gives a popup menu when clicked. Click on a gel band to find out facts about that band or to assert constraints about the band. You also can click on a band to set its individual error range, to change its size, or to remove it. 2.3.7.1 About Fragment <enzyme, size>. Displays a dialog box that contains basic facts about the fragment, including its size and error range. Click on "OK" to make this box disappear. 2.3.7.2 Assert Constraint. This is the header for an indented list of constraints that you can assert about your data. Each constraint describes a relationship between two fragments, one of which must be a single digest fragment and the other a double di- gest fragment. All possible constraint choices are asserted in the same way. Choose the constraint by clicking on one of the bands. Pick the constraint from the menu. Click on the other band. The new constraint will appear in the constraints window. 2.3.7.3 Identical. Choose this to assert that your fragment is identical with another fragment. 2.3.7.4 Not Identical. Choose this to assert that two fragments are not identical. 2.3.7.5 Bigger Than. Choose this to assert that the fragment you clicked on is bigger than another fragment. 2.3.7.6 Smaller Than. Choose this to assert that the fragment you clicked on is smaller than another fragment. 2.3.7.7 Contains (Part Of). Choose this to assert that the single digest fragment you clicked on contains a particular double digest fragment. If you clicked on a band in the double digest lane, this menu item reads "Part of". 2.3.7.8 Not Contains (Not Part of). Choose this to assert that the single digest fragment you clicked on does not contain a particular double digest. If you clicked on a band in the double digest lane, this menu item reads "Not Part of". 2.3.7.9 Change Size-Estimate Error Ranges. Choose this if you want a particular band to have an error range different from the range selected for the whole data set or for a particular lane. This menu choice allows you to select error range from a menu; for even finer control see "Change Size Data". The error menu is described in 2.3.3.1. 2.3.7.10 Change Size Data. Choosing this option brings up a dialog box that allows you to type in a new size for the fragment you clicked on. You can also set the error range to any values you like. To enter a new fragment size, click on the number to right of "Size:". Type in the new value, and press "Return". To set the error range to your exact specifications, enter the minimum and maximum possible sizes for the fragment after "Min:" and "Max:" respectively, just as you did for the size field. If you want to set the error from the usual menu, click on "Reset Size Range" and choose the error range you want from the menu. If you do this, the minimum and maximum values will be adjusted automatically. Between the time you click on the value field and the time you press "return", the "CANCEL" button won't work. If you've started typing and change your mind, press "return" and then click on "CANCEL". 2.3.7.11 Remove Fragment. Choose this to remove a fragment from the gel. 2.4 The Constraints Window The "Constraints" window displays a list of currently asserted constraints, together with a menu bar with buttons labeled "Add", "Drop",and "Negate". It provides ways to change the existing constraints and add new ones. Each constraint is listed as one line of text in the "Constraints" window. Each constraint is also an active button with a popup menu. 2.4.1 Constraints Each constraint appears as a statement giving a constraint relationship be- tween a single digest fragment and a double digest fragment. Clicking on a constraint brings up a popup menu that allows you to drop or negate that constraint. 2.4.1.1 Drop. Choosing this removes the constraint. 2.4.1.2 Negate (Un-Negate). Choosing this transforms the constraint to its opposite. "identical" becomes "not-identical", and so on. This choice appears as "Un-Negate" if the constraint is in the negative form. 2.4.2 Add Clicking on this button causes a popup menu to appear that lists six possible kinds of constraint you can impose on your data. Each constraint describes a relationship between two fragments, one of which must be a single digest fragment and the other a double digest fragment. All possible constraint choices are asserted in the same way. Choose the constraint by clicking on your choice from the "Add" menu. Click on the first band in the constraint relationship, then click on the second one. The order in which you click makes a difference for constraints other than identical or not-identical, so it is a good idea to look in the window after imposing a constraint to be sure DD got it right. 2.4.2.1 Identical. Choose this to assert that your fragment is identical with another fragment. 2.4.2.2 Not Identical. Choose this to assert that two fragments are not identical. 2.4.2.3 Bigger Than. Choose this to assert that the fragment you clicked on is bigger than another fragment. 2.4.2.4 Smaller Than. Choose this to assert that the fragment you clicked on is smaller than another fragment. 2.4.2.5 Contains (Part Of). Choose this to assert that the single digest fragment you clicked on contains a particular double digest fragment. If you clicked on a band in the double digest lane, this menu item reads "Part of". 2.4.2.6 Not Contains (Not Part of). Choose this to assert that the single digest fragment you clicked on does not contain a particular double digest fragment. If you clicked on a band in the double digest lane, this menu item reads "Not Part of". 2.4.3 Drop Drop a constraint. Click on the "Drop" button, then click on the constraint you want to drop. 2.4.4 Negate Negate a constraint. Click on the "Negate" button, then click on the constraint you want to negate. 2.5 Maps The "Maps" window displays the restriction maps DD makes. It displays them in text, linear, and circular form in ways that you can control. There are buttons across the menu bar, labeled "Make Maps", "Configure", and "Save". The window itself has two buttons at the top labeled "Next" and "Prev", which allow you to page through multiple maps. Below these buttons is a line that says how many maps are in the set and which one is currently displayed. It also shows the goodness of fit of terms of the % of maximum deviation allowed for the error ranges chosen. Below that is a line in small print that describes which fragments are unordered. The rest of the window contains a text map together with a linear and/or circular map. The text map shows fragments labeled by their sizes, with vertical lines for cut sites, and double vertical lines for coincident cut sites. Unordered fragments are grouped by a horizontal line. The linear and circular maps each have three lines, one for each digest. The double digest is in the center, and restriction sites are labeled by vertical tics. Putting the pointer over a fragment causes information about that fragment to appear in the window. 2.5.1 Make Maps Click on this button to tell DD to compute maps. The progress of the compu- tation is shown in the top window. There are two kinds of warning boxes that may come up after you click on "Make Maps". One warns about inconsistency in the data, and another warns that the problem is computationally difficult. 2.5.1.1 NOTE, WARNING or ERROR concerning your data. DD checks every data set for internal consistency before computing maps. If you enter data graphically and do not select "Critique Current Data" from the "Other" menu, DD will do it automatically when you click on "Make Maps". DD will check that all lanes add up to the same molecular weight (within error limits). DD will also count fragments in the double digest lane compared to the single digest lanes and tell you if the fragment numbers look strange or suggest linear or circular DNA. After you have read the critique, click on "Stop to Review Data" if you want to edit your data, or click on "Continue with Current Data" to make maps anyway. The latter option is not offered in case of error (e.g. when no fragments have been entered in one of the lanes). 2.5.1.2 WARNING: This looks like a hard problem. This warning means that DD is likely to find hundreds or thousands of maps. Choose "Stop to Add Constraints" to abort the computation and "Continue Computing" to continue it. Usually it is wise to choose "Stop to Add Constraints". Not only will DD have trouble with the problem, but the answer will not be very useful anyway. If this box appears, it could mean that you need to add constraints. It could also mean that your data is fundamentally ambiguous. In that case, do another experiment! Caution. Choosing "Continue Computing" after this warning can make DD run out of memory and crash. If you wish to choose this, save your data and maps first. 2.5.2 Configure Clicking on this button makes a popup menu appear that allows you to control the format of displayed maps, the format of maps saved to files, and which double digest fragment is displayed at the left end of a linear map or at 12 o'clock on a circular map. 2.5.2.1 Change Map Display Format. Choose this to change the format with which maps are displayed in the "Maps" window. Text and Linear Only. Display text and linear maps only. Text and Circular Only. Display text and circular maps only. Text, Linear, and Circular. Display all three map formats. 2.5.2.2 Change Map File Output Style. Choosing this brings up a dialog box that you can use to control the format with which maps are saved to disk. The current setting for file format is shown in heavy black. Below it are three buttons for your possible choices. Click to choose. You can save your map as ASCII text, postscript graphics, or postscript text. If you are saving your maps in postscript, you can also choose whether to save it in monochrome or color. When you are happy with your choices, click on "SET FORMAT". Click on "CANCEL" to leave these settings as they were. 2.5.2.3 Anchor a Double Digest Fragment in Left/12-O'Clock Position. Choosing this allows you to choose the first double digest fragment displayed on the map, starting at the left end or clockwise from 12 o'clock. A popup menu will appear listing your double digest fragments. Click on the one you want. 2.5.3 Save Choose this button to save one or more maps to a file or to change the format in which maps are saved. With the exception of choosing a file format, all of the subtopics here follow exactly those under the "Save" button in the "Digest Data" window. See 2.3.2 for detailed headings. 2.5.3.1 Change Map File Output Style. Choosing this brings up a dialog box that you can use to control the format with which maps are saved to disk. The current setting for file format is shown in heavy black. Below it are three buttons for your possible choices. Click to choose. You can save your map as ASCII text, postscript graphics, or postscript text. If you are saving your maps in postscript, you can also choose whether to save it in monochrome or color. When you are happy with your choices, click on "SET FORMAT". Click on "CANCEL" to leave these settings as they were. 2.5.3.2 Save All Maps to File. Choose this to save all of the maps you made for the currently selected digest to a file. For a discussion of options for saving to file, see section 2.3.2. 2.5.3.3 Save Current Map to File. Choose this to save the current map to a file. You can put it in a new or existing file. For an existing file, you can append the map or replace the contents of the file with the new map. For a discussion of options for saving to file, see section 2.3.2. 2.6 Match Details This is an optional window. It shows details of the calculations that DD makes to find maps. It has a menu bar across the top with buttons labeled "Possibilities", "Constraints", "Compatibility", "Sets", "Maps", and "Close Window". "Close Window" removes the "Match Details" window. Each of the other buttons tells DD to take its map making calculation to the particular stage described by that button (see below). There are three subwindows in the main window. The top two list the number of possibilities DD is considering for each enzyme on a fragment by fragment basis at each stage of the calculation. Each number of possibilities is itself a button. Clicking on it causes the possible matches to appear in a third subwindow at the bottom. Placing the pointer on one of these possible matches causes further information to appear on the top subwindow of the main DD window. We briefly outline how DD makes its calculations, noting in parentheses the name of the button that takes DD to that particular stage. DD first cal- culates all possible ways that each single digest fragment can be built up from combinations of double digest fragments, allowing for both the current error ranges and the possibility of small undetected fragments ("Possibilities"). In the next step, DD eliminates any of these that are not compatible with constraints that you imposed ("Constraints"). Next, DD eliminates ways of building single digest fragments from double digest fragments that are in- ternally inconsistent ("Compatibility"). For example, if a particular double digest fragment is always needed to build one of the single-enzyme fragments, no other fragment from the same single-enzyme lane could be built using that double-digest fragment. Internally consistent sets are then constructed for each single-digest lane, using each double digest fragment once ("Sets"). Finally, these sets are merged to form summary maps ("Maps"). For further details, contact the program's author directly (details at end of manual). Chapter 3. Installation and Internals DD is written in the Common Lisp programming language. The graphical interface uses the Common Lisp Interface Manager (CLIM), an emerging stan- dard for portable graphics supported by all the major Common Lisp vendors. It should be fairly easy to configure and run DD on any computer for which Common Lisp and CLIM are available. CLIM is currently available for X11, Macintosh, Microsoft Windows and Genera systems. In practice, we have been developing and testing it on two systems: Macin- toshes using Macintosh Common Lisp and CLIM, and Sun Sparcstations using Lucid Common Lisp and CLIM. The configurations used for development and testing are indicated below; due to the many possible variations in hardware and software, we can only say we do not yet have reports of models, window managers, etc. with which DD won't work. Those interested in running it on other computer systems should contact us directly. 3.1 Macintosh 3.1.1 Installation If you obtained a copy of DD whose filename ends in ".hqx", you need to "unbinhex" it, using one of the programs (such as CompactPro or Stuffit) which do this. The result will be a file ending in ".sea", short for self extracting archive. Click on this file, and it will ask you to specify a destination folder in which to extract the archive's contents. Clicking on "Extract" will create a "Double Digester" folder in the location you selected. In this folder you will find the application, "Double Digester", and a folder called "data", containing files with sample double digest and gel standard data. The DD application occupies about 2.8 MB of disk space, and requires about 5 MB of memory to run. If you give DD more memory (using "Get Info" from the "File" menu to change the "Current size" setting before you run DD), it will be able to deal with more and/or harder digests before it runs out of memory. If this requires running in virtual memory, however, DD will run very much slower than if it can run entirely in built-in memory (select "About This Macintosh" from the Apple Menu to find out about your machine). When DD starts up, it looks in the folder from which it started for a folder named "data"; it will use either this or its startup folder as the default folder for reading and writing files (this is resetable from the "Configure" menu). If you save maps in postscript format, you will need to print them using a program which can send postscript files to a printer. For System 7, you can use the "LaserWriter Utility" that comes with it, by selecting the "Download you will need a program such as "SendPS". 3.1.2 Troubleshooting If DD is unresponsive, and is not in the middle of calculating or saving maps, it may be waiting for input. You can select "Windows" from the Macintosh menu bar to see if there are any popup windows which may have become buried, and check the top window for any messages indicating DD is waiting for something. Alternatively, you can simply hit the "Command-." key combination to abort any pending process and return to normal interaction; this is always safe to try. The current version of DD has been tested on the following typ es of Mac- intosh: MacIIx, MacIIfx, Quadra and PowerBook. It has run on monochrome, grayscale and 8-bit color displays. DD runs under both System 6 and System 7. If you have problems with normal running of DD, try running it without any desk accessories active (we do not know of any conflicts, but this is a common source of problems on the Macintosh). 3.2 Unix and X11 3.2.1 Installation If you obtained a copy of DD whose filename ends in ".tar.Z", you will need to "uncompress" it and then extract the contents of the resulting tar file. The simplest way to do this is: zcat double-digester.tar.Z _ tar xvf - which will create a directory called something like "dd-1.1", containing the application "double-digester" and a "data" directory with sample double digest and gel standard data. The DD application occupies about 12MB of disk space, and uses about 24 MB of memory (physical or swap) to run. You will probably need at least 40 MB of swap space, preferably 50 MB or more, to allow for windowing and other software on your system. If you need more swap space, you or your system administrator might want to consider using swap files as an alternative to reconfiguring disks (cf. man pages on mkfile and swapon). When DD starts up, it looks in your current working directory for a sub- directory named "data"; it will use either this or your current directory as the default directory for reading and writing files (this is resetable from the "Configure" menu). 3.2.2 Troubleshooting If DD is unresponsive, and is not in the middle of calculating or saving maps, it may be waiting for input. You can look to see if there are any dialog boxes or menus around (menus under X11 should disappear when buried), and check the top window for any messages indicating DD is waiting for something. You can next try hitting the interrupt key (often "Control-C") to abort any pending process and return to normal interaction; this is always safe to try so long as keyboard input is directed to the DD window. If this doesn't work or you want to terminate a long computation, you can direct it to the window from which you started DD, and then choose an appropriate restart option (normally ":A" or the number - probably "2" or "5"- preceding the words "Double Digester top level"). Appropriate keyboard input to DD is always directed to a dialog box, not the main window. Nevertheless, if you do type at the keyboard and press "return" when the input focus is directed to the main window of DD, the line typed at the keyboard will sometimes appear at the top left, over the menu bar of the main window. When the line first appears, the machine beeps. When the pointer is moved across the DD main window, the text will disappear. It will reappear again when the window is resized, but vanish again when the pointer is moved. This is a bug. Moving the pointer is a much more common operation than resizing, and hence it is easy to work around this problem. The current version of DD has been tested on a Sun SparcstationII running OpenWindows 3.0 with 32 MB of memory, and on a Sparcstation ELC with 24 MB of memory running OpenWindows 2.0. Remote display on a HP9000/370 workstation using the Motif window manager, and on a Macintosh running a MacX server, has also been tested. A previous version was also built and run on an HP9000/370 with 16MB of memory, using Lucid Common Lisp and CLIM under X11R4 with Motif. 3.3 All Versions 3.3.1 Error Recovery If DD runs out of memory or encounters some other serious problem, it should provide a warning that it has hit an internal error. It gives a countdown of how many more times it will attempt to recover, to avoid infinite loops, and then attempts to return to a state which allows you to save your data and maps. Be sure to immediately save any data and maps (probably best in that order) which are important to you: while you might be able to continue working normally, problems such as running out of memory are likely to recur soon. 3.3.2 Memory Management DD frees memory whenever it can. This process is called "garbage collection". On the Mac, it is happening whenever the usual cursor disappears and is replaced with a "GC" cursor. On the Sun, DD prints a message in the window it was started from that begins ";;; GC:". With typical problems that do not elicit a complexity warning (see 2.5.1.2), DD should always have plenty of memory. There is one possible exception to this: DD can run out of memory if a large enough number of data sets are mapped. The reason for this is that DD saves all relevant information for each data set, including constraints, all error information, and intermediate results. This allows you to switch between data sets without having to recalculate results, but it also means that DD tends to fill up its memory as you use it repeatedly. If garbage collection is beginning to occur frequently, save your data and maps and restart DD. When DD saves a data set, it saves all standards, constraint and error information, so you can regenerate all maps from saved data. 3.3.3 Saving Large Map Files If you save maps in postscript format, they can use large amounts of space. DD warns you about this if you select the postscript output option with more than 10 maps, but does not do so otherwise, nor does it attempt to find out whether enough space exists to write them out. If you want to check how much disk space a set of maps will take, simply choose the "Change Map File Output Style" option on the Maps "Save" menu, and reselect postscript output. 3.4 Further Information and Suggestions For additional information, to report bugs, or to suggest things you would like to see included or changed, contact DD's author: Lawrence Wright Medical Informatics Center 3 TMP - Anesthesiology Yale School of Medicine New Haven, CT 06510-3333 Phone: (203) 785 7453, 785 2802 FAX: (203) 737 2243, 785 6664 INTERNET: wright-lawrence@yale.edu BITNET: wright-lawrence@yalecs.bitnet UUCP: yale!wright-lawrence