text: /*  Last edited: Aug 25 15:19 1999 (klh) */
  /**********************************************************************
   ** FILE: cluster.h
   ** NOTES:
   **  A DistanceMatrix should always be part of a Cluster 
   **  It makes no sense to have a set of pairwise distances without the 
   **  associated sequences (even if we just store their names)
   **********************************************************************/
  
  #ifndef _CLUSTER
  #define _CLUSTER
  
  #include "sequence.h"
  #include "distancemat.h"
  
  
  
  /******************* structure definitions ****************************/
  
  struct Cluster {
    unsigned int clustersize;
    struct Sequence **members;
    struct Sequence *consensus;
    struct DistanceMatrix *matrix;
  };
  
  
  /*
    Clusters contain groups of identical sequence. I intend to investigate
    methods where clusters contain groups of similar (not necessarily
    identical) sequences. The DistanceMatric field, although not currently
    used, will allow for the building of trees from these clusters
  */
  
  
  struct ClusterGroup {
    unsigned int numclusters;
    struct Cluster **clusters;
    struct DistanceMatrix *matrix;
  };
  
  
  /********************** function prototypes ***************************/
  
  
  
  /*********************************************************************
    FUNCTION: alignment_to_ClusterGroup
    DESCRIPTION: 
      This function returns a ClusterGroup, given an Alignment. 
      if the secind arg is true, In doing indentical sequences in the 
      alignment are merged. If bootstrapping is required, the consensus
      alignment can be extracted from the ClusterGroup using 
      get_consensus_from_ClusterGroup
    RETURNS: struct ClusterGroup
    ARGS: 
      1. A source Alignment pointer
      2. A boolean specifying whether duplicate sequences should be
         merged.
    NOTES: 
  *********************************************************************/
  struct ClusterGroup *alignment_to_ClusterGroup( struct Alignment *,unsigned int);
  
  /********************************************************************* 
   FUNCTION: clone_Cluster
   DESCRIPTION: 
     This function makes a complete copy of the given Cluster
     and returns it
   RETURNS: struct Cluster *
   ARGS: 
     struct Cluster *
   NOTES: 
   *********************************************************************/
  struct Cluster *clone_Cluster( struct Cluster *);
  
  /*********************************************************************
    FUNCTION: consensus_aln_from_ClusterGroup
    DESCRIPTION: 
      This function creates an alignment by taking the consensus 
      sequences from each Cluster in the given ClusterGroup
    RETURNS: struct ClusterGroup
    ARGS: 
      1. A source Alignment pointer
      2. A boolean specifying whether duplicate sequences should be
         merged.
    NOTES: 
  *********************************************************************/
  struct Alignment *consensus_aln_from_ClusterGroup( struct ClusterGroup *);
  
  /********************************************************************* 
   FUNCTION: empty_Cluster
   DESCRIPTION: 
     This function handles the simple task of allocating the space
     for a new Cluster.
   RETURNS: struct Cluster *
   ARGS: 
   NOTES: 
   *********************************************************************/
  struct Cluster *empty_Cluster( void );
  
  /********************************************************************* 
   FUNCTION: empty_ClusterGroup
   DESCRIPTION: 
     This function handles the simple task of allocating the space
     for a new ClusterGroup
   RETURNS: struct Cluster *
   ARGS: 
   NOTES: 
   *********************************************************************/
  struct ClusterGroup *empty_ClusterGroup( void );
  
  /********************************************************************* 
   FUNCTION: free_Cluster
   DESCRIPTION: 
     This function releases the memory used by this Cluster and all of its
     members
   RETURNS: A null pointer
   ARGS: 
     struct Cluster *
   NOTES: 
   *********************************************************************/
  void *free_Cluster( struct Cluster *);
  
  /********************************************************************* 
   FUNCTION: free_ClusterGroup
   DESCRIPTION: 
     This function releases the memory used by this Cluster and all of its
     members
   RETURNS: A null pointer
   ARGS: 
     struct Cluster *
   NOTES: 
   *********************************************************************/
  void *free_ClusterGroup( struct ClusterGroup *);
  
  /********************************************************************* 
   FUNCTION: merge_Cluster
   DESCRIPTION: 
     Adds the sequences in second arg to first arg, freeing the second
     arg, returning the result of this freeing (hopefully NULL);
   RETURNS: The result of freeing the second cluster (NULL if all is well)
   ARGS: 
     Destination Cluster *, 
     Source Cluster *
   NOTES:
   *********************************************************************/
  void *merge_Cluster( struct Cluster *, struct Cluster *);
  
  /********************************************************************* 
   FUNCTION: single_Sequence_Cluster
   DESCRIPTION: 
     This function handles the simple task of allocating the space
     for a new Cluster with the single given Sequence.
   RETURNS: struct Cluster *
   ARGS: 
     A pointer to a Sequence, or NULL for an empty Cluster
   NOTES: 
   *********************************************************************/
  struct Cluster *single_Sequence_Cluster( struct Sequence *);
  
  /********************************************************************* 
   FUNCTION: single_Cluster_ClusterGroup
   DESCRIPTION: 
     This function takes the given cluster and very simlpy makes a 
     single-Cluster ClusterGroup from it
   RETURNS: struct ClusterGroup *
   ARGS: 
     A pointer to a Cluster
   NOTES: 
   *********************************************************************/
  struct ClusterGroup *single_Cluster_ClusterGroup( struct Cluster *);
  
  
  #endif
  