\section{sequence}
\label{module_sequence}
This module contains the following objects

\begin{itemize}
\item \ref{object_Sequence} Sequence

\item \ref{object_SequenceSet} SequenceSet

\item This module also contains some factory methods
\end{itemize}
\subsection{sequence factory methods}
\subsubsection{Sequence_type_to_string}
\begin{description}
\item[External C] {\tt Wise2_Sequence_type_to_string (type)}
\item[Perl] {\tt &Wise2::Sequence_type_to_string (type)}

\end{description}
Arguments
\begin{description}
\item[type] [UNKN ] type eg SEQUENCE_PROTEIN [int]
\item[returns] [UNKN ] Undocumented return value [char *]
\end{description}
Converts sequence type (SEQUENCE_*) to a string


\subsubsection{new_Sequence_from_strings}
\begin{description}
\item[External C] {\tt Wise2_new_Sequence_from_strings (name,seq)}
\item[Perl] {\tt &Wise2::new_Sequence_from_strings (name,seq)}

\end{description}
Arguments
\begin{description}
\item[name] [READ ] name of sequence, memory is allocated for it. [char *]
\item[seq] [READ ] char * of sequence, memory is allocated for it. [char *]
\item[returns] [UNKN ] Undocumented return value [Sequence *]
\end{description}
Makes a new sequence from strings given. 
Separate memory will be allocated for them
and them copied into it.


They can be NULL, in which case 
o  a dummy name SequenceName will be assigned
o  No sequence placed and length of zero.


Though this is dangerous later on. 


The sequence type is calculated automatically using
/best_guess_type. If you want a DNA sequence but are
unsure of the content of, for example, IUPAC codes,
please use /force_to_dna_Sequence before using the
sequence. Most of the rest of dynamite relies on a
five letter A,T,G,C,N alphabet, but this function
will allow any sequence type to be stored, so please
check if you want to save yourself alot of grief.


In perl and other interfaces, this is a much safer
constructor than the raw "new" type




\subsection{Object Sequence}

\label{object_Sequence}

The Sequence object has the following fields. To see how to access them refer to \ref{accessing_fields}
\begin{description}
\item{name} Type [char * : Scalar]  name of the sequence

\item{seq} Type [char * : Scalar]  actual sequence

\item{len} Type [int : Scalar]  length of the sequence

\item{maxlen} Type [int : Scalar]  internal counter, indicating how much space in seq there is

\item{offset} Type [int : Scalar]  start (in bio-coords) of the sequence. Not called start due to weird legacy.

\item{end} Type [int : Scalar]  end (in bio-coords == C coords) of the sequence

\item{type} Type [int : Scalar]  guess of protein/dna type

\end{description}
This object is the basic sequence object,
trying to hold little more than the 
name and sequence of the DNA/protein. 


The len/maxlen is the actual length
of the sequence (strlen(obj->seq)) and
amount of memory allocated in obj->seq 
mainly for parsing purposes.


You are strongly encouraged to used the
typed counterparts of Sequence, namely,
Protein, cDNA and Genomic. By doing this 
you are much, much less likely to
mess up algorithms which expect specific
sequence types. 




Member functions of Sequence

\subsubsection{uppercase_Sequence}

\begin{description}
\item[External C] {\tt Wise2_uppercase_Sequence (seq)}
\item[Perl] {\tt &Wise2::Sequence::uppercase (seq)}

\item[Perl-OOP call] {\tt $obj->uppercase()}

\end{description}
Arguments
\begin{description}
\item[seq] [RW   ] Sequence to be uppercased [Sequence *]
\item[returns] Nothing - no return value
\end{description}
makes all the sequence uppercase


\subsubsection{force_to_dna_Sequence}

\begin{description}
\item[External C] {\tt Wise2_force_to_dna_Sequence (seq,fraction,number_of_conver)}
\item[Perl] {\tt &Wise2::Sequence::force_to_dna (seq,fraction)}

\item[Perl-OOP call] {\tt $obj->force_to_dna(fraction)}

\end{description}
Arguments
\begin{description}
\item[seq] [RW   ] sequence object read and converted  [Sequence *]
\item[fraction] [READ ] number 0..1 for tolerance of conversion [double]
\item[number_of_conver] \em{only for C api} [WRITE] number of conversions actually made [int *]
\item[returns] [READ ] TRUE for conversion to DNA, FALSE if not [boolean]
\end{description}
This 
\begin{verbatim}
 a) sees how many non ATGCN characters there are in Seq
 b) If the level is below fraction
    a) flips non ATGC chars to N
    b) writes number of conversions to number_of_conver
    c) returns TRUE
 c) else returns FALSE


