gde_linux/CORE/xylem/features.doc

      FEATURES.DOC                                          update  7 Feb 94


      NAME
            FEATURES - extracts features from GenBank entries
      
      SYNOPSIS
            features
            features expression
            features [-f featurekey | -F keyfile]
                     [-n name     |-a accession    | -e expression |
                      -N namefile |-A accfile      | -E expfile]
                     [-u dbfile   | -U dbfile      | -g ] 
            features -h     

      DESCRIPTION
            FEATURES extracts sequence objects from GenBank entries, using
            the Features Table language. Features can be retrieved either by 
            specifying keywords (eg. CDS, mRNA, exon, intron etc.) or by 
            evaluating expressions. In practical terms, FEATURES is actually
            a user interface for GETOB, which actually performs the parsing
            and extraction of sequence objects. FEATURES can be run either as 
            an interactive program or with command line arguments.

            'features' with no arguments runs the program interactively. 
            'features' followed by an expression retrieves the data directly
            from GenBank and evaluates the expression. The third form of 
            features requires all arguments to be accompanied by their 
            respective option flags. Finally, 'features -h' prints the
            SYNOPSIS. 
     
             
      INTERACTIVE EXECUTION
      FEATURES executed with no arguments runs interactively. An example of the 
      FEATURES menu is shown below: 

      ___________________________________________________________________
                           FEATURES - Version    7 FEB 94                
          Please cite: Fristensky (1993) Nucl. Acids Res. 21:5997-6003
      ___________________________________________________________________
      Features:  tRNA
      Entries:   EPFCPCG
      Dataset:  
      ___________________________________________________________________
         Parameter              Description                      Value
      -------------------------------------------------------------------
      1).................... FEATURES TO EXTRACT ....................> f
        f:Type a feature at the keyboard 
        F:Read a list of features from a file
      2)....................ENTRIES TO BE PROCESSED (choose one).....> n
        Keyboard input - n:name     a:accession #     e:expression
        File input     - N:name(s)  A:accession #(s)  E:expression(s)
      3)....................WHERE TO GET IT .........................> g
        u:Genbank dataset   g:complete GenBank database
        U: same as u, but all entries
      4)....................WHERE TO SEND IT ........................> a
        s:Each feature to a separate file  a:All output to same file
        ---------------------------------------------------------------
         Type number of your choice or 0 to continue:
      0
      Messages will be written to EPFCPCG.msg
      Final sequence output will be written to  EPFCPCG.out
      Expressions will be written to EPFCPCG.exp
      Extracting features...

      In the example, FEATURES was instructed to retrieve all tRNAs from
      the GenBank entry EPFCPCG, which contains the Epifagus plastid
      genome. By default, the GenBank database was the source of the
      sequence. Messages indicate the progress of the job. A log describing
      the extraction of each feature is written to EPFCPCG.msg, while the
      extracted features themselves are written to EPFCPCG.out. Feature 
      expressions which could be used by FEATURES to reconstruct the .out
      file, are written to EPFCPCG.exp. 

      The first step is to retrieve the EPFCPCG entry from GenBank, which is
      accomplished by calling FETCH. Next, FEATURES extracts the specified
      features from the entry.
      
      An excerpt from EPFCPCG.msg is shown below, describing the extraction
      of the fifth tRNA found in this entry. To create this tRNA,  two exons
      had to be joined. The qualifier line associated with this feature 
      indicates that it is an Isoleucine tRNA with a gat anticodon.


      EPFCPCG:anticodon gtg
          complement     
              (
                  join           
                (
                           70023                         70028

                           1                         69

                      )

              )


      /product="transfer RNA-His"
      /gene="His-tRNA"
      /label=anticodon gtg
      /note="anticodon gtg"
      //----------------------------------------------

 
	 The actual sequence for this feature, as written to EPFCPCG.out, is
	 written with each exon beginning a new line:

      >EPFCPCG:anticodon gtg
      ggcggatgtagccaaatggatcaaggtagtggattgtgaatccaacatat
      gcgggttcaattcccgtcg
      ttcgcc

      Finally, the expression that was evaluated to create this feature is 
      written to EPFCPCG.exp:

      >EPFCPCG:anticodon gtg
      @M81884:anticodon gtg

      If EPFCPCG.exp was used as an expression file in option 2 (E) of FEATURES,
      EPFCPCG.out would be recreated.
 
      OPTIONS
      1) FEATURES - choosing f will cause FEATURES to prompt for
	 a feature to extract. If you wish to extract several types of
	 features simultaneously (ie. F), you must construct a file listing the
	 feature keywords. The following example would retrieve both tRNA and
	 rRNA sequences:

	 OBJECTS
	 tRNA
	 rRNA
	 SITES

      The words 'OBJECTS' and 'SITES' must enclose the feature keywords,
      and each keyword must be on a separate line. For a rigorous
      definition of the input file format, see the GETOB manual pages
      (getob.doc).
      
       In the menu shown above, f was chosen, and the user entered tRNA at
       the prompt. Thus tRNA is now displayed on the Features: line. If
       features had been specified from a file (suboption F) then the
       filename containing the feature keywords would be displayed instead.
       A complete list of legal feature keywords can be found in the GenBank
       Release notes (gbrel.txt) under the subheading 'Feature Key Names'.

	 2) ENTRIES    
         n  User is prompted for the name of an entry from which the
	    feature is to be extracted. The name of the entry will appear
	    on the 'Entries' line of the menu.

	 N  User is prompted for a filename containing one or more
	    entry names. Each name must be on a separate line. The filename
	    will be displayed on the 'Entries' menu line.

         a  User is prompted for an accession number, which will appear
	    on the 'Entries' line of the menu.

         A  User is prompted for a filename for accession numbers. The filename
            will appear on the 'Entries:' line.

         e  User is prompted for a GenBank Features expression of the
	    form  accession:location.'accession' refers to a GenBank 
	    accession number, while 'location' is any legal feature location.
	    A brief description of location syntax can be found under the
	    subheading "Feature Location" in the GenBank release notes
	    (gbrel.txt). See "The DDBJ/EMBL/GenBank Feature Table:
	    Definition" Version 1.04 for a complete definition.
         E  User is prompted for a filename containing one or more Feature
	    expressions. EACH EXPRESSION MUST BEGIN A '@'. All lines beginning
            with '@' are processed as expressions, and all other lines are
            copied to the output file unchanged.

         Examples:

	    The tRNA shown above could have been extracted by choosing
	    suboption e and entering either of the following expressions:

            M81884:complement(join(70023..70028,1..69))
            M81884:anticodon gtg

	    In the first example, the feature line from the original entry
	    is used as the location. In the second example, the feature is
	    found by its qualifier line, which also appeared in the
	    original entry. It must be noted that the qualifier line must
	    be unique from others in the same entry in its first 15
	    characters after the = . 

	    The flaL protein coding region of B. licheniformis is described
	    in GenBank entry BLIFALA, accession number M60287 in the
	    following feature:

            CDS             305..640
                            /note="flaD (sin) homologue"
                            /gene="flaL"
                            /label=ORF2
                            /codon_start=1

         This feature could be retrieved using any of the following
         expressions:

		 M60287:305..640
		 M60287:ORF2
		 M60287:/label=ORF2
		 M60287:/gene="flaL"
		 M60287:/note="flaD (sin) homologue"

           Note  that the /label= qualifier is special, in that labels are
           specifically intented as unique tags on an feature. For labels,
           only the label itself is need be specified. Thus, /label=ORF2 is
           equivalent to ORF2.  For other qualifiers, the qualifier keyword
           (eg. /note=) must be included. 

	 3) DATABASE (WHERE TO GET IT) - By default, all entries processed will
	 be automatically retrieved from GenBank using FETCH. Specifying 'u'
	 (User-defined database subset) makes it possible to extract features
	 from GenBank subsets created by the user. Usually, retrieval of
	 features is much faster with a User-defined subset, so if you
	 frequently work with sets of genes, it is best to retrieve them
	 en-masse using FETCH, and work with them directly. For example, if
	 you had retrieved a set of Beta-globin sequences into a file called
	 'globin.gen', you could directly extract features from these entries
	 by specifying 'globin' or 'globin.gen' as your User-defined database.
	 If the file extension is '.gen', FEATURES will automatically create
	 temporary files called globin.ano, globin.wrp and globin.ind,
	 containing annotation, sequence, and an index, respectively. These
	 files will be read during feature extraction, and then discarded. If
	 you have already created such files using SPLITDB, simply specify
	 any of 'globin', 'globin.ano', etc. ie. anything, as long as it does
	 not have the .gen file extension.

         'U' rather than 'u' causes ALL entries in the user-defined
         database to be subset. This means that it is unnecessary to 
         specify entry options (eg -n, -N etc.), as these will be
         ignored, if given.

	 One consequence of these conventions is that the individual GenBank
	 divisions can be processed directly. For example, suppose you were only
	 interested in rodent globins.  You could directly access the rodent
	 division of GenBank by specifying the base name of that file division
	 (eg. /home/psgendb/GenBank/gbrod) as your user-defined database. In
	 this case, the files gbrod.ano, gbrod.wrp and gbrod.ind already
	 exist. Again, this approach is faster, since FEATURES would not have
	 to find and retrieve the sequences, but can read directly from the
	 database files. Finally, if you wanted to process all of the entries
	 in the database division, simply use -U. The user is warned that a
	 GenBank division is a huge amount of data, and processing every entry
	 could take a long time.

	 4) WHERE TO SEND IT - By default (a), the output for all entries goes
	 to a single set of files, whose names are chosen by FEATURES,
	 depending on the setting of option 2, Entries. If a single name (n) or
	 accession number (a) has been chosen, that will be used as
	 the raw filename. For example, if you were processing the entry
	 WHTCAB, the output files would be WHTCAB.msg and WHTCAB.out. If names
	 (N), accession numbers (A) or expressions (E) were read from a file,
	 the raw name of that file would be used eg. cellulase.nam would result
	 in cellulase.msg and cellulase.out.  Finally, if a single expression
	 is processed (e), then the primary accession number in that
	 expression will be used for the filenames. In all cases, FEATURES
	 will tell you the names of the files being written.

	 Choosing suboption s, you can specify that the features created for
	 each entry be sent to separate files. In this case, each file will
	 have the name of that entry, with the extension .obj. However, all
	 messages and expressions  will still go to a single files. While this
         can be a convenient way of creating separate files when you need them,
         this option still has the limitation of writing all features for a
         given entry (if there are more than one) to the same file. Also,
         successive resolution of features (anything requiring 'getob -r')
         will not work with this option. This may be corrected in future 
         versions.


      COMMAND LINE EXECUTION

      There are two ways of running FEATURES from the command line. If only one
      argument is supplied, that argument is interpreted as an expression, and
      the result of that expression (ie. a sequence ) is written to the 
      standard output. .msg, .out and .exp files are NOT created. For example,
      GenBank entry BACFLALA (M60287) contains the following feature:

      CDS             95..271
                      /label=LORF-
                      /codon_start=1
                      /translation="MNKDKNEKEELDEEWTELIKHALEQGISPDDIRIFLNLGKKSSK
                      PSASIERSHSINPF"
      Any of 

      features M60287:LORF-
      features M60287:95..271
      features M60287:/label=LORF-

      would write the open reading frame to the standard output: 

      atgaataaagataaaaatgagaaagaagaattggatgaggagtggacaga
      actgattaaacacgctcttgaacaaggcattagtccagacgatatacgta
      tttttctcaatttgggtaagaagtcttcaaaaccttccgcatcaattgaa
      agaagtcattcaataaatcctttctga

      This form of FEATURES is provided to make it easy to pipe output to 
      other programs for further processing. For example

      features M60287:LORF- |ribosome >LORF.protein

      would write the translation of the open reading frame to a file called
      LORF.protein.      

      The full functionality of the FEATURES can be accessed using arguments on
      the command line. In particular, when there are multiple entries to be
      processed, or multiple features within entries, it is much faster to
      supply FEATURES with lists of entries, feature keys or expressions. 
      Command line options are similar to suboptions in menu items 1-3 above:

      Feature keys:  
       -f  key               {feature key}
       -F  filename          {file of feature keys}

       Entries:      
       -n name                {GenBank LOCUS name}
       -N filename            {file of GenBank LOCUS names}
       -a accession           {GenBank ACCESSION number}
       -A filename            {file of GenBank ACCESSION numbers}
       -e expression          {Feature Table expression}
       -E filename            {file of Feature Table expressions, each begin-
                               ning with '@'}

        Databases:
        -u filename           {GenBank dataset}
        -U filename           { "      "        "  "    "       "    ,
                              process all entries ie. -nNaAeE options
                              will be ignored}
        -g                    {GenBank}

        Examples:
        
        features -f tRNA -n EPFCPCG

        retrieves all tRNAs from GenBank entry EPFCPCG and writes .msg, .out,
        and .exp files.

        features -e M60287:LORF-  	  

        would retrieve the same open reading frame as in the earlier example.


        Since most time-consuming operation in FEATURES is sequence retrieval,
        it is often best to retrieve frequently-used sequences as database
        subsets. For example, a set GenBank entries for chlorophyl a/b binding
        protein genes might be stored in a file called CAB.gen.

        features -f CDS -N CAB.nam -u CAB.gen

        would generate the files CAB.msg, CAB.out and CAB.exp containing output 
        for all CDS features in the entries listed in the file CAB.nam.

        features -E CAB.exp -u CAB.gen
 
        would re-create the output file CAB.out.

  
        
     BUGS
       FEATURES does no preliminary error checking for syntax of 
       GenBank expressions prior to their evaluation. Expressions that can
       not be evaluated will be flagged by GETOB in the .msg file.

       At present, little checking is done to test for the presence or
       correctness of input files. Some errors may cause the program to
       crash.

       For User-defined datasets, filename expansion is not performed.

     FILES
        Temporary files:
          X.term X.ano X.wrp X.ind X.gen {X is raw filename, see 4) }
          UNRESOLVED.fea UNRESOLVED.out
          FEA.inf FEA.nam FEA.gen FEA.ano FEA.wrp FEA.ind FEA.msg FEA.out

     SEE ALSO
            grep(1V) fetch getob splitdb 

     TRANSPORTATION NOTES
	    It should be fairly easy to get FEATURES to work even on systems
	    in which GenBank has not been formatted for the XYLEM package.
	    This is because FEATURES does not work directly on the database, but
	    rather retrieves all necessary sequences by calling FETCH. Thus,
	    statements like 'fetch FEA.nam FEA.gen' could be replaced with any
	    command that, given a file containing names or accession numbers,
	    returns a file containing GenBank entries. In principle, you
	    could even implement this sort of command to retrieve entries from
	    the email server (retrieve@ncbi.nlm.nih.gov) at NCBI, although
	    such a setup would undoubtedly be quite slow.

     AUTHOR
       Dr. Brian Fristensky
       Dept. of Plant Science
       University of Manitoba
       Winnipeg, MB  Canada  R3T 2N2
       Phone: 204-474-6085
       FAX: 204-261-5732
       frist@cc.umanitoba.ca

     REFERENCE
       Fristensky, B. (1993) Feature expressions: creating and manipulating
       sequence datasets. Nucleic Acids Research 21:5997-6003.