
<section>
  <title>Requirements for the &seqapi;.</title>

  <para>In this section we discuss the basic requirements for the
    &seqapi; both in terms of the data to be represented and the
    requirements for any potential implementation. </para>

  <section>
    <title>The biological sequence as a list</title>

    <para>As previously mentioned the biological sequence is in
      essence a list, which is an ordered series of elements. The
      basic operations that the Sequence should therefore provide
      are:- 

      <itemizedlist>
	<listitem>
	  <para>Access to the elements, in their appropriate
	    order.</para>
	</listitem>
	<listitem>
	  <para>Access to the size of the list</para>
	</listitem>
	<listitem>
	  <para>The ability to retrieve subsequences of the larger
	    sequence.</para>
	</listitem>
      </itemizedlist>
      </para>
    
    <![%draft;[
    <para>
      <emphasis>One thing that we have not really thought about with the
	API at the moment is what notion of equality we have. The
	obvious answer to this is to say that a sequence is equal
	iff it all of its elements are equal and if the sequences
	are of the same SequenceType. I am not sure though that this
	is in fact the correct way to go. We also have a notion of
	an identifier, and source, both of which should be also
	considered. But how do we define the notion of equality of
	these. I think perhaps equals and hashcode should be left as
	they are and we should introduce and additional which checks
	for &quot;lexical&quot; equality
      </emphasis>
    </para>
    ]]>
    
  </section>

  <section>
    <title>Modifying sequences</title>

    <para>Many bioinformatics applications model sequences in
      immutable data structures. This has several advantages. If a
      sequence can not change it is not necesary to ensure that other
      parts of the program are when changes happen to that
      sequence. The Java language is also &quot;multi-threaded&quot;, that
      is it can do more than one thing at once. Multi-threaded programming
      provides many advantages, but it's also inherantly
      complex, as changes in one thread can affect another. Immutable
      objects limit this complexity as the object can not be changed
      in another thread. It is for this reason amoung others for
      instance that the String class of Java is immutable.</para>

    <para>Despite the appeal of immutable sequences and the
      simplicity they provide they can also produce greater
      complexity. If the application needs to alter sequences then
      objects need to be re-created every time it is altered. As well
      as being more complicated this can also have a large impact on
      the computational performance of the class. We have decided that
      despite the potential difficulties the &seqapi; should support
      the ability to change sequences.</para>
  </section>
  
  <section>
    <title>Conserving &quot;type&quot; information about
      sequnces</title>

    <para>There are many different types of biological sequences such
      as protein, DNA and RNA sequences. When written down these
      sequences are usually represented as a string of characters
      (fortunately none of those mentioned have more that 26 different
      elements!). One problem with this representation is that its not
      possible to differentiate between a single letter, say a C
      representing cytosine, or a cysteine. It doesn't normally make a
      lot of sense to compare a protein sequence and a DNA sequence
      directly. Additionally the requirement for mutable sequences
      mean that it is potentially possible to add an amino acid to a
      DNA sequence. This will almost always be a mistake.</para>

    <para>Therefore we wanted the &seqapi; to build a degree of safety
      into its operations, so that such errors could be easily
      trapped, which should reduce the potential for bugs. This bears
      a resemblance to the notion of type checking which is
      implemented in Java, and indeed many other languages. Ideally we
      would like the &seqapi; to exploit Java's type system, as this
      would enable any such errors to be caught at compile
      time. It should be noted however that Java's Collection's API,
      which includes several implementations of Lists does not provide
      this sort of type safety, which raises the suspision that it
      might not be possible in the Java language. Therefore failing
      compile time type safety the &seqapi; should &quot;fail
      fast&quot;, that is cause errors as soon as a possible type
      error was detected, rather than continuing with potentially
      corrupt data.</para>
  </section>

  <section>
    <title>Representing more varied sequences: gaps, and complex
      sequences</title>
    
    <para>It is common in bioinformatics applications to align one
      sequence with another, so that regions with the same or similar
      sequences are placed next to each other. If sequences are
      identical this is a trivial task, but this is not generally the
      case, and it is frequently necessary to insert gaps into
      sequences in order to align sequences. We required the abilty to
      represent gapped sequences with the &seqapi;</para>

    <para>As well as gapped sequences we wanted to be able to
      represent sequences which are basically of one type, but which
      have what can be considered to be modified residues. Examples of
      this would be methylated cytosines in DNA, or phosphorylated
      protein sequences. </para>
  </section>

  <section>
    <title>Identifying the source of the sequence</title>

    <para>In many cases the sequences being represented by the
      &seqapi; will comes from a specific database. Sequence databases
      usually come with an attached identifier for that sequence. This
      API needs to be able to represent this data in a way which is
      generic enough to cover most database formats.</para>
  </section>
  
  <section>
    <title>Computation and programming requirements:- a lightweight
      API</title>

    <para>Perhaps because its one of the more basic data structures
      found in computing science, there are many different
      implementations of the list, all of which have different
      implications of the CPU and memory usage. None of these
      solutions are ideal, and the choice of which to use depends upon
      the data being represented, and the application in question. The
      &seqapi; should not require the use of one particular
      implementation, but instead should allow easy replacements of
      one implementation for another.</para>
    
    <para>The primary purpose this API is to represent sequence
      data. In order to be useful it should put as minimal a
      requirement on the implementing programmer as is consistent with
      its data task of representing the data. Where ever possible the
      &seqapi; should provide default implementations and helper
      classes to simplfy the implementation further. </para>

    <para>Finally the API should reuse as many of the ideas, and
      design patterns and classes of the core Java library as
      possible. As well as not wishing to load the programmer down
      with implementational requirements we want to ensure that the
      API was as easy to understand as possible</para>

  </section>
  
  <section>
    <title>Anti-requirements</title>
    
    <para>In bioinformatics sequences are frequently associated with a
      large body of associated information, in addition to the
      sequences identifier, which can collectively be described as
      sequence annotation. The &seqapi; specifically is not required
      to represent this form of data. The reasoning behind this is
      that firstly it contradicts the requirements for a simple,
      lightweight API. Secondly sequence annotation is an extremely
      complex issue, consisting as it does of a hetrogenous data
      set. Whilst it would be good to have an API representing such
      data it would far exceed the size of this API. Finally there is
      nothing to preclude building up annotated sequence objects by
      combining the objects in this API with objects representing the
      state of the annotation.</para>
  </section>
</section>

<!--
 We need to define local variables to enable psgml mode to work out
 what DTD we are using, and also where we are in the document.

 Local Variables: ***
 sgml-parent-document:("sequence.sgml" "article" "section" ) ***
 End: ***
 -->