\end{verbatim}
fraction of 0.0 means completely intolerant of errors
fraction of 1.0 means completely tolerant of errors




\subsubsection{is_reversed_Sequence}

\begin{description}
\item[External C] {\tt Wise2_is_reversed_Sequence (seq)}
\item[Perl] {\tt &Wise2::Sequence::is_reversed (seq)}

\item[Perl-OOP call] {\tt $obj->is_reversed()}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] sequence to test [Sequence *]
\item[returns] [UNKN ] Undocumented return value [boolean]
\end{description}
Currently the sequence object stores 
reversed sequences as start > end.


This tests that and returns true if it is


\subsubsection{translate_Sequence}

\begin{description}
\item[External C] {\tt Wise2_translate_Sequence (dna,ct)}
\item[Perl] {\tt &Wise2::Sequence::translate (dna,ct)}

\item[Perl-OOP call] {\tt $obj->translate(ct)}

\end{description}
Arguments
\begin{description}
\item[dna] [READ ] DNA sequence to be translated [Sequence *]
\item[ct] [READ ] Codon table to do codon->aa mapping [CodonTable *]
\item[returns] [OWNER] new protein sequence [Sequence *]
\end{description}
This translates a DNA sequence to a protein.
It assummes that it starts at first residue
(use trunc_Sequence to chop a sequence up).


\subsubsection{reverse_complement_Sequence}

\begin{description}
\item[External C] {\tt Wise2_reverse_complement_Sequence (seq)}
\item[Perl] {\tt &Wise2::Sequence::revcomp (seq)}

\item[Perl-OOP call] {\tt $obj->revcomp()}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] Sequence to that is used to reverse (makes a new Sequence) [Sequence *]
\item[returns] [OWNER] new Sequence which is reversed [Sequence *]
\end{description}
This both complements and reverses a sequence,
- a common wish!


The start/end are correct with respect to the start/end
of the sequence (ie start = end, end = start).


\subsubsection{magic_trunc_Sequence}

\begin{description}
\item[External C] {\tt Wise2_magic_trunc_Sequence (seq,start,end)}
\item[Perl] {\tt &Wise2::Sequence::magic_trunc (seq,start,end)}

\item[Perl-OOP call] {\tt $obj->magic_trunc(start,end)}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] sequence that is the source to be truncated [Sequence *]
\item[start] [READ ] start point [int]
\item[end] [READ ] end point [int]
\item[returns] [OWNER] new Sequence which is truncated/reversed [Sequence *]
\end{description}
Clever function for dna sequences.


When start < end, truncates normally


when start > end, truncates end,start and then
reverse complements.


ie. If you have a coordinate system where reverse 
sequences are labelled in reverse start/end way,
then this routine produces the correct sequence.


\subsubsection{trunc_Sequence}

\begin{description}
\item[External C] {\tt Wise2_trunc_Sequence (seq,start,end)}
\item[Perl] {\tt &Wise2::Sequence::trunc (seq,start,end)}

\item[Perl-OOP call] {\tt $obj->trunc(start,end)}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] object holding the sequence to be truncated [Sequence *]
\item[start] [READ ] start point of truncation [int]
\item[end] [READ ] end point of truncation [int]
\item[returns] [OWNER] newly allocated sequence structure [Sequence *]
\end{description}
truncates a sequence. It produces a new memory structure
which is filled from sequence start to end.


Please notice
\begin{verbatim}
  
  Truncation is in C coordinates. That is
\end{verbatim}
the first residue is 0 and end is the number of the
residue after the cut-point. In otherwords to 
2 - 3 would be a single residue truncation. So - if
you want to work in more usual, 'inclusive' molecular
biology numbers, which start at 1, then you need to say


\begin{verbatim}
  trunc_Sequence(seq,start-1,end);


\end{verbatim}
(NB, should be (end - 1 + 1) = end for the last coordinate).


\begin{verbatim}
  Truncation occurs against the *absolute* coordinate
\end{verbatim}
system of the Sequence, not the offset/end pair inside.
So, this is a very bad error
\begin{verbatim}
 
  ** wrong code, and also leaks memory **


  tru = trunc_Sequence(trunc_Sequence(seq,50,80),55,75); 


\end{verbatim}
This the most portable way of doing this


\begin{verbatim}
  temp = trunc_Sequence(seq,50,80);


  tru  = trunc_Sequence(temp,55-temp->offset,75-temp->offset);


  free_Sequence(temp);




