
                          DOMAINSEQS documentation
                                      
   

CONTENTS

   1.0 SUMMARY 
   2.0 INPUTS & OUTPUTS 
   3.0 INPUT FILE FORMAT 
   4.0 OUTPUT FILE FORMAT 
   5.0 DATA FILES 
   6.0 USAGE 
   7.0 KNOWN BUGS & WARNINGS 
   8.0 NOTES 
   9.0 DESCRIPTION 
   10.0 ALGORITHM 
   11.0 RELATED APPLICATIONS 
   12.0 DIAGNOSTIC ERROR MESSAGES 
   13.0 AUTHORS 
   14.0 REFERENCES 

1.0 SUMMARY

   Adds sequence records to a DCF file (domain classification file)

2.0 INPUTS & OUTPUTS

   DOMAINSEQS parses a DCF file (domain classification file) and writes a
   file containing the same data, except that domain sequence information
   derived from structural and, optionally, sequence databases are added.
   Domain sequences are taken from domain CCF files (clean coordinate
   files) and (optionally) the swissprot database. If the swissprot
   sequence is used, DOMAINSEQS requires a swissprot:PDB equivalence file
   that gives the accession number of each PDB file corresponding to the
   domains in the DCF file. The path for the CCF files (input) and names
   of DCF files (input and output) are specified by the user. A log file
   is also written.

3.0 INPUT FILE FORMAT

   The format of the DCF file is described in the SCOPPARSE
   documentation.

4.0 OUTPUT FILE FORMAT

   The format of the DCF file is described in the SCOPPARSE
   documentation.

5.0 DATA FILES

   If the user specified retrieval of sequences from a sequence database,
   DOMAINSEQS uses a swissprot:PDB equivalence file is generated by using
   PDBTOSP.

6.0 USAGE

  6.1 COMMAND LINE ARGUMENTS

   Standard (Mandatory) qualifiers (* if not always prompted):
  [-dcfinfile]         infile     This option specifies the name of DCF file
                                  (domain classification file) (input). A
                                  'domain classification file' contains
                                  classification and other data for domains
                                  from SCOP or CATH, in DCF format
                                  (EMBL-like). The files are generated by
                                  using SCOPPARSE and CATHPARSE. Domain
                                  sequence information can be added to the
                                  file by using DOMAINSEQS.
  [-dpdbdir]           directory  This option specifies the location of domain
                                  CCF file (clean coordinate files) (input).
                                  A 'clean cordinate file' contains coordinate
                                  and other data for a single PDB file or a
                                  single domain from SCOP or CATH, in CCF
                                  format (EMBL-like). The files, generated by
                                  using PDBPARSE (PDB files) or DOMAINER
                                  (domains), contain 'cleaned-up' data that is
                                  self-consistent and error-corrected.
                                  Records for residue solvent accessibility
                                  and secondary structure are added to the
                                  file by using PDBPLUS.
   -getswiss           toggle     Retrieve swissprot sequence.
*  -pdbtospfile        infile     This option specifies the name of the
                                  pdbcodes to swissprot indexing file. The
                                  swissprot:PDB equivalence file is generated
                                  by PDBTOSP
  [-dcfoutfile]        outfile    This option specifies the name of DCF file
                                  (domain classification file) (output). A
                                  'domain classification file' contains
                                  classification and other data for domains
                                  from SCOP or CATH, in DCF format
                                  (EMBL-like). The files are generated by
                                  using SCOPPARSE and CATHPARSE. Domain
                                  sequence information can be added to the
                                  file by using DOMAINSEQS.
   -errfile            outfile    This option specifies the name of log file
                                  for the build. The log file contains
                                  messages about any errors arising while
                                  domainseqs ran.

   Additional (Optional) qualifiers (* if not always prompted):
*  -datafile           matrixf    This option specifies the residue
                                  substitution matrix, which is used for
                                  sequence comparison.
*  -gapopen            float      This option specifies the gap insertion
                                  penalty. This is the score taken away when a
                                  gap is created. The best value depends on
                                  the choice of comparison matrix. The default
                                  value assumes you are using the EBLOSUM62
                                  matrix for protein sequences, and the
                                  EDNAFULL matrix for nucleotide sequences.
