GISTrainer (Apache OpenNLP Tools 2.5.9 API)
Description: declaration: package: opennlp.tools.ml.maxent, class: GISTrainer

# Class GISTrainer

java.lang.Object
opennlp.tools.ml.AbstractTrainer
opennlp.tools.ml.AbstractEventTrainer
opennlp.tools.ml.maxent.GISTrainer

All Implemented Interfaces:
  `Trainer, EventTrainer`

public class GISTrainer extends AbstractEventTrainer
An implementation of Generalized Iterative Scaling (GIS).

The reference paper for this implementation was Adwait Ratnaparkhi's tech report at the University of Pennsylvania's Institute for Research in Cognitive Science, and is available at ftp://ftp.cis.upenn.edu/pub/ircs/tr/97-08.ps.Z.

The slack parameter used in the above implementation has been removed by default from the computation and a method for updating with Gaussian smoothing has been added per Investigating GIS and Smoothing for Maximum Entropy Taggers, Clark and Curran (2002). http://acl.ldc.upenn.edu/E/E03/E03-1071.pdf.

The slack parameter can be used by setting `useSlackParameter` to `true`. Gaussian smoothing can be used by setting `useGaussianSmoothing` to `true`.

A `Prior` can be used to train models which converge to the distribution which minimizes the relative entropy between the distribution specified by the empirical constraints of the training data and the specified prior. By default, the uniform distribution is used as the prior.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final double`
  `LOG_LIKELIHOOD_THRESHOLD_DEFAULT`
  `static final String`
  `LOG_LIKELIHOOD_THRESHOLD_PARAM`
  `static final String`
  `MAXENT_VALUE`

  ### Fields inherited from class AbstractEventTrainer

  `DATA_INDEXER_ONE_PASS_REAL_VALUE, DATA_INDEXER_ONE_PASS_VALUE, DATA_INDEXER_PARAM, DATA_INDEXER_TWO_PASS_VALUE`

  ### Fields inherited from interface EventTrainer

  `EVENT_VALUE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GISTrainer()`
  Initializes a `GISTrainer`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MaxentModel`
  `doTrain(DataIndexer indexer)`
  `void`
  `init(TrainingParameters trainingParameters, Map<String,String> reportMap)`
  Initializes a `AbstractTrainer` via `TrainingParameters` and a `report map`.
  `boolean`
  `isSortAndMerge()`
  `void`
  `setGaussianSigma(double sigmaValue)`
  Sets whether this trainer will use smoothing while training the model.
  `void`
  `setSmoothing(boolean smooth)`
  Sets whether this trainer will use smoothing while training the model.
  `void`
  `setSmoothingObservation(double timesSeen)`
  Sets whether this trainer will use smoothing while training the model.
  `GISModel`
  `trainModel(int iterations, DataIndexer di)`
  Trains a model using the GIS algorithm.
  `GISModel`
  `trainModel(int iterations, DataIndexer di, int threads)`
  Trains a model using the GIS algorithm.
  `GISModel`
  `trainModel(int iterations, DataIndexer di, Prior modelPrior, int threads)`
  Trains a model using the GIS algorithm.
  `GISModel`
  `trainModel(ObjectStream<Event> eventStream)`
  Trains a model using the GIS algorithm, assuming 100 iterations and no cutoff.
  `GISModel`
  `trainModel(ObjectStream<Event> eventStream, int iterations, int cutoff)`
  Trains a GIS model on the event in the specified event stream, using the specified number of iterations and the specified count cutoff.

  ### Methods inherited from class AbstractEventTrainer

  `getDataIndexer, train, train, validate`

  ### Methods inherited from class AbstractTrainer

  `getAlgorithm, getCutoff, getIterations, getTrainingConfiguration, init`

  ### Methods inherited from class Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface Trainer

  `init`

- ## Field Details

  - ### LOG_LIKELIHOOD_THRESHOLD_PARAM

    public static final String LOG_LIKELIHOOD_THRESHOLD_PARAM
    See Also:
      - Constant Field Values

  - ### LOG_LIKELIHOOD_THRESHOLD_DEFAULT

    public static final double LOG_LIKELIHOOD_THRESHOLD_DEFAULT
    See Also:
      - Constant Field Values

  - ### MAXENT_VALUE

    public static final String MAXENT_VALUE
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### GISTrainer

    public GISTrainer()
    Initializes a `GISTrainer`.

    Note:
    The resulting instance does not print progress messages about training to STDOUT.

