JAMF Archive

BioCompanion as published in 1995

THIS IS THE REFERENCE CODE AS PUBLISHED.

		Doelz, R.   
		Optimal production of biological documentation: the JAM format.
		Comput. Applic. Biosci. 11, 224-226 (1995).

The version you are currently viewing is the one printed and distributed via the Internet from the server of BioComputing Basel. Version 3.1 of the BioCompanion was published with version 2 of the JAMF software. The server that was indicated in the documentation has ceased to exist.

Version 3.2 of the BioCompanion was not publicly available for free but was shareware that was distributed with GCG's software release 9. For the purpose of enhanced editing, JAMF was partially rewritten and the proprietary version 3.x of JAMF was used from 1996 onwards. The Biocompanion is available in a current version from the publisher . It has significantly changed both in software and content.

JAMF source code

LATEX version source code

location: Home > Archive > BioCompanion V2.x (1995)

Chapter 4: GettingStarted

Getting Started

Standard Environment

Material and Methods

NOTE: The following instructions make use of software packages which are copyrighted or licensed by software providers and need to be purchased and installed separately. If you start the program package's environment, or review the program's output file, you will find the corresponding copyright and acknowledgement notices. It is of all user's interest that these notices are carefully read and kept in mind in order to grant honours to those who deserve it.

NOTE: The following instructions make use of databases which are usually placed in the public domain. The rate of updates is steadily increasing. Make sure that you always use the latest database version you can get hold of. Remember to check with your software manager what the latest database release or description was if you publish data referring to sequence databases.

NOTE: The programs and data are brought to you by people who work hard to get you the best quality and performance. These installations are not free of cost, even if you might not need to pay fees directly. It is required that you acknowledge these organisations properly in publications in order to ensure their future funding.

Setup of the Text Screen

The standard environment in the past was a text terminal or screen on a suitable equipment (PC, etc.) which displayed text on an area of 80x24 characters. Depending on the properties of the equipment attached to the screen or the capabilities of the program, it may be impossible to visualise graphics on the screen. If you are afraid that this is the case, contact your system or site manager for details. The most common types of text screens are called vt100-type screens.

If your screen behaves strangely ( "unknown terminal" or similar messages) refer to the section "Common Problems" in order to set the required parameters correctly.

Using X-Windows across the Network

NOTE: The following does not need to be configured if you use a text-oriented display.

If you use local area networks , it is possible to send windows across the (local) network. The procedure required to do this is called X-Windows and is explained in detail in the appendix.

You can run X-Windows graphics on a terminal or computer other than the host where the corresponding molecular biology programs have been started. To do this, you must tell the host you are logged in to send the graphics window to your terminal or computer, i.e., you must know the name or IP address of the terminal or computer where you want to display the graphics. The variable which the host needs to know is called DISPLAY:

$ set display/create/transport=tcpip/node=host.domain.country

Example:

 
  
$ set display/create/transport=tcpip/node=biomac.embnet.unibas.ch

TCP/IP is an optional product for the VMS operating systems and needs separate installation and configuration by the system manager. If the command above does not work, contact your system manager. Refer to the appendix for prerequisites of this configuration when using personal computers. Depending on your setup, X-Windows applies a security procedure which restricts the sending of windows around the world. Therefore, you must "allow" your terminal or computer to display the window on your screen (as described in section "Common Technical Problems" ). If this is not the case, the error message is

 
  
Cannot open display

Refer to the section "Configuration Problems" to escape from this situation.

Calling the GCG Setup Program

You must register your user name before you can start to work with the GCG package. If you use GCG for the first time, you must install the proper procedure:

$ @d$biogen:[biozen]installation

NOTE: This procedure is required only once, and only if you start with a new account.

The startup of the GCG environment is usually performed with a single command:

$ gcg

There are occasionally different commands to start the GCG environment. In Basel, the environment is started with the following command:

$ query

The startup procedure will display the GCG banner and quotation information for the GCG package. Additionally, local database information is displayed. The details of database use and quotation are described later .

NOTE: The command will fail if the account initialisation has not yet been done for you. Ask your program manager for details.

