/*
   File:        freq.h
   Author:      Jeff Schneider
   Created:     Wed Aug 11 18:19:00 EDT 1999
   Description: Utilities for finding frequent sets in datsets

   Copyright 1999, Jeff Schneider
*/

#ifndef FREQ_H
#define FREQ_H

#include "dsut.h"

/* The following structure is used to store records that are included
   in the same group.  row points to one row of a datset, and the list
   represents the set of rows that should be processed as one group.
 */
typedef struct matchlist
{
  int row;
  int count; 
  struct matchlist *next;
} matchlist;

/* Use this if you need to have a shell whose pointer won't change even
   though the head of a sorted matchlist may.  Specifically, this was
   written for people who want to store matchlists in hash tables and
   continue to update the lists contents without deleting and re-inserting
   the list into the table every time.
*/
typedef struct matchlist_head
{
  matchlist *head;
} matchlist_head;

/* This function creates a new datset from an existing one.  The new datset
   represents the frequent sets appearing in the original one.  The parameters
   are as follows:

   ds        - an existing datset, from which the new one will be built.

   matchatts - rows in ds will be considered to be a group if matchatts
               contain the same value.  for example, if you have a list
               of product orders, you might specify the date field and
               the customer id field here to indicate that you want to 
               group orders together by date and customer.  the goal in 
               that case might be to find out which sets of products 
               commonly get ordered together.  there are two special cases:
               matchatts is 0 length - all records are grouped together.
                                       this is included for completeness,
                                       but probably has no practical use.
               matchatts is NULL     - all records are treated independently.
                                       this usually only makes sense if
                                       the size of freqatts is greater than 1

   freqatts  - these are the attributes you are looking for frequent sets of.
               in the previous example, this would be the product ids.  note
               that it is perfectly valid to have more than one attribute
               listed here.  for example, if you wanted to find common
               customer/product combinations (that customer commonly orders
               that product), then you would leave matchatts NULL, but put
               both product and customer in freqatts.

   setsize   - this indicates the maximum size of the sets.  for example, if
               you're interested in finding common pairs of products, you
               would set this to 2.  If you're interested in common triples, 
               you set it to 3, etc.

   minsetcount - the minimum number of records that must have these 
                 co-occurring freqatts values in order for it to be included
                 in the output.  for example, you may want to only include
                 pairs of products that were ordered together at least 10
                 times in the datset.

   Note that the size of the resulting datset can be very large.  You are
   at a greater risk of creating a large datset if you choose a large setsize,
   because the number of possible tuples gets large.  The easiest way to
   combat this is to increase minsetcount, because the number of them actually
   occurring a large number of times may still be small.
*/
datset *mk_frequent_datset(datset *ds, ivec *matchatts, ivec *freqatts,
                           int setsize, int minsetcount);


#endif /* FREQ_H */