- ## Method Details

  - ### isSortAndMerge

    public boolean isSortAndMerge()
    Specified by:
      `isSortAndMerge` in class `AbstractEventTrainer`

  - ### init

    public void init(TrainingParameters trainingParameters, Map<String,String> reportMap)
    Initializes a `AbstractTrainer` via `TrainingParameters` and a `report map`.
    Specified by:
      `init` in interface `Trainer`
    Overrides:
      `init` in class `AbstractTrainer`
    Parameters:
      `trainingParameters` - The `TrainingParameters` to use.
      `reportMap` - The `Map` instance used as report map.

  - ### doTrain

    public MaxentModel doTrain(DataIndexer indexer) throws IOException
    Specified by:
      `doTrain` in class `AbstractEventTrainer`
    Throws:
      `IOException`

  - ### setSmoothing

    public void setSmoothing(boolean smooth)
    Sets whether this trainer will use smoothing while training the model.

    Note:
    This can improve model accuracy, though training will potentially take longer and use more memory. Model size will also be larger.

    Parameters:
      `smooth` - `true` if smoothing is desired, `false` if not.

  - ### setSmoothingObservation

    public void setSmoothingObservation(double timesSeen)
    Sets whether this trainer will use smoothing while training the model.

    Note:
    This can improve model accuracy, though training will potentially take longer and use more memory. Model size will also be larger.

    Parameters:
      `timesSeen` - The "number" of times we want the trainer to imagine it saw a feature that it actually didn't see

  - ### setGaussianSigma

    public void setGaussianSigma(double sigmaValue)
    Sets whether this trainer will use smoothing while training the model.

    Note:
    This can improve model accuracy, though training will potentially take longer and use more memory. Model size will also be larger.

    Parameters:
      `sigmaValue` - The Gaussian sigma value used for smoothing.

  - ### trainModel

    public GISModel trainModel(ObjectStream<Event> eventStream) throws IOException
    Trains a model using the GIS algorithm, assuming 100 iterations and no cutoff.
    Parameters:
      `eventStream` - The `eventStream` holding the data on which this model will be trained.
    Returns:
      A trained `GISModel` which can be used immediately or saved to disk using an `GISModelWriter`.
    Throws:
      `IOException`

  - ### trainModel

    public GISModel trainModel(ObjectStream<Event> eventStream, int iterations, int cutoff) throws IOException
    Trains a GIS model on the event in the specified event stream, using the specified number of iterations and the specified count cutoff.
    Parameters:
      `eventStream` - A `stream` of all events.
      `iterations` - The number of iterations to use for GIS.
      `cutoff` - The number of times a feature must occur to be included.
    Returns:
      A trained `GISModel` which can be used immediately or saved to disk using an `GISModelWriter`.
    Throws:
      `IOException`

  - ### trainModel

    public GISModel trainModel(int iterations, DataIndexer di)
    Trains a model using the GIS algorithm.
    Parameters:
      `iterations` - The number of GIS iterations to perform.
      `di` - The `DataIndexer` used to compress events in memory.
    Returns:
      A trained `GISModel` which can be used immediately or saved to disk using an `GISModelWriter`.
    Throws:
      `IllegalArgumentException` - Thrown if parameters were invalid.

  - ### trainModel

    public GISModel trainModel(int iterations, DataIndexer di, int threads)
    Trains a model using the GIS algorithm.
    Parameters:
      `iterations` - The number of GIS iterations to perform.
      `di` - The `DataIndexer` used to compress events in memory.
      `threads` - The number of thread to train with. Must be greater than `0`.
    Returns:
      A trained `GISModel` which can be used immediately or saved to disk using an `GISModelWriter`.
    Throws:
      `IllegalArgumentException` - Thrown if parameters were invalid.

  - ### trainModel

    public GISModel trainModel(int iterations, DataIndexer di, Prior modelPrior, int threads)
    Trains a model using the GIS algorithm.
    Parameters:
      `iterations` - The number of GIS iterations to perform.
      `di` - The `DataIndexer` used to compress events in memory.
      `modelPrior` - The `Prior` distribution used to train this model.
    Returns:
      A trained `GISModel` which can be used immediately or saved to disk using an `GISModelWriter`.
    Throws:
      `IllegalArgumentException` - Thrown if parameters were invalid.