You should see the following or similar startup logo:

 
  
                     Welcome to the WISCONSIN PACKAGE  
                      Version 8.1-UNIX, August 1995  
  
                             Installed on OSF  
  
  Copyright 1982, 1983, 1984, 1985, 1986, 1987, 1989, 1991, 1992, 1994, 1995  
            Genetics Computer Group, Inc.  All rights reserved.  
  
         Published research assisted by this software should cite:  
  
                 Program Manual for the Wisconsin Package,  
            Version 8, September 1994, Genetics Computer Group,  
             575 Science Drive, Madison, Wisconsin, USA  53711  
  
              Databases available:  
                   GenBank            Release 89.0 ( 6/95)  
                   EMBL (Abridged)    Release 42.0 ( 3/95)  
                   PIR-Protein        Release 44.0 ( 3/95)  
                   SWISS-PROT         Release 31.0 ( 3/95)  
                   PROSITE            Release 12.2 ( 3/95)  
                   Restriction Enzymes (REBASE)    ( 6/95)  
  
               Help is available with the command % genhelp or by  
            calling (608) 231-5200 or sending e-mail to Help@GCG.Com

If you have the EGCG package (by P.Rice et al.) installed on your computer, you can use these programs in addition to the GCG software. The following or similar logo will appear if you have setup the EGCG environment with

$ egcg

 
  
            Welcome to the EGCG extensions to the WISCONSIN PACKAGE  
                       Version 8.0-beta-0.0, July 1995  
                             Installed on IRIX  
  
   Copyright 1982, 1983, 1984, 1985, 1986, 1987, 1989, 1991, 1992, 1994  
            Genetics Computer Group, Inc.  All rights reserved.  
  
      Published research assisted by this software should always cite:  
  
                 Program Manual for the Wisconsin Package,  
              Version 8, August 1994, Genetics Computer Group,  
             575 Science Drive, Madison, Wisconsin, USA  53711  
  
                   and also for the Extension programs:  
  
        Program Manual for the EGCG Package, Peter Rice, The Sanger Centre,  
                  Hinxton Hall, Cambridge, CB10 1RQ, England.  
  
         Additional code by Peter Rice, The Sanger Centre, Hinxton, England  
                    and other members of the EGCG team.  
  
        Other Databases available :  
        (Quick Index of) EMBL   Release 43.0 (06/95)   
        (Quick Index of) EMNEW  Release 44.0  
  
               Help is available with the command % egenhelp

Wisconsin Package Interface

Purpose of WPI

The Wisconsin Package Interface (WPI) is a windowing environment layered on top of the command line interface used so far with GCG. In contrast to personal computer windowing systems, which use Microsoft Windows or the Macintosh Finder to display windows, WPI uses the so-called X-Windows system to send data from the host computer to your display. Therefore, you need an X-Windows display, such as an X-terminal, an X-server running on a microcomputer, or a workstation that runs X-Windows, if you want to use WPI. You may have used X-Windows already to display GCG graphics on the screen. As in the GCG command line version, WPI graphics can be produced on various output devices such as printers, plotters and the screen.

WPI is neither a replacement for GCG, nor does it offer programs which are not available in the GCG command line version. WPI adds the convenience of window-oriented software usage. WPI does not change or alter the way how results are produced by the GCG package.

IMPORTANT NOTE: To run WPI, your PC or Mac must be connected to the campus network and run sufficiently fast. A colour screen of at least 16 inch and high resolution is recommended. Personal computers running X-Windows are known to require well more than 8 MByte of RAM.

WPI Details: The Concept of "Lists"

In contrast to the GCG command line interface, WPI allows you to define and store the set of sequences you want to work with. I.e., you no longer need to remember which sequence files are of current interest. WPI will collect sequence files for you when you 'add' them to the list. If you start WPI for the very first time, this list is empty. The pull-down of the menu 'Sequence' allows you to 'Add' sequences to the list from either

'Database Sequences': sequences which are stored centrally

'Sequence Files': local sequences available in your directories

'Adding' sequences to the "main list window" neither alters sequences nor changes their location. The purpose of 'adding' sequences to the list is just to register the sequences within the WPI interface to utilise them more easily.

More WPI Details: The Concept of an "Output Manager"

With the GCG command line version, you type the name of a program, feed it with parameters, and wait for the completion of the program. In contrast, WPI allows you to continue to work while another program is running in the background. This is different from the 'batch' option. The programs are executed like the ones you started by typing the command. In a way, WPI does the command typing for you. There are several types of output:

Text files which can be utilised for further processing (e.g., 'fasta' output from a sequence search)

Text files which are not meant for further processing (e.g., the result from a 'composition' calculation)

Graphics files or intermediates of graphic files (e.g., a 'dotplot', or the output from a 'compare' run to be fed to 'dotplot' later)

Sequence files (e.g., from a 'translate' run)

The results may be viewed or processed according to their character, e.g., a graphics file can be plotted as a figure, and a list of file names can be added to the "main list window". The "output manager window" allows you to trigger these actions, including deletion and other file handling commands.

