/***************************************************************************

                          FILE SEGMENTER.H
 
 (janvier 2004)

Gaetan Peaquin - gaetan.peaquin@free.fr
Cyril Labbe - cyril.labbe@imag.fr 
Dominique Labbe - dominique.labbe@iep.upmf-grenoble.fr

D'après : Pierre HUBERT, Jean-Pierre CARBONNEL et Ali CHAOUCHE, "Segmentation des séries hydrométéorologiques", Journal of hydrology, 110, 1989,349-367.
Et Pierre HUBERT, Cyril LABBE et Dominique LABBE, "Segmentation automatique des corpus", in Annie MORIN et Pascale SEBILLOT (eds), VIe Journées d'Analyse des Données Textuelles,Rennes, IRISA-INRIA, 2002, vol 1, 359-369.

 
****************************************************************************/

#ifndef _SEGMENTER_H
#define _SEGMENTER_H

#include "liste.h"

/// Programme de segmentation d'une série ordonnée
/*
 * Le programme recherche la segmentation optimale, 
 * i.e. réduisant l'écart quadratique à la moyenne sur chaque segment,
 * d'une série (ordonnée dans un premier temps)
 */


/* Variables Globales */

/// nombre d'éléments de la série S admis en traitement
static int n;

/// nombre d'éléments de la sous série de S courante
static int i;

/// ordre de segmentation
static int k;

/// seuil de signification pour le test de Scheffe
static float alpha;

/// taille minimale de segments, en nombre d'elements de S
static int tmin;

/// d[e,f] écart quadratique à la moyenne sur le segment défini par [e;f]
static float d[DEFAULT][DEFAULT];

/// moy[e,f] moyenne sur le segment défini par [e;f]
static float moy[DEFAULT][DEFAULT];

/// D[m,i] écart quadratique à la moyenne sur la segmentation optimale d'ordre m sur la sous série d'ordre i
static float D[DEFAULT][DEFAULT];

/// borne supérieure de variation de k
static int ksup;

/// active ou désactive le test de Scheffe
static int no_scheffe;

/// indique si la série à traiter est décrite avec étiquette ou non
static int no_etiquet;

/// active ou désactive le mode verbeux
static int verb;

/// définit la version à utiliser
static int vers;

/// écart quadratique à la moyenne minimum, tout ordre de segmentation confondu sur la série S complète
static float Dmin = MAXFLOAT;

/// serie[e] valeur du "e"ième élément de la série
static float serie[DEFAULT];

/// etiqu[e] valeur de la "e"ième étiquette de la série
static int etiqu[DEFAULT];

/// active ou désactive la variation automatique du seuil pour le test de Scheffe
static int seuil_variable;

/// l'alpha maximum associé à une segmentation pour un ordre donné
static double max_alpha[DEFAULT];

/// le fichier de requêtes
static char * inputfile = "ProgSegmen.txt";

/// le fichier de donnees
static char * datafile;

/// le fichier de sortie
static char * outputfile;

/// tableau de liste de segments
/**
 * seg[m,i] décrit la segmentation optimale d'ordre m sur la sous série d'ordre i
 * i.e. décrit la liste des différents segments qui la composent
 */
static struct lsegment tlseg[DEFAULT][DEFAULT];

/// talpha[][] liste les alpha associées à une segmentation pour un ordre donné
/**
 * talpha[k][e] est la valeur de alpha maximale associé à la différence
 * entre les "e" et "e+1"ième segments composant la segmentation d'ordre k
 * de telle façon que cette différence satisfasse au test de Scheffe
 */
static float talpha[DEFAULT][DEFAULT];


/* Déclarations de fonctions */

/// Calcul de l'écart quadratique sur une segmentation complète
/**
 * La fonction calcule l'écart quadratique à la moyenne sur la segmentation optimale d'une sous série complète
 * @param k l'ordre de segmentation
 * @param i l'ordre de la sous série considérée
 * @return l'écart quadratique global à la segmentation calculé
 */
float CalculD(int k, int i);


/// Calcul de l'écart quadratique sur un segment
/**
 * La fonction calcule l'écart quadratique à la moyenne sur le segment dont les extrêmités sont fournies en paramètres
 * @param e extrêmité gauche du segment
 * @param f extrêmité droite du segment
 * @return l'écart quadratique local au segment calculé
 */
float Calculd(int e, int f);

/// Initialisation de tableaux
/**
 * La fonction initialise les tableaux d[][] et moy[][] ;
 * ceci afin de pouvoir effectuer des tests au cours du 
 * deroulement de l'algorithme pour eviter des calculs redondants
 * On ne remplit que la partie triangulaire superieure
 * @param b la borne supérieure de dimensions des tableaux (et donc de variation des indices)
 * @return 0 si tout s'est bien déroulé
 */
int InitTab(int b);

/// Test de la validite d'une segmentation
/**
 * La fonction teste si la segmentation est valide
 * au sens du critere de Scheffe
 * @param l la liste de segments à tester
 * @param alpha le seuil de signification du test de Scheffe
 * @return la validité de la segmentation 
 */
int EstValideSeg(struct lsegment * l,float alpha);

/// Lecture de la série ordonnée
/**
 * La fonction lit le fichier décrivant la série ordonnée 
 * et la sauvegarde dans un tableau
 * @param datafile le nom du fichier décrivant la série
 * @param outputfile le nom du fichier de sortie
 * @param s le tableau de sauvegarde de la série
 * @param t la taille de la série
 * @return 0 si tout s'est bien déroulé
 */
int Lecture(char * datafile, float * s, int * t);

/// Ecriture des résultats
/**
 * La fonction écrit les caractéristiques des segmentations
 * calculées dans le fichier résultat
 * @param k l'ordre de segmentation courante
 * @param l la description de cette segmentation
 * @return 0 si tout s'est bien déroulé
 */
int Ecriture(int k,struct lsegment * s);

/// Ecriture des caractéristiques de l'éxecution
/**
 * La fonction écrit les caractérisitques d'éxecution 
 * du programme et des informations supplémentaires
 * sur chaque segmentation calculée
 * @param k l'ordre de segmentation final
 * @return 0 si tout s'est bien déroulé
 */
int EcritureCarac(int k);

/// Initialisation de variables
/**
 * La fonction initialise certaines variables selon les options
 * spécifiées par l'utilisateur au lancement du programme
 * @param argc le nombre d'arguments
 * @param argv les arguments
 * @return 0 si tout s'est bien déroulé
 */
int InitVar(int argc, char * argv[]);

/// Affichage de la liste de segments
/**
 * @param s la liste de segments concernée
 */
void Afficherlseg(struct lsegment * s);

#endif // _SEGMENTER_H