/*
 * File:                GaussianClusterCreator.java
 * Authors:             Justin Basilico
 * Company:             Sandia National Laboratories
 * Project:             Cognitive Foundry
 *
 * Copyright March 22, 2006, Sandia Corporation.  Under the terms of Contract
 * DE-AC04-94AL85000, there is a non-exclusive license for use of this work by
 * or on behalf of the U.S. Government. Export of this program may require a
 * license from the United States Government. See CopyrightHistory.txt for
 * complete details.
 *
 */

package gov.sandia.cognition.learning.algorithm.clustering.cluster;

import gov.sandia.cognition.annotation.CodeReview;
import gov.sandia.cognition.statistics.distribution.MultivariateGaussian;
import gov.sandia.cognition.math.matrix.Vector;
import gov.sandia.cognition.util.AbstractCloneableSerializable;
import java.util.Collection;

/**
 * The <code>GaussianClusterCreator</code> class implements a ClusterCreator
 * for creating GaussianClusters by fitting a MultivariateGaussian to the
 * given set of example vectors.
 *
 * @author Justin Basilico
 * @since 1.0
 */
@CodeReview(
    reviewer="Kevin R. Dixon",
    date="2008-07-22",
    changesNeeded=false,
    comments={
        "Created default constructor.",
        "Otherwise code looks fine."
    }
)
public class GaussianClusterCreator
    extends AbstractCloneableSerializable
    implements ClusterCreator<GaussianCluster,Vector>
{
    
    /**
     * Default covariance, {@value}
     */
    public static final double DEFAULT_COVARIANCE = 1e-4;
    
    /** 
     * amount to add to the diagonals of the covariance
     * matrix, typically on the order of 1e-4.
     */
    private double defaultCovariance;
    
    /**
     * Default constructor
     */
    public GaussianClusterCreator()
    {
        this( DEFAULT_COVARIANCE );
    }
    
    /**
     * Creates a new instance of GaussianClusterCreator
     * @param defaultCovariance 
     * amount to add to the diagonals of the covariance
     * matrix, typically on the order of 1e-4.
     */
    public GaussianClusterCreator(
        double defaultCovariance )
    {
        super();
        this.setDefaultCovariance( defaultCovariance );
    }

    /**
     * Creates a GaussianCluster from a given set of vectors by fitting a 
     * Gaussian to those vectors.
     *
     * @param  members The members for the new cluster.
     * @return A new GaussianCluster generated by fitting the given members to
     *         a MultivariateGaussian.
     */
    public GaussianCluster createCluster(
        Collection<? extends Vector> members)
    {
        // Generate a gaussian from the data.
        MultivariateGaussian.PDF gaussian =
            MultivariateGaussian.MaximumLikelihoodEstimator.learn(
                members, this.getDefaultCovariance() );
        
        // Return a cluster for that gaussian.
        return new GaussianCluster(members, gaussian);
    }

    /**
     * Getter for defaultCovariance
     * @return 
     * amount to add to the diagonals of the covariance
     * matrix, typically on the order of 1e-4.
     */
    public double getDefaultCovariance()
    {
        return this.defaultCovariance;
    }

    /**
     * Setter for defaultCovariance
     * @param defaultCovariance 
     * amount to add to the diagonals of the covariance
     * matrix, typically on the order of 1e-4.
     */
    public void setDefaultCovariance(
        double defaultCovariance)
    {
        this.defaultCovariance = defaultCovariance;
    }
    
}