Even more WPI Details: The Concept of a "Job Manager"

Instead of waiting for a result, WPI allows you to continue to work while another program is running in the background. The "job manager window" lists the execution status of all the jobs that you have started. Programs running in the background may generate output, in particular if they do not run as expected. Error messages are displayed in the "job manager window".

Interaction of WPI Windows

WPI allows you to have more than one window open. Instead of sequentially opening and closing all the windows, you should try to keep at least the "main list window" and the "output manager window" open simultaneously.

Starting WPI

Given the proper configuration of the environment , it is sufficient to type

$ spawn/nowait WPI

WPI can be configured in a sophisticated fashion. In contrast to the GCG command line interface, WPI uses so-called "sets" of sequences which hold additional data such as start/end and other information.

If you plan to use WPI in parallel to the GCG command line interface, it is important to remember two important items:

Resources: Scratch files and all additional flexibility of operation require large resources. This may become a problem if disk quota are handled with the usual constraints. Before you start to work with WPI, make sure that you have enough free disk space, etc. Ask your program or system manager for details. Refer to the section "Problems Caused by User" for details.

Synchronisation: You must remember that there is no automatic update of WPI sets if you alternatively use the GCG command line interface and the WPI. If you configured a set in WPI with a defined begin/end setting, and then use the command line sequence editor to change the sequence length, the begin/end settings will no longer be identical.

================================= Begin Exercise 1

A small WPI exercise: Run a 'fasta' search of a database sequence against the SWISSPROT database.

Proceed as follows:

'add' the sequence CALM_HUMAN from the SWISSPROT database

run the program 'fasta' with the default settings

view and print the result output

================================= End Exercise 1

WPI and the User

Small Computer Screens and WPI

If you feel that the screen of your personal computer is too small, you can either configure your X-Windows server program to display scroll bars or start WPI with smaller characters (recommended) to get a smaller window size. The latter can be done by typing

$ WIP/small

WPI Timing

The option to run jobs in the background may affect the timing of your session. WPI itself will time out if you do not work for an extended period of time, i.e., you need to restart WPI after returning from lunch or similar elongated pauses. At some sites system managers have configured a time out for idle sessions on the entire computer system. If you did not save your current list in the "main list window", this list will be lost if your session times out. Therefore, better save your working list occasionally.

Setup of the GCG Plotting Environment

... Using WPI

WPI automatically displays graphics on the screen. If you want to recapture graphics, open the "output manager window" and select either the print or display option button. Depending on your site, various devices will be configured.

NOTE: WPI output files can become very large easily. Make sure to have enough disk space or quota if you produce many plots or delete them frequently. WPI deletes files only if selected.

Plotting Setup from the Command Line Using the 'setplot' Utility

$ setplot

If you issue the command 'setplot', you get a menu which allows you to choose from different options. Remember that the GCG package can either display graphics on the screen or print them on a printer. It is usually not possible with the default configuration to do both simultaneously. The typical cycle of commands, therefore, is

 
  
setplot  (-> set output to display device)   
program  (-> run program first time and display result)   
program  (-> rerun program if you need to optimise output)  
...      (rerun program, or other programs, as often as you need)   
setplot  (-> set output to printer)   
program  (-> generate hardcopy output)   
setplot  (-> reset output to display device)  
...

Plotting Setup from the Command Line Using Generic Commands

If the command 'setplot' is not supported at your site, the following graphics drivers will be important. There are more available, ask your program manager for details. The setup is performed by typing one of the following commands:

 
  
regis       for DEC terminals   
tektronix   for many kinds of graphics, including terminals and PCs   
hpgl        for Hewlet-Packard devices   
postscript  for postscript devices  
xwindows    for X-Windows

Verification of the Plotting Environment

To verify that your environment is setup and working properly, give the command

$ plottest

Make sure that you are close to the printer when you try to print the plot test for the first time. In the worst case, the graphics output is misconfigured and the printer spits out paper like mad. Refer to section "Need to Stop a Print Session" to stop a misguided output.

Computer On-Line Documentation

Frequent commands for things like file editing, printing, etc. are explained on the computer in 'on-line', i.e., electronic documentation. The command 'help' will give you a list of keywords. To select a topic, type its name and <RETURN>. To leave 'help', type repeatedly <RETURN> until you are back at the $ prompt.

$ help

GCG has a comprehensive introduction for new users on various operating systems (see below).

GCG On-Line Documentation (Command Line Version)

