/*
Copyright (C) 2009 Ueli Hofstetter
Copyright (C) 2010 Richard Gomes

This source code is release under the BSD License.

This file is part of JQuantLib, a free-software/open-source library
for financial quantitative analysts and developers - http://jquantlib.org/

JQuantLib is free software: you can redistribute it and/or modify it
under the terms of the JQuantLib license.  You should have received a
copy of the license along with this program; if not, please email
. The license is also available online at
.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the license for more details.

JQuantLib is based on QuantLib. http://quantlib.org/
When applicable, the original copyright notice follows this notice.
 */

/*
 Copyright (C) 2003, 2004, 2005, 2006, 2007 Ferdinando Ametrano

 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/

 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 . The license is also available online at
 .

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
*/

package org.jquantlib.math.statistics;

import org.jquantlib.QL;
import org.jquantlib.lang.annotation.QualityAssurance;
import org.jquantlib.lang.annotation.QualityAssurance.Quality;
import org.jquantlib.lang.annotation.QualityAssurance.Version;
import org.jquantlib.math.matrixutilities.Array;
import org.jquantlib.math.matrixutilities.Matrix;

/**
 * Statistics analysis of N-dimensional (sequence) data
 * 

 * It provides 1-dimensional statistics as discrepancy plus
 * N-dimensional (sequence) statistics (e.g. mean,
 * variance, skewness, kurtosis, etc.) with one component for each
 * dimension of the sample space.
 * 
 * @author Ueli Hofstetter
 * @author Richard Gomes
 */
@QualityAssurance(quality = Quality.Q4_UNIT, reviewers = { "Richard Gomes" }, version = Version.V097)
public class GenericSequenceStatistics {

	private static final String UNSUFFICIENT_SAMPLE_WEIGHT = "sampleWeight=0, unsufficient";
	private static final String UNSUFFICIENT_SAMPLE_NUMBER = "sample number <=1, unsufficient";
	private static final String NULL_DIMENSION			 = "sample error: null dimension";
	private static final String SAMPLE_SIZE_MISMATCH	   = "sample size mismatch";

	protected /*@Size*/ int dimension_;
	protected Statistics[] stats;
	protected Matrix quadraticSum;
	private /*@Real*/ double[] results;
	
	
	public GenericSequenceStatistics() {
		this(0);
	}

	public GenericSequenceStatistics(final int dimension) {
		this.dimension_ = 0;
		reset(dimension);
	}


	//
	// public methods
	//

	public /*@Size*/ int size() /*@ReadOnly*/ {
		return dimension_;
	}

	//---- covariance and correlation

	/**
	 * returns the covariance Matrix
	 */
	public Matrix covariance() /*@ReadOnly*/ {
		final /*@Real*/ double sampleWeight = weightSum();
		QL.require(sampleWeight > 0.0, UNSUFFICIENT_SAMPLE_WEIGHT);

		final /*@Real*/ double sampleNumber = samples();
		QL.require(sampleNumber > 1.0, UNSUFFICIENT_SAMPLE_NUMBER);

		final Array m = mean();
		final /*@Real*/ double inv = 1.0/sampleWeight;

		final Matrix result = quadraticSum.mul(inv);
		result.subAssign(m.outerProduct(m));

		result.mulAssign( sampleNumber/(sampleNumber-1.0) );
		return result;
	}

	/**
	 * returns the correlation Matrix
	 */
	public Matrix correlation() /*@ReadOnly*/ {
		final Matrix corr = covariance();
		final Array v = corr.diagonal();
		for (/*@Size*/ int i=0; i 0) {
			if (dimension == dimension_) {
				for (/* @Size */int i = 0; i < dimension_; ++i)
					stats[i].reset();
			} else {
				this.dimension_ = dimension;
				stats = new Statistics[dimension];
				for (int i=0; i 0, NULL_DIMENSION);
			reset(/* @Size */dimension);
		}
		QL.require(datum.length == dimension_, SAMPLE_SIZE_MISMATCH);
		final Array array = new Array(datum);
		quadraticSum.addAssign(array.outerProduct(array).mulAssign(weight));
		for (/* @Size */int i = 0; i < dimension_; i++) {
			stats[i].add(datum[i], weight);
		}
	}

    /**
     * adds a sequence of data to the set, with default weight
     */
	public void add(final Array datum) {
		add(datum, 1.0);
	}

    /**
     * adds a sequence of data to the set, each with its weight
     */
	public void add(final Array datum, final/* @Real */double weight) {
		if (dimension_ == 0) {
			// stat wasn't initialized yet
			final /*@Integer*/ int dimension = datum.size();
			QL.require(dimension > 0, NULL_DIMENSION);
			reset(/* @Size */dimension);
		}
		QL.require(datum.size() == dimension_, SAMPLE_SIZE_MISMATCH);
		quadraticSum.addAssign(datum.outerProduct(datum).mulAssign(weight));
		for (/* @Size */int i = 0; i < dimension_; i++) {
			stats[i].add(datum.$[datum._(i)], weight);
		}
	}

}