*  -gapextend          float      This option specifies the gap extension
                                  penalty. This is added to the standard gap
                                  penalty for each base or residue in the gap.
                                  This is how long gaps are penalized.
                                  Usually you will expect a few long gaps
                                  rather than many short gaps, so the gap
                                  extension penalty should be lower than the
                                  gap penalty. An exception is where one or
                                  both sequences are single reads with
                                  possible sequencing errors in which case you
                                  would expect many single base gaps. You can
                                  get this result by setting the gap open
                                  penalty to zero (or very low) and using the
                                  gap extension penalty to control gap
                                  scoring.

   Advanced (Unprompted) qualifiers: (none)
   Associated qualifiers:

   "-dcfoutfile" associated qualifiers
   -odirectory3        string     Output directory

   "-errfile" associated qualifiers
   -odirectory         string     Output directory

   General qualifiers:
   -auto               boolean    Turn off prompts
   -stdout             boolean    Write standard output
   -filter             boolean    Read standard input, write standard output
   -options            boolean    Prompt for standard and additional values
   -debug              boolean    Write debug output to program.dbg
   -verbose            boolean    Report some/full command line options
   -help               boolean    Report command line options. More
                                  information on associated and general
                                  qualifiers can be found with -help -verbose
   -warning            boolean    Report warnings
   -error              boolean    Report errors
   -fatal              boolean    Report fatal errors
   -die                boolean    Report deaths


   Standard (Mandatory) qualifiers Allowed values Default
   [-dcfinfile]
   (Parameter 1) This option specifies the name of DCF file (domain
   classification file) (input). A 'domain classification file' contains
   classification and other data for domains from SCOP or CATH, in DCF
   format (EMBL-like). The files are generated by using SCOPPARSE and
   CATHPARSE. Domain sequence information can be added to the file by
   using DOMAINSEQS. Input file Required
   [-dpdbdir]
   (Parameter 2) This option specifies the location of domain CCF file
   (clean coordinate files) (input). A 'clean cordinate file' contains
   coordinate and other data for a single PDB file or a single domain
   from SCOP or CATH, in CCF format (EMBL-like). The files, generated by
   using PDBPARSE (PDB files) or DOMAINER (domains), contain 'cleaned-up'
   data that is self-consistent and error-corrected. Records for residue
   solvent accessibility and secondary structure are added to the file by
   using PDBPLUS. Directory ./
   -getswiss Retrieve swissprot sequence. Toggle value Yes/No No
   -pdbtospfile This option specifies the name of the pdbcodes to
   swissprot indexing file. The swissprot:PDB equivalence file is
   generated by PDBTOSP Input file Required
   [-dcfoutfile]
   (Parameter 3) This option specifies the name of DCF file (domain
   classification file) (output). A 'domain classification file' contains
   classification and other data for domains from SCOP or CATH, in DCF
   format (EMBL-like). The files are generated by using SCOPPARSE and
   CATHPARSE. Domain sequence information can be added to the file by
   using DOMAINSEQS. Output file domainseqs.out
   -errfile This option specifies the name of log file for the build. The
   log file contains messages about any errors arising while domainseqs
   ran. Output file domainseqs.log
   Additional (Optional) qualifiers Allowed values Default
   -datafile This option specifies the residue substitution matrix, which
   is used for sequence comparison. Comparison matrix file in EMBOSS data
   path EBLOSUM62
   -gapopen This option specifies the gap insertion penalty. This is the
   score taken away when a gap is created. The best value depends on the
   choice of comparison matrix. The default value assumes you are using
   the EBLOSUM62 matrix for protein sequences, and the EDNAFULL matrix
   for nucleotide sequences. Floating point number from 1.0 to 100.0 10.0
   for any sequence
   -gapextend This option specifies the gap extension penalty. This is
   added to the standard gap penalty for each base or residue in the gap.
   This is how long gaps are penalized. Usually you will expect a few
   long gaps rather than many short gaps, so the gap extension penalty
   should be lower than the gap penalty. An exception is where one or
   both sequences are single reads with possible sequencing errors in
   which case you would expect many single base gaps. You can get this
   result by setting the gap open penalty to zero (or very low) and using
   the gap extension penalty to control gap scoring. Floating point
   number from 0.0 to 10.0 0.5 for any sequence
   Advanced (Unprompted) qualifiers Allowed values Default
   (none)

  6.2 EXAMPLE SESSION

   An example of interactive use of DOMAINSEQS is shown below.
   The DCF file (domain classification file) lacking sequence information
   called /test_data/all.scop was parsed and a DCF file with sequence
   information called /test_data/domainseqs/all_s.scop was written. The
   file Epdbtosp.dat was queried for accession numbers of PDB files
   corresponding to the domains in all.scop, but no accession numbers
   were found for either of the domains d1ii7a_ or d1cs4a_. A log file
   called /test_data/domainseqs/domainseqs.log was written.

7.0 KNOWN BUGS & WARNINGS

   The swissprot:PDB equivalence file available as part of the EMBOSS
   distribution does not contain accession numbers for all PDB files and
   covers only a relatively small proportion of domains in SCOP.