The GCG package provides two different help functions, which operate like the VMS 'help' (even on UNIX). To request a topic, type the following command and the name of the topic you would like to get help on.

$ genmanual

This will give you a topic-sorted list of keywords. To select a topic, type its name and <RETURN>. To leave 'help', type repeatedly <RETURN> until you are back at the operating system prompt.

$ genhelp

This will give you a list of the GCG programs. To see information on a program, type its name and <RETURN>. To leave 'help', type repeatedly <RETURN> until you are back at the operating system prompt.

NOTE: If the selected program was not optimal, refer to the topic "related programs" which may suggest alternative programs.

Detailed Information on each Program

The command qualifier 'check' allows you to check command options on the fly and add as appropriate. For example, try the command line version of 'fasta' as follows:

$ fasta /check

GCG further provides helpful information for new users under the topic NEW USER .

GCG On-Line Documentation (WPI Version)

The GCG package provides two different help functions, which are structured like the VMS 'help'. To request a topic, use the <help> button in the current window. A new window will open, and you can read the text in the upper area. The lower third of the window offers a list of subtopics which can be selected for more information. In WPI a new window will open for each command to execute. More detailed command options can frequently be called with the <options> button.

ATLAS On-Line Documentation

To get help in the ATLAS program, type "help" at the

ATLAS>

prompt.

SRS On-Line Documentation

To get help in the SRS program, type a question mark (?) if you use the VMS version of the program. The UNIX version does currently not support on-line help.

Network Help

Depending on your facility, the access to the international networks, or the availability of the tools described in this chapter, may be restricted. The electronic network can be of great help when asking for information in the user community. One system, called USENET NEWS, is available at most academic sites. Its principle is that of an exchanging bulletin board. I.e., you 'post' something and this can be read by all others due to the replication mechanism of the system. A certain discipline should be adhered to in writing messages (so-called netiquette). In biology, many NEWS groups of interest are also available as electronic mail exploder lists. This means that you can interact with thousands of people via electronic mail.

USENET NEWS

NEWS is a program which must be installed on your computer to allow you to read the messages. It is available in various flavours, the most common one is described below.

The command 'help news' will give you informtion on the NEWS program (see previous sections for on-line help). To start NEWS, you may need to enter commands to setup the correct environment, e.g.,

$ getsym news

Then, start the program with

$ news

The screen will show a list of so-called newsgroups. To select one, move the cursor to the place of interest and hit <RETURN>. If you type register afterwards, the next time you start up NEWS it will automatically show you only those groups which you registered in. If you want to see all of them again, type 'news' at the

NEWS>

prompt. Type 'help' to get more information.

BIOSCI BULLETIN BOARDS

The bulletin boards of USENET NEWS are also available as electronic mail. To send and receive mail, refer to the section about mail servers . To subscribe to a group, you must first obtain the address of the group and information on the procedure of subscription. DO NOT SEND MESSAGES TO THE GROUP if you want to subscribe. Read the Frequently Asked Questions (FAQ) sheet below.

Frequently Asked Questions

The following article is available either via the network or in printed form:

 
   
Smith, Una R. (1993) "A Biologist's Guide to the Internet."

This article summarises most of the questions asked in networking together with the appropriate answers. It is published monthly in the USENET newsgroups sci.bio, bionet.general, and news.answers. The document is also available via 'anonymous ftp' as file "biology/guide" from the server pit-manager.mit.edu (approx. 20 pages).

Printed Documentation

All software described in this book is also documented in written form. Ask your manager or software consultant for ways to get the documentation printed. GCG documentation is mostly stored on-line as postscript file documentation for printing individual chapters. Ask your colleagues or your manager on how to print this documentation. This guide, if you read it electronically, is also available in printed form. If you have it printed, you may also want to see it on the screen.

 
  
	SAVE TREES.	  
          
        THINK OF OUR WOODS. 	  
  
        DO NOT PRINT DOCUMENTATION IF YOU DO NOT INTEND TO READ IT.

Human Help

Local help implies that you need to ask someone. This "someone" can be one of your colleagues, the person who maintains the GCG package, or the local computing centre. You need to find out who is the best person to talk to - if you use the printed version, write it down here:

 
  
Name        _____________________________________  
  
Telephone   _________________    FAX  __________________  
  
Opening hours (Mo Tu We Th Fr) mornings _____  afternoons ______  
  
Mail address ______________________________  
  
Snail mail address _________________________________  
         
                   _________________________________  
                     
                   _________________________________

JAM produced file: GETTING4.HTML as [next page] , or [overview] , or [table of contents]