crfsuite.h

/*
 *      CRFsuite library.
 *
 * Copyright (c) 2007-2010, Naoaki Okazaki
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the names of the authors nor the names of its contributors
 *       may be used to endorse or promote products derived from this
 *       software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "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 COPYRIGHT OWNER
 * OR CONTRIBUTORS 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.
 */

/* $Id$ */

#ifndef    __CRFSUITE_H__
#define    __CRFSUITE_H__

#ifdef    __cplusplus
extern "C" {
#endif/*__cplusplus*/

#include <stdio.h>
#include <stdarg.h>

/** 
 * \addtogroup crfsuite_api CRFSuite C API
 * @{
 *
 *  The CRFSuite C API provides a low-level library for manupulating
 *  CRFSuite in C language.
 */

/** 
 * \addtogroup crfsuite_misc Miscellaneous definitions and functions
 * @{
 */

/** Version number of CRFSuite library. */
#define CRFSUITE_VERSION    "0.12.2"

/** Copyright string of CRFSuite library. */
#define CRFSUITE_COPYRIGHT  "Copyright (c) 2007-2013 Naoaki Okazaki"

/** Type of a float value. */
typedef double floatval_t;

/** Maximum value of a float value. */
#define    FLOAT_MAX    DBL_MAX

/**
 * Status codes.
 */
enum {
    /** Success. */
    CRFSUITE_SUCCESS = 0,
    /** Unknown error occurred. */
    CRFSUITEERR_UNKNOWN = 0x80000000,
    /** Insufficient memory. */
    CRFSUITEERR_OUTOFMEMORY,
    /** Unsupported operation. */
    CRFSUITEERR_NOTSUPPORTED,
    /** Incompatible data. */
    CRFSUITEERR_INCOMPATIBLE,
    /** Internal error. */
    CRFSUITEERR_INTERNAL_LOGIC,
    /** Overflow. */
    CRFSUITEERR_OVERFLOW,
    /** Not implemented. */
    CRFSUITEERR_NOTIMPLEMENTED,
};

/**@}*/



/**
 * \addtogroup crfsuite_object Object interfaces and utilities.
 * @{
 */

struct tag_crfsuite_model;
/** CRFSuite model interface. */
typedef struct tag_crfsuite_model crfsuite_model_t;

struct tag_crfsuite_trainer;
/** CRFSuite trainer interface. */
typedef struct tag_crfsuite_trainer crfsuite_trainer_t;

struct tag_crfsuite_tagger;
/** CRFSuite tagger interface. */
typedef struct tag_crfsuite_tagger crfsuite_tagger_t;

struct tag_crfsuite_dictionary;
/** CRFSuite dictionary interface. */
typedef struct tag_crfsuite_dictionary crfsuite_dictionary_t;

struct tag_crfsuite_params;
/** CRFSuite parameter interface. */
typedef struct tag_crfsuite_params crfsuite_params_t;

/**@}*/



/**
 * \addtogroup crfsuite_data Dataset (attribute, item, instance, dataset)
 * @{
 */

/**
 * An attribute.
 *  An attribute consists of an attribute id with its value.
 */
typedef struct {
    int         aid;                /**< Attribute id. */
    floatval_t  value;              /**< Value of the attribute. */
} crfsuite_attribute_t;

/**
 * An item.
 *  An item consists of an array of attributes.
 */
typedef struct {
    /** Number of contents associated with the item. */
    int             num_contents;
    /** Maximum number of contents (internal use). */
    int             cap_contents;
    /** Array of the attributes. */
    crfsuite_attribute_t    *contents;
} crfsuite_item_t;

/**
 * An instance (sequence of items and labels).
 *  An instance consists of a sequence of items and labels.
 */
typedef struct {
    /** Number of items/labels in the sequence. */
    int         num_items;
    /** Maximum number of items/labels (internal use). */
    int         cap_items;
    /** Array of the item sequence. */
    crfsuite_item_t  *items;
    /** Array of the label sequence. */
    int         *labels;
    /** Instance weight. */
    floatval_t  weight;
    /** Group ID of the instance. */
	int         group;
} crfsuite_instance_t;

/**
 * A data set.
 *  A data set consists of an array of instances and dictionary objects
 *  for attributes and labels.
 */
typedef struct {
    /** Number of instances. */
    int                 num_instances;
    /** Maximum number of instances (internal use). */
    int                 cap_instances;
    /** Array of instances. */
    crfsuite_instance_t*     instances;

    /** Dictionary object for attributes. */
    crfsuite_dictionary_t    *attrs;
    /** Dictionary object for labels. */
    crfsuite_dictionary_t    *labels;
} crfsuite_data_t;

/**@}*/



/**
 * \addtogroup crfsuite_evaluation Evaluation utility
 * @{
 */

/**
 * Label-wise performance values.
 */
typedef struct {
    /** Number of correct predictions. */
    int         num_correct;
    /** Number of occurrences of the label in the gold-standard data. */
    int         num_observation;
    /** Number of predictions. */
    int         num_model;
    /** Precision. */
    floatval_t  precision;
    /** Recall. */
    floatval_t  recall;
    /** F1 score. */
    floatval_t  fmeasure;
} crfsuite_label_evaluation_t;

/**
 * An overall performance values.
 */
typedef struct {
    /** Number of labels. */
    int         num_labels;
    /** Array of label-wise evaluations. */
    crfsuite_label_evaluation_t* tbl;

    /** Number of correctly predicted items. */
    int         item_total_correct;
    /** Total number of items. */
    int         item_total_num;
    /** Total number of occurrences of labels in the gold-standard data. */
    int         item_total_observation;
    /** Total number of predictions. */
    int         item_total_model;
    /** Item-level accuracy. */
    floatval_t  item_accuracy;

    /** Number of correctly predicted instances. */
    int         inst_total_correct;
    /** Total number of instances. */
    int         inst_total_num;
    /** Instance-level accuracy. */
    floatval_t  inst_accuracy;

    /** Macro-averaged precision. */
    floatval_t  macro_precision;
    /** Macro-averaged recall. */
    floatval_t  macro_recall;
    /** Macro-averaged F1 score. */
    floatval_t  macro_fmeasure;
} crfsuite_evaluation_t;

/**@}*/


/**
 * \addtogroup crfsuite_object
 * @{
 */

/**
 * Type of callback function for logging.
 *  @param  user        Pointer to the user-defined data.
 *  @param  format      Format string (compatible with prinf()).
 *  @param  args        Optional arguments for the format string.
 *  @return int         \c 0 to continue; non-zero to cancel the training.
 */
typedef int (*crfsuite_logging_callback)(void *user, const char *format, va_list args);


/**
 * CRFSuite model interface.
 */
struct tag_crfsuite_model {
    /**
     * Pointer to the internal data (internal use only).
     */
    void *internal;
    
    /**
     * Reference counter (internal use only).
     */
    int nref;

    /**
     * Increment the reference counter.
     *  @param  model       The pointer to this model instance.
     *  @return int         The reference count after this increment.
     */
    int (*addref)(crfsuite_model_t* model);

    /**
     * Decrement the reference counter.
     *  @param  model       The pointer to this model instance.
     *  @return int         The reference count after this operation.
     */
    int (*release)(crfsuite_model_t* model);

    /**
     * Obtain the pointer to crfsuite_tagger_t interface.
     *  @param  model       The pointer to this model instance.
     *  @param  ptr_tagger  The pointer that receives a crfsuite_tagger_t
     *                      pointer.
     *  @return int         The status code.
     */
    int (*get_tagger)(crfsuite_model_t* model, crfsuite_tagger_t** ptr_tagger);

    /**
     * Obtain the pointer to crfsuite_dictionary_t interface for labels.
     *  @param  model       The pointer to this model instance.
     *  @param  ptr_labels  The pointer that receives a crfsuite_dictionary_t
     *                      pointer.
     *  @return int         The status code.
     */
    int (*get_labels)(crfsuite_model_t* model, crfsuite_dictionary_t** ptr_labels);

    /**
     * Obtain the pointer to crfsuite_dictionary_t interface for attributes.
     *  @param  model       The pointer to this model instance.
     *  @param  ptr_attrs   The pointer that receives a crfsuite_dictionary_t
     *                      pointer.
     *  @return int         The status code.
     */
    int (*get_attrs)(crfsuite_model_t* model, crfsuite_dictionary_t** ptr_attrs);

    /**
     * Print the model in human-readable format.
     *  @param  model       The pointer to this model instance.
     *  @param  fpo         The FILE* pointer.
     *  @return int         The status code.
     */
    int (*dump)(crfsuite_model_t* model, FILE *fpo);
};



/**
 * CRFSuite trainer interface.
 */
struct tag_crfsuite_trainer {
    /**
     * Pointer to the internal data (internal use only).
     */
    void *internal;
    
    /**
     * Reference counter (internal use only).
     */
    int nref;

    /**
     * Increment the reference counter.
     *  @param  trainer     The pointer to this trainer instance.
     *  @return int         The reference count after this increment.
     */
    int (*addref)(crfsuite_trainer_t* trainer);

    /**
     * Decrement the reference counter.
     *  @param  trainer     The pointer to this trainer instance.
     *  @return int         The reference count after this operation.
     */
    int (*release)(crfsuite_trainer_t* trainer);

    /**
     * Obtain the pointer to crfsuite_params_t interface.
     *  @param  trainer     The pointer to this trainer instance.
     *  @return crfsuite_params_t*  The pointer to crfsuite_params_t.
     */
    crfsuite_params_t* (*params)(crfsuite_trainer_t* trainer);

    /**
     * Set the callback function and user-defined data.
     *  @param  trainer     The pointer to this trainer instance.
     *  @param  user        The pointer to the user-defined data.
     *  @param  cbm         The pointer to the callback function.
     */
    void (*set_message_callback)(crfsuite_trainer_t* trainer, void *user, crfsuite_logging_callback cbm);

    /**
     * Start a training process.
     *  @param  trainer     The pointer to this trainer instance.
     *  @param  data        The poiinter to the data set.
     *  @param  filename    The filename to which the trainer stores the model.
     *                      If an empty string is specified, this function
     *                      does not sture the model to a file.
     *  @param  holdout     The holdout group.
     *  @return int         The status code.
     */
    int (*train)(crfsuite_trainer_t* trainer, const crfsuite_data_t *data, const char *filename, int holdout);
};

/**
 * CRFSuite tagger interface.
 */
struct tag_crfsuite_tagger {
    /**
     * Pointer to the internal data (internal use only).
     */
    void *internal;

    /**
     * Reference counter (internal use only).
     */
    int nref;

    /**
     * Increment the reference counter.
     *  @param  tagger      The pointer to this tagger instance.
     *  @return int         The reference count after this increment.
     */
    int (*addref)(crfsuite_tagger_t* tagger);

    /**
     * Decrement the reference counter.
     *  @param  tagger      The pointer to this tagger instance.
     *  @return int         The reference count after this operation.
     */
    int (*release)(crfsuite_tagger_t* tagger);

    /**
     * Set an instance to the tagger.
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  inst        The item sequence to be tagged.
     *  @return int         The status code.
     */
    int (*set)(crfsuite_tagger_t* tagger, crfsuite_instance_t *inst);

    /**
     * Obtain the number of items in the current instance.
     *  @param  tagger      The pointer to this tagger instance.
     *  @return int         The number of items of the instance set by
     *                      set() function.
     *  @return int         The status code.
     */
    int (*length)(crfsuite_tagger_t* tagger);

    /**
     * Find the Viterbi label sequence.
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  labels      The label array that receives the Viterbi label
     *                      sequence. The number of elements in the array must
     *                      be no smaller than the number of item.
     *  @param  ptr_score   The pointer to a float variable that receives the
     *                      score of the Viterbi label sequence.
     *  @return int         The status code.
     */
    int (*viterbi)(crfsuite_tagger_t* tagger, int *labels, floatval_t *ptr_score);

    /**
     * Compute the score of a label sequence.
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  path        The label sequence.
     *  @param  ptr_score   The pointer to a float variable that receives the
     *                      score of the label sequence.
     *  @return int         The status code.
     */
    int (*score)(crfsuite_tagger_t* tagger, int *path, floatval_t *ptr_score);

    /**
     * Compute the log of the partition factor (normalization constant).
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  ptr_score   The pointer to a float variable that receives the
     *                      logarithm of the partition factor.
     *  @return int         The status code.
     */
    int (*lognorm)(crfsuite_tagger_t* tagger, floatval_t *ptr_norm);

    /**
     * Compute the marginal probability of a label at a position.
     *  This function computes P(y_t = l | x), the probability when
     *  y_t is the label (l).
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  l           The label.
     *  @param  t           The position.
     *  @param  ptr_prob    The pointer to a float variable that receives the
     *                      marginal probability.
     *  @return int         The status code.
     */
    int (*marginal_point)(crfsuite_tagger_t *tagger, int l, int t, floatval_t *ptr_prob);

    /**
     * Compute the marginal probability of a partial label sequence.
     *  @param  tagger      The pointer to this tagger instance.
     *  @param  path        The partial label sequence.
     *  @param  begin       The start position of the partial label sequence.
     *  @param  end         The last+1 position of the partial label sequence.
     *  @param  ptr_prob    The pointer to a float variable that receives the
     *                      marginal probability.
     *  @return int         The status code.
     */
    int (*marginal_path)(crfsuite_tagger_t *tagger, const int *path, int begin, int end, floatval_t *ptr_prob);
};

/**
 * CRFSuite dictionary interface.
 */
struct tag_crfsuite_dictionary {
    /**
     * Pointer to the internal data (internal use only).
     */
    void *internal;

    /**
     * Reference counter (internal use only).
     */
    int nref;

    /**
     * Increment the reference counter.
     *  @param  dic         The pointer to this dictionary instance.
     *  @return int         The reference count after this increment.
     */
    int (*addref)(crfsuite_dictionary_t* dic);

    /**
     * Decrement the reference counter.
     *  @param  dic         The pointer to this dictionary instance.
     *  @return int         The reference count after this operation.
     */
    int (*release)(crfsuite_dictionary_t* dic);

    /**
     * Assign and obtain the integer ID for the string.
     *  @param  dic         The pointer to this dictionary instance.
     *  @param  str         The string.
     *  @return int         The ID associated with the string if any,
     *                      the new ID otherwise.
     */
    int (*get)(crfsuite_dictionary_t* dic, const char *str);

    /**
     * Obtain the integer ID for the string.
     *  @param  dic         The pointer to this dictionary instance.
     *  @param  str         The string.
     *  @return int         The ID associated with the string if any,
     *                      \c -1 otherwise.
     */
    int (*to_id)(crfsuite_dictionary_t* dic, const char *str);

    /**
     * Obtain the string for the ID.
     *  @param  dic         The pointer to this dictionary instance.
     *  @param  id          the string ID.
     *  @param  pstr        \c *pstr points to the string associated with
     *                      the ID if any, \c NULL otherwise.
     *  @return int         \c 0 if the string ID is associated with a string,
     *                      \c 1 otherwise.
     */
    int (*to_string)(crfsuite_dictionary_t* dic, int id, char const **pstr);

    /**
     * Obtain the number of strings in the dictionary.
     *  @param  dic         The pointer to this dictionary instance.
     *  @return int         The number of strings stored in the dictionary.
     */
    int (*num)(crfsuite_dictionary_t* dic);

    /**
     * Free the memory block allocated by to_string() function.
     *  @param  dic         The pointer to this dictionary instance.
     *  @param  str         The pointer to the string whose memory block is
     *                      freed.
     */
    void (*free)(crfsuite_dictionary_t* dic, const char *str);
};

/**
 * CRFSuite parameter interface.
 */
struct tag_crfsuite_params {
    /**
     * Pointer to the instance data (internal use only).
     */
    void *internal;

    /**
     * Reference counter (internal use only).
     */
    int nref;

    /**
     * Increment the reference counter.
     *  @param  params      The pointer to this parameter instance.
     *  @return int         The reference count after this increment.
     */
    int (*addref)(crfsuite_params_t* params);

    /**
     * Decrement the reference counter.
     *  @param  params      The pointer to this parameter instance.
     *  @return int         The reference count after this operation.
     */
    int (*release)(crfsuite_params_t* params);

    /**
     * Obtain the number of available parameters.
     *  @param  params      The pointer to this parameter instance.
     *  @return int         The number of parameters maintained by this object.
     */
    int (*num)(crfsuite_params_t* params);

    /**
     * Obtain the name of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  i           The parameter index.
     *  @param  ptr_name    *ptr_name points to the parameter name.
     *  @return int         \c 0 always.
     */
    int (*name)(crfsuite_params_t* params, int i, char **ptr_name);

    /**
     * Set a parameter value.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  value       The parameter value in string format.
     *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
     */
    int (*set)(crfsuite_params_t* params, const char *name, const char *value);

    /**
     * Get a parameter value.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  ptr_value   *ptr_value presents the parameter value in string
     *                      format.
     *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
     */
    int (*get)(crfsuite_params_t* params, const char *name, char **ptr_value);

    /**
     * Set an integer value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  value       The parameter value.
     *  @return int         \c 0 if the parameter value is set successfully,
     *                      \c -1 otherwise (unknown parameter or incompatible
     *                      type).
     */
    int (*set_int)(crfsuite_params_t* params, const char *name, int value);

    /**
     * Set a float value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  value       The parameter value.
     *  @return int         \c 0 if the parameter value is set successfully,
     *                      \c -1 otherwise (unknown parameter or incompatible
     *                      type).
     */
    int (*set_float)(crfsuite_params_t* params, const char *name, floatval_t value);

    /**
     * Set a string value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  value       The parameter value.
     *  @return int         \c 0 if the parameter value is set successfully,
     *                      \c -1 otherwise (unknown parameter or incompatible
     *                      type).
     */
    int (*set_string)(crfsuite_params_t* params, const char *name, const char *value);

    /**
     * Get an integer value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  ptr_value   The pointer to a variable that receives the
     *                      integer value.
     *  @return int         \c 0 if the parameter value is obtained
     *                      successfully, \c -1 otherwise (unknown parameter
     *                      or incompatible type).
     */
    int (*get_int)(crfsuite_params_t* params, const char *name, int *ptr_value);

    /**
     * Get a float value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  ptr_value   The pointer to a variable that receives the
     *                      float value.
     *  @return int         \c 0 if the parameter value is obtained
     *                      successfully, \c -1 otherwise (unknown parameter
     *                      or incompatible type).
     */
    int (*get_float)(crfsuite_params_t* params, const char *name, floatval_t *ptr_value);

    /**
     * Get a string value of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  ptr_value   *ptr_value presents the parameter value.
     *  @return int         \c 0 if the parameter value is obtained
     *                      successfully, \c -1 otherwise (unknown parameter
     *                      or incompatible type).
     */
    int (*get_string)(crfsuite_params_t* params, const char *name, char **ptr_value);

    /**
     * Get the help message of a parameter.
     *  @param  params      The pointer to this parameter instance.
     *  @param  name        The parameter name.
     *  @param  ptr_type    The pointer to \c char* to which this function
     *                      store the type of the parameter.
     *  @param  ptr_help    The pointer to \c char* to which this function
     *                      store the help message of the parameter.
     *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
     */
    int (*help)(crfsuite_params_t* params, const char *name, char **ptr_type, char **ptr_help);

    /**
     * Free the memory block of a string allocated by this object.
     *  @param  params      The pointer to this parameter instance.
     *  @param  str         The pointer to the string.
     */
    void (*free)(crfsuite_params_t* params, const char *str);
};

/**@}*/



/**
 * \addtogroup crfsuite_object
 * @{
 */

/**
 * Create an instance of an object by an interface identifier.
 *  @param  iid         The interface identifier.
 *  @param  ptr         The pointer to \c void* that points to the
 *                      instance of the object if successful,
 *                      *ptr points to \c NULL otherwise.
 *  @return int         \c 1 if this function creates an object successfully,
 *                      \c 0 otherwise. Note that this is inconsistent with the
 *                      other CRFsuite API calls.
 */
int crfsuite_create_instance(const char *iid, void **ptr);

/**
 * Create an instance of a model object from a model file.
 *  @param  filename    The filename of the model.
 *  @param  ptr         The pointer to \c void* that points to the
 *                      instance of the model object if successful,
 *                      *ptr points to \c NULL otherwise.
 *  @return int         \c 0 if this function creates an object successfully,
 *                      \c 1 otherwise.
 */
int crfsuite_create_instance_from_file(const char *filename, void **ptr);

/**
 * Create an instance of a model object from a model in memory.
 *  @param  data        A pointer to the model data.
 *                      Must be 16-byte aligned.
 *  @param  size        A size (in bytes) of the model data.
 *  @param  ptr         The pointer to \c void* that points to the
 *                      instance of the model object if successful,
 *                      *ptr points to \c NULL otherwise.
 *  @return int         \c 0 if this function creates an object successfully,
 *                      \c 1 otherwise
 */
int crfsuite_create_instance_from_memory(const void *data, size_t size, void **ptr);

/**
 * Create instances of tagging object from a model file.
 *  @param  filename    The filename of the model.
 *  @param  ptr_tagger  The pointer to \c void* that points to the
 *                      instance of the tagger object if successful,
 *                      *ptr points to \c NULL otherwise.
 *  @param  ptr_attrs   The pointer to \c void* that points to the
 *                      instance of the dictionary object for attributes
 *                      if successful, *ptr points to \c NULL otherwise.
 *  @param  ptr_labels  The pointer to \c void* that points to the
 *                      instance of the dictionary object for labels
 *                      if successful, *ptr points to \c NULL otherwise.
 *  @return int         \c 0 if this function creates an object successfully,
 *                      \c 1 otherwise.
 */
int crfsuite_create_tagger(
    const char *filename,
    crfsuite_tagger_t** ptr_tagger,
    crfsuite_dictionary_t** ptr_attrs,
    crfsuite_dictionary_t** ptr_labels
    );

/**@}*/



/**
 * \addtogroup crfsuite_data
 * @{
 */

/**
 * Initialize an attribute structure.
 *  @param  attr        The pointer to crfsuite_attribute_t.
 */
void crfsuite_attribute_init(crfsuite_attribute_t* attr);

/**
 * Set an attribute and its value.
 *  @param  attr        The pointer to crfsuite_attribute_t.
 *  @param  aid         The attribute identifier.
 *  @param  value       The attribute value.
 */
void crfsuite_attribute_set(crfsuite_attribute_t* attr, int aid, floatval_t value);

/**
 * Copy the content of an attribute structure.
 *  @param  dst         The pointer to the destination.
 *  @param  src         The pointer to the source.
 */
void crfsuite_attribute_copy(crfsuite_attribute_t* dst, const crfsuite_attribute_t* src);

/**
 * Swap the contents of two attribute structures.
 *  @param  x           The pointer to an attribute structure.
 *  @param  y           The pointer to another attribute structure.
 */
void crfsuite_attribute_swap(crfsuite_attribute_t* x, crfsuite_attribute_t* y);

/**
 * Initialize an item structure.
 *  @param  item        The pointer to crfsuite_item_t.
 */
void crfsuite_item_init(crfsuite_item_t* item);

/**
 * Initialize an item structure with the number of attributes.
 *  @param  item        The pointer to crfsuite_item_t.
 *  @param  num_attributes  The number of attributes.
 */
void crfsuite_item_init_n(crfsuite_item_t* item, int num_attributes);

/**
 * Uninitialize an item structure.
 *  @param  item        The pointer to crfsuite_item_t.
 */
void crfsuite_item_finish(crfsuite_item_t* item);

/**
 * Copy the content of an item structure.
 *  @param  dst         The pointer to the destination.
 *  @param  src         The pointer to the source.
 */
void crfsuite_item_copy(crfsuite_item_t* dst, const crfsuite_item_t* src);

/**
 * Swap the contents of two item structures.
 *  @param  x           The pointer to an item structure.
 *  @param  y           The pointer to another item structure.
 */
void crfsuite_item_swap(crfsuite_item_t* x, crfsuite_item_t* y);

/**
 * Append an attribute to the item structure.
 *  @param  item        The pointer to crfsuite_item_t.
 *  @param  attr        The attribute to be added to the item.
 *  @return int         \c 0 if successful, \c -1 otherwise.
 */
int  crfsuite_item_append_attribute(crfsuite_item_t* item, const crfsuite_attribute_t* attr);

/**
 * Check whether the item has no attribute.
 *  @param  item        The pointer to crfsuite_item_t.
 *  @return int         \c 1 if the item has no attribute, \c 0 otherwise.
 */
int  crfsuite_item_empty(crfsuite_item_t* item);



/**
 * Initialize an instance structure.
 *  @param  seq         The pointer to crfsuite_instance_t.
 */
void crfsuite_instance_init(crfsuite_instance_t* seq);

/**
 * Initialize an instance structure with the number of items.
 *  @param  seq         The pointer to crfsuite_instance_t.
 *  @param  num_items   The number of items.
 */
void crfsuite_instance_init_n(crfsuite_instance_t* seq, int num_items);

/**
 * Uninitialize an instance structure.
 *  @param  seq         The pointer to crfsuite_instance_t.
 */
void crfsuite_instance_finish(crfsuite_instance_t* seq);

/**
 * Copy the content of an instance structure.
 *  @param  dst         The pointer to the destination.
 *  @param  src         The pointer to the source.
 */
void crfsuite_instance_copy(crfsuite_instance_t* dst, const crfsuite_instance_t* src);

/**
 * Swap the contents of two instance structures.
 *  @param  x           The pointer to an instance structure.
 *  @param  y           The pointer to another instance structure.
 */
void crfsuite_instance_swap(crfsuite_instance_t* x, crfsuite_instance_t* y);

/**
 * Append a pair of item and label to the instance structure.
 *  @param  seq         The pointer to crfsuite_instance_t.
 *  @param  item        The item to be added to the instance.
 *  @param  label       The label to be added to the instance.
 *  @return int         \c 0 if successful, \c -1 otherwise.
 */
int  crfsuite_instance_append(crfsuite_instance_t* seq, const crfsuite_item_t* item, int label);

/**
 * Check whether the instance has no item.
 *  @param  seq         The pointer to crfsuite_instance_t.
 *  @return int         \c 1 if the instance has no attribute, \c 0 otherwise.
 */
int  crfsuite_instance_empty(crfsuite_instance_t* seq);



/**
 * Initialize a dataset structure.
 *  @param  data        The pointer to crfsuite_data_t.
 */
void crfsuite_data_init(crfsuite_data_t* data);

/**
 * Initialize a dataset structure with the number of instances.
 *  @param  data        The pointer to crfsuite_data_t.
 *  @param  n           The number of instances.
 */
void crfsuite_data_init_n(crfsuite_data_t* data, int n);

/**
 * Uninitialize a dataset structure.
 *  @param  data        The pointer to crfsuite_data_t.
 */
void crfsuite_data_finish(crfsuite_data_t* data);

/**
 * Copy the content of a dataset structure.
 *  @param  dst         The pointer to the destination.
 *  @param  src         The pointer to the source.
 */
void crfsuite_data_copy(crfsuite_data_t* dst, const crfsuite_data_t* src);

/**
 * Swap the contents of two dataset structures.
 *  @param  x           The pointer to a dataset structure.
 *  @param  y           The pointer to another dataset structure.
 */
void crfsuite_data_swap(crfsuite_data_t* x, crfsuite_data_t* y);

/**
 * Append an instance to the dataset structure.
 *  @param  data        The pointer to crfsuite_data_t.
 *  @param  inst        The instance to be added to the dataset.
 *  @return int         \c 0 if successful, \c -1 otherwise.
 */
int  crfsuite_data_append(crfsuite_data_t* data, const crfsuite_instance_t* inst);

/**
 * Obtain the maximum length of the instances in the dataset.
 *  @param  data        The pointer to crfsuite_data_t.
 *  @return int         The maximum number of items of the instances in the
 *                      dataset.
 */
int  crfsuite_data_maxlength(crfsuite_data_t* data);

/**
 * Obtain the total number of items in the dataset.
 *  @param  data        The pointer to crfsuite_data_t.
 *  @return int         The total number of items in the dataset.
 */
int  crfsuite_data_totalitems(crfsuite_data_t* data);

/**@}*/

/**
 * \addtogroup crfsuite_evaluation
 */
/**@{*/

/**
 * Initialize an evaluation structure.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 *  @param  n           The number of labels in the dataset.
 */
void crfsuite_evaluation_init(crfsuite_evaluation_t* eval, int n);

/**
 * Uninitialize an evaluation structure.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 */
void crfsuite_evaluation_finish(crfsuite_evaluation_t* eval);

/**
 * Reset an evaluation structure.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 */
void crfsuite_evaluation_clear(crfsuite_evaluation_t* eval);

/**
 * Accmulate the correctness of the predicted label sequence.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 *  @param  reference   The reference label sequence.
 *  @param  prediction  The predicted label sequence.
 *  @param  T           The length of the label sequence.
 *  @return int         \c 0 if succeeded, \c 1 otherwise.
 */
int crfsuite_evaluation_accmulate(crfsuite_evaluation_t* eval, const int* reference, const int* prediction, int T);

/**
 * Finalize the evaluation result.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 */
void crfsuite_evaluation_finalize(crfsuite_evaluation_t* eval);

/**
 * Print the evaluation result.
 *  @param  eval        The pointer to crfsuite_evaluation_t.
 *  @param  labels      The pointer to the label dictionary.
 *  @param  cbm         The callback function to receive the evaluation result.
 *  @param  user        The pointer to the user data that is forwarded to the
 *                      callback function.
 */
void crfsuite_evaluation_output(crfsuite_evaluation_t* eval, crfsuite_dictionary_t* labels, crfsuite_logging_callback cbm, void *user);

/**@}*/



/** 
 * \addtogroup crfsuite_misc Miscellaneous definitions and functions
 * @{
 */

/**
 * Increments the value of the integer variable as an atomic operation.
 *  @param  count       The pointer to the integer variable.
 *  @return             The value after this increment.
 */
int crfsuite_interlocked_increment(int *count);

/**
 * Decrements the value of the integer variable as an atomic operation.
 *  @param  count       The pointer to the integer variable.
 *  @return             The value after this decrement.
 */
int crfsuite_interlocked_decrement(int *count);

/**@}*/

/**@}*/

/**
@mainpage CRFsuite: a fast implementation of Conditional Random Fields (CRFs)

@section intro Introduction

This document describes information for using
<a href="http://www.chokkan.org/software/crfsuite">CRFsuite</a> from external
programs. CRFsuite provides two APIs:
- @link crfsuite_api C API @endlink: low-level and complete interface, which
  is used by the official frontend program.
- @link crfsuite_hpp_api C++/SWIG API @endlink: high-level and easy-to-use
  interface for a number of programming languages (e.g, C++ and Python),
  which is a wrapper for the C API.

*/


#ifdef    __cplusplus
}
#endif/*__cplusplus*/

#endif/*__CRFSUITE_H__*/