8.0 NOTES

   DOMAINSEQS will not attempt to retrieve a swissprot sequence for any
   domains comprised of more than a single segment, i.e. for domains
   whose NC record in the DCF file has a value other than 1 (see
   SCOPPARSE documentation).
   The region of sequence to retrieve is identified by alignment of the
   sequence from the CCF file (structural database) to the full length
   sequences in swissprot. If this were to be done for segmented domains,
   the start and end point for the retrieved sequence (relative to the
   full length sequence) might actually include a completely different
   domain.
   Consider :
   (A) represents a sequence from the coordinate file for a segmented
   domain D1
   (B) represents the full-length swissprot sequence, it includes D1, but
   D1 is split by a second domain D2

                 D1
  (A)  XXXXXXXXXXXXXXXXXXXXX

          D1         D2        D1
  (B) XXXXXXXXXX-----------XXXXXXXXXXX

   It should be clear that for an alignment retrieving B, the start and
   end points for the retrieved sequence would be misleading.
   The user should be aware that sequences from the domain CCF file for
   domains comprised of more than a single segment are not biologically
   significant, as the sequences are derived from different segments of
   one or more chains. However, such sequences might be acceptable for
   redundancy calculations (e.g. by using DOMAINNR) because two redundant
   domains made of similar fragments will have similar sequences, so the
   redundancy should be detectable.

  8.1 GLOSSARY OF FILE TYPES

   ** The swissprot:PDB equivalence file is generated by pdbtosp and is
   part of ** the emboss distribution.

   FILE TYPE FORMAT DESCRIPTION CREATED BY SEE ALSO
   Domain classification file (for SCOP) DCF format (EMBL-like format for
   domain classification data). Classification and other data for domains
   from SCOP. SCOPPARSE Domain sequence information can be added to the
   file by using DOMAINSEQS.
   Domain classification file (for CATH) DCF format (EMBL-like format for
   domain classification data). Classification and other data for domains
   from CATH. CATHPARSE Domain sequence information can be added to the
   file by using DOMAINSEQS.
   Clean coordinate file (for protein) CCF format (EMBL-like format for
   protein coordinate and derived data). Coordinate and other data for a
   single PDB file. The data are 'cleaned-up': self-consistent and
   error-corrected. PDBPARSE Records for residue solvent accessibility
   and secondary structure are added to the file by using PDBPLUS.
   Clean coordinate file (for domain) CCF format (EMBL-like format for
   protein coordinate and derived data). Coordinate and other data for a
   single domain from SCOP or CATH. The data are 'cleaned-up':
   self-consistent and error-corrected. DOMAINER Records for residue
   solvent accessibility and secondary structure are added to the file by
   using PDBPLUS.
   swissprot:PDB equivalence file EMBL-like format. A file containing
   swissprot identifiers for PDB codes. Included in the EMBOSS
   distribution N.A.

   None

9.0 DESCRIPTION

   Domain sequences are not given in the raw SCOP or CATH parsable files,
   but are required for many analyses and for convenience should,
   ideally, be provided along with the classification itself. DOMAINSEQS
   reads a DCF file (domain classificaiton file) that lacks sequence
   information and writes one containing sequence information.

10.0 ALGORITHM

   In order to find the start and end of a domain in a sequence from
   swissprot, the domain sequence from the domain CCF file is aligned to
   the full length protein sequence from swissprot. Alignment is
   performed first by string handling and if that fails, by using the
   EMBOSS implementation of the Needleman and Wunsch global alignment
   algorithm. Gap insertion and extension penalties used in the
   alignments are user-specified.

11.0 RELATED APPLICATIONS

See also

   Program name Description
   aaindexextract Extract data from AAINDEX
   allversusall Does an all-versus-all global alignment for each set of
   sequences in an input directory and writes files of sequence
   similarity values
   cathparse Reads raw CATH classification files and writes DCF file
   (domain classification file)
   cutgextract Extract data from CUTG
   domainer Reads CCF files (clean coordinate files) for proteins and
   writes CCF files for domains, taken from a DCF file (domain
   classification file)
   domainnr Removes redundant domains from a DCF file (domain
   classification file). The file must contain domain sequence
   information, which can be added by using DOMAINSEQS
   domainsse Adds secondary structure records to a DCF file (domain
   classification file)
   hetparse Converts raw dictionary of heterogen groups to a file in
   EMBL-like format
   pdbparse Parses PDB files and writes CCF files (clean coordinate
   files) for proteins
   pdbplus Add residue solvent accessibility and secondary structure data
   to a CCF file (clean coordinate file) for a protein or domain
   pdbtosp Convert raw swissprot:PDB equivalence file to EMBL-like format
   printsextract Extract data from PRINTS
   prosextract Builds the PROSITE motif database for patmatmotifs to
   search
   rebaseextract Extract data from REBASE
   scopparse Reads raw SCOP classification files and writes a DCF file
   (domain classification file)
   seqnr Removes redundancy from DHF files (domain hits files) or other
   files of sequences
   sites Reads CCF files (clean coordinate files) and writes CON files
   (contact files) of residue-ligand contact data for domains in a DCF
   file (domain classification file)
   ssematch Searches a DCF file (domain classification file) for
   secondary structure matches
   tfextract Extract data from TRANSFAC

12.0 DIAGNOSTIC ERROR MESSAGES

   None.

13.0 AUTHORS

   Ranjeeva Ranasinghe (rranasin@hgmp.mrc.ac.uk)
   Jon Ison (jison@rfcgr.mrc.ac.uk)
   MRC Rosalind Franklin Centre for Genomics Research, Wellcome Trust
   Genome Campus, Hinxton, Cambridge, CB10 1SB, UK

14.0 REFERENCES

   Please cite the authors and EMBOSS.
   Rice P, Longden I and Bleasby A (2000) "EMBOSS - The European
   Molecular Biology Open Software Suite" Trends in Genetics, 15:276-278.
   
   See also http://emboss.sourceforge.net/

  14.1 Other useful references