\end{verbatim}
\subsubsection{read_fasta_file_Sequence}

\begin{description}
\item[External C] {\tt Wise2_read_fasta_file_Sequence (filename)}
\item[Perl] {\tt &Wise2::Sequence::read_fasta_file_Sequence (filename)}

\item[Perl-OOP call] {\tt $obj->read_fasta_file_Sequence()}

\end{description}
Arguments
\begin{description}
\item[filename] [READ ] filename to open  [char *]
\item[returns] [UNKN ] Undocumented return value [Sequence *]
\end{description}
Just a call
\begin{verbatim}
  a) open filename
  b) read sequence with /read_fasta_Sequence
  c) close file.


\end{verbatim}
\subsubsection{read_Sequence_EMBL_seq}

\begin{description}
\item[External C] {\tt Wise2_read_Sequence_EMBL_seq (buffer,maxlen,ifp)}
\item[Perl] {\tt &Wise2::Sequence::read_Sequence_EMBL_seq (buffer,maxlen,ifp)}

\item[Perl-OOP call] {\tt $obj->read_Sequence_EMBL_seq(maxlen,ifp)}

\end{description}
Arguments
\begin{description}
\item[buffer] [RW   ] buffer containing the first line. [char *]
\item[maxlen] [READ ] length of buffer [int]
\item[ifp] [READ ] input file to read from [FILE *]
\item[returns] [UNKN ] Undocumented return value [Sequence *]
\end{description}
reads the sequence part of an EMBL file.


This function can either take a file which 
starts




\subsubsection{read_fasta_Sequence}

\begin{description}
\item[External C] {\tt Wise2_read_fasta_Sequence (ifp)}
\item[Perl] {\tt &Wise2::Sequence::read_fasta_Sequence (ifp)}

\item[Perl-OOP call] {\tt $obj->read_fasta_Sequence()}

\end{description}
Arguments
\begin{description}
\item[ifp] [READ ] input file to read from [FILE *]
\item[returns] [OWNER] new Sequence structure  [Sequence *]
\end{description}
reads the fasta file: format is


>name
sequence


allocates a structure and puts in the
sequence. Calls /make_len_type_Sequence to
check type and length.


It leaves the '>' on the next fasta sequence
for multiple sequence reading


\subsubsection{show_Sequence_residue_list}

\begin{description}
\item[External C] {\tt Wise2_show_Sequence_residue_list (seq,start,end,ofp)}
\item[Perl] {\tt &Wise2::Sequence::show_debug (seq,start,end,ofp)}

\item[Perl-OOP call] {\tt $obj->show_debug(start,end,ofp)}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] Sequence to show [Sequence *]
\item[start] [READ ] start of list [int]
\item[end] [READ ] end of list [int]
\item[ofp] [UNKN ] Undocumented argument [FILE *]
\item[returns] Nothing - no return value
\end{description}
shows a region of a sequence as
\begin{verbatim}
   124  A
   125  T


\end{verbatim}
etc from start to end. The numbers
are in C coordinates (ie, 0 is the first
letter).


useful for debugging


\subsubsection{write_fasta_Sequence}

\begin{description}
\item[External C] {\tt Wise2_write_fasta_Sequence (seq,ofp)}
\item[Perl] {\tt &Wise2::Sequence::write_fasta (seq,ofp)}

\item[Perl-OOP call] {\tt $obj->write_fasta(ofp)}

\end{description}
Arguments
\begin{description}
\item[seq] [READ ] sequence to be written [Sequence *]
\item[ofp] [UNKN ] file to write to [FILE *]
\item[returns] Nothing - no return value
\end{description}
writes a fasta file of the form
>name
Sequence


\subsubsection{make_len_type_Sequence}

\begin{description}
\item[External C] {\tt Wise2_make_len_type_Sequence (seq)}
\item[Perl] {\tt &Wise2::Sequence::validate (seq)}

\item[Perl-OOP call] {\tt $obj->validate()}

\end{description}
Arguments
\begin{description}
\item[seq] [RW   ] Sequence object [Sequence *]
\item[returns] Nothing - no return value
\end{description}
makes seq->len and seq->end match the seq->seq
length number. 


It also checks the type of the sequence with
/best_guess_type


\subsection{Object SequenceSet}

\label{object_SequenceSet}

The SequenceSet object has the following fields. To see how to access them refer to \ref{accessing_fields}
\begin{description}
\item{set} Type [Sequence ** : List] No documentation

\end{description}
A list of sequences. Not a database (you should
use the db stuff for that!). But useful anyway




Member functions of SequenceSet

