/*****************************************************************************
#   Copyright (C) 1994-2008 by David Gordon.
#   All rights reserved.                           
#                                                                           
#   This software is part of a beta-test version of the Consed/Autofinish
#   package.  It should not be redistributed or
#   used for any commercial purpose, including commercially funded
#   sequencing, without written permission from the author and the
#   University of Washington.
#   
#   This software is provided ``AS IS'' and any express or implied
#   warranties, including, but not limited to, the implied warranties of
#   merchantability and fitness for a particular purpose, are disclaimed.
#   In no event shall the authors or the University of Washington be
#   liable for any direct, indirect, incidental, special, exemplary, or
#   consequential damages (including, but not limited to, procurement of
#   substitute goods or services; loss of use, data, or profits; or
#   business interruption) however caused and on any theory of liability,
#   whether in contract, strict liability, or tort (including negligence
#   or otherwise) arising in any way out of the use of this software, even
#   if advised of the possibility of such damage.
#
#   Building Consed from source is error prone and not simple which is
#   why I provide executables.  Due to time limitations I cannot
#   provide any assistance in building Consed.  Even if you do not
#   modify the source, you may introduce errors due to using a
#   different version of the compiler, a different version of motif,
#   different versions of other libraries than I used, etc.  For this
#   reason, if you discover Consed bugs, I can only offer help with
#   those bugs if you first reproduce those bugs with an executable
#   provided by me--not an executable you have built.
# 
#   Modifying Consed is also difficult.  Although Consed is modular,
#   some modules are used by many other modules.  Thus making a change
#   in one place can have unforeseen effects on many other features.
#   It may takes months for you to notice these other side-effects
#   which may not seen connected at all.  It is not feasable for me to
#   provide help with modifying Consed sources because of the
#   potentially huge amount of time involved.
#
#*****************************************************************************/
//
// tracefile.h
//
// The TraceFile object corresponds to an ABI or SCF format chromatogram.
// Contains the trace data, the original called bases, point positions
// of the bases (i.e. above what point on the trace the called or aligned
// base appears).
//
// The original bases called by the ABI or phred software, and their
// point positions are for display only and are never changed by
// this object.
//
// The original chromatogram file is never changed by this object or
// the consed application.  All user edits are saved in the output
// .ace file.
//
// Primary client for this object is the TedWin, which is responsible
// for displaying the traces and provides an interface for the user
// to generate edit actions.
//

#ifndef TRACEFILE_INCLUDED
#define TRACEFILE_INCLUDED


#include "sysdepend.h"
#include "rwtvalorderedvector.h"
#include "filename.h"

// finger-friendly name for arrays of trace data points
typedef RWTValOrderedVector<unsigned int> TracePointArray;

// these are the currently supported chromatogram file formats
typedef enum { AbiFile, ScfFile } TraceFileType;

// avoid cyclical include files
class LocatedFragment;
class Fragment;

class TraceFile {

 public:

   // ctor takes full file path of chromatogram as argument
   TraceFile( Fragment* pFragment, const bool bAskForPathnameIfMissing );

   FileName filFindChromat( bool& bDeleteAfterReading );

   ~TraceFile();

   // return the ntide as originally called by the base calling software   
   // indexed by position in original read.  note that this is a
   // Sequence style (1 based) index.
   Ntide& ntideABICalledGet(const int nIndex) const {
      return seqABICalledBases_.ntideGet(nIndex);
   }

   // the point positions of the Ntides in the (editable) sequence of 
   // a LocatedFragment must be set, either from the point positions
   // of the called bases in the original chromatogram file, or by 
   // interpolation (as in the case of pads added by phrap).  This
   // member function is passed a pointer to the TraceFile's corresponding
   // LocatedFragment and updates the Sequence's point positions.
   void setFragmentPointPositions(LocatedFragment* pLocFrag);

   // passed a point position range, returns the range of
   // called base indices that fall within it
   void getRangeOfABICalledPositions(const int nPointMin, 
                                  const int nPointMax, 
                                  int& nCalledBaseMin, 
                                  int& nCalledBaseMax,
                                  bool& bError) const {
      // Sequence provides this functionality
      seqABICalledBases_.getIndexRangeFromPointPositions(nPointMin, 
                                                          nPointMax,
                                                          nCalledBaseMin,
                                                          nCalledBaseMax,
                                                          bError );
   }

   // passed 'A', 'C', 'T', 'G' and an index into the trace point 
   // array, returns trace value (i.e. y-coordinate/intensity) 
   unsigned int nGetTraceValue( const char c, const int nPoint );

   // returns the number of points in the trace arrays
   int nGetNumberOfPoints() const { return nPoints_; }

   // this complements the trace point arrays as well as the 
   // array of originally called bases and their point positions
   void complementTracesAndABICalledBases();

   void createFakeSolexaTraces();

 public:

   // these dynamic arrays of int are used to store the data points for 
   // the four traces (A,C,T,G) generated by the image analysis software
   // they are pointers rather than members to make complementation
   // easier (swap pointers instead of swap arrays).
   //
   // the reverseElementOrder() function is used in complementation.
   //
   // note that unlike Sequence data these are 0 based arrays
   TracePointArray* pdaTraceA_;  // "Ptr to Dyn Array" of int
   TracePointArray* pdaTraceC_;  // 
   TracePointArray* pdaTraceT_;  // 
   TracePointArray* pdaTraceG_;  // 

   // this array stores the bases as called by the base calling software,
   // ABI or phrap.  This is a Sequence, i.e. a 1 based array of Ntide
   // and as such can be complemented with complementSequence() member.
   // The point positions are stored within the Ntides.  Unlike the
   // Sequence contained within a Fragment, it will never contain pads.
   // The data in the array remains unedited throughout the life of 
   // the object.
   Sequence seqABICalledBases_;

   // number of points in the trace arrays
   int nPoints_;

   Fragment* pFrag_;


   int nMinTraceValue_;
   int nMaxTraceValue_;

};  // class TraceFile

#endif  // TRACEFILE_INCLUDED