//
// ErrorEstimate.java
//

/*
VisAD system for interactive analysis and visualization of numerical
data.  Copyright (C) 1996 - 2017 Bill Hibbard, Curtis Rueden, Tom
Rink, Dave Glowacki, Steve Emmerson, Tom Whittaker, Don Murray, and
Tommy Jasmin.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library 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 GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA
*/

package visad;

/**
   ErrorEstimate is the immutable VisAD class for statistics about a value
   or array of values.

*/
public class ErrorEstimate extends Object implements java.io.Serializable, Comparable {

  final double Error;
  final double Mean;
  final long NumberNotMissing;
  final Unit unit;

  /** these are bounds used in estimates of derivatives;
      they should be reciprocals;
      they are not applied in all cases, or uniformly */
  private static final double DERIVATIVE_LOW_LIMIT = 0.01;
  private static final double DERIVATIVE_HI_LIMIT = 1.0 / DERIVATIVE_LOW_LIMIT;

  /** construct an error distribution of number values with
      given mean and error (variance), in Unit unit
      

Note that the mean and error
      parameters are reversed in this method
  */
  public ErrorEstimate(double error, double mean, long number, Unit u) {
    unit = u;
    if (Double.isNaN(error) || Double.isNaN(mean) || number <= 0) {
      Error = Double.NaN;
      Mean = Double.NaN;
      NumberNotMissing = 0;
    }
    else {
      Error = error;
      Mean = mean;
      NumberNotMissing = number;
    }
  }

  /** construct an error distribution of 1 value with
      given mean and error (variance), in Unit unit */
  public ErrorEstimate(double mean, double error, Unit u) {
    unit = u;
    if (Double.isNaN(mean)) {
      NumberNotMissing = 0;
      Mean = Double.NaN;
      Error = Double.NaN;
    }
    else {
      NumberNotMissing = 1;
      Mean = mean;
      Error = error;
    }
  }

  /** construct an ErrorEstimate from a Field ErrorEstimate, a sample
      ErrorEstimate, the sample value, and an increment for NumberNotMissing;
      used by FlatField.setSample */
  public ErrorEstimate(ErrorEstimate field_error, ErrorEstimate sample_error,
                       double val, int inc) throws VisADException {
    double ef;
    double mf;
    long nf;
    Unit uf;
    if (field_error == null) {
      ef = Double.NaN;
      mf = Double.NaN;
      nf = 0;
      uf = null;
    }
    else {
      ef = field_error.Error;
      mf = field_error.Mean;
      nf = field_error.NumberNotMissing;
      uf = field_error.unit;
    }

    double es;
    double ms;
    long ns = Double.isNaN(val) ? 0 : 1;
    Unit us;
    if (sample_error == null) {
      us = null;
      es = Double.NaN;
      ms = Double.NaN;
    }
    else {
      us = sample_error.unit;
      if (uf == null || uf == us) {
        es = sample_error.Error;
        ms = val;
      }
      else {
        es = uf.toThis(sample_error.Error, us);
        ms = uf.toThis(val, us);
      }
    }

    unit = (field_error != null) ? uf : us;
    long number = nf + inc;
    if (number > 0) {
      double mean = 0.0;
      double error = 0.0;
      if (!Double.isNaN(ef)) error += (number - ns) * ef;
      if (!Double.isNaN(mf)) mean += (number - ns) * mf;

      if (!Double.isNaN(es)) error += ns * es;
      if (!Double.isNaN(ms)) mean += ns * ms;
      NumberNotMissing = number;
//if(NumberNotMissing==1800)Thread.dumpStack();
      Error = error / NumberNotMissing;
      Mean = mean / NumberNotMissing;
    }
    else {
      NumberNotMissing = 0;
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct an ErrorEstimate for a value that is the result of a
      binary operator; a and b are the ErrorEstimate-s for the operands */
  public ErrorEstimate(double value, Unit u, int op, ErrorEstimate a,
                       ErrorEstimate b, int error_mode)
         throws VisADException {
    unit = u;
    if (Double.isNaN(value)) {
      NumberNotMissing = 0;
      Mean = Double.NaN;
      Error = Double.NaN;
    }
    else {
      NumberNotMissing = 1;
      Mean = value;
      Error = binary(op, a, b, error_mode);
    }
  }

  /** construct an ErrorEstimate for a value that is the result of a
      unary operator; a is the ErrorEstimate for the operand */
  public ErrorEstimate(double value, Unit u, int op, ErrorEstimate a,
                       int error_mode) throws VisADException {
    unit = u;
    if (Double.isNaN(value)) {
      NumberNotMissing = 0;
      Mean = Double.NaN;
      Error = Double.NaN;
    }
    else {
      NumberNotMissing = 1;
      Mean = value;
      Error = unary(op, a, error_mode);
    }
  }

  /** construct an ErrorEstimate for an array of values with an error */
  public ErrorEstimate(double[] value, double error, Unit u) {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = error;
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct an ErrorEstimate for an array of values with an error */
  public ErrorEstimate(float[] value, double error, Unit u) {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = error;
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct Error for an array of values that is the result of a binary
      operator; a and b are the ErrorEstimate-s for the operands */
  public ErrorEstimate(double[] value, Unit u, int op, ErrorEstimate a,
                       ErrorEstimate b, int error_mode)
         throws VisADException {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = binary(op, a, b, error_mode);
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct Error for an array of values that is the result of a binary
      operator; a and b are the ErrorEstimate-s for the operands */
  public ErrorEstimate(float[] value, Unit u, int op, ErrorEstimate a,
                       ErrorEstimate b, int error_mode)
         throws VisADException {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = binary(op, a, b, error_mode);
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct Error for an array of values that is the result of a unary
      operator; a is the ErrorEstimate for the operand */
  public ErrorEstimate(double[] value, Unit u, int op, ErrorEstimate a,
                       int error_mode) throws VisADException {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = unary(op, a, error_mode);
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** construct Error for an array of values that is the result of a unary
      operator; a is the ErrorEstimate for the operand */
  public ErrorEstimate(float[] value, Unit u, int op, ErrorEstimate a,
                       int error_mode) throws VisADException {
    unit = u;
    int number = 0;
    double sum = 0.0;
    for (int i=0; i 0) {
      Mean = sum / NumberNotMissing;
      Error = unary(op, a, error_mode);
    }
    else {
      Mean = Double.NaN;
      Error = Double.NaN;
    }
  }

  /** copy a ErrorEstimate[] array; this is a helper for Set,
      FlatField, etc */
  public static ErrorEstimate[] copyErrorsArray(ErrorEstimate[] errors) {
    if (errors == null) return null;
    int n = errors.length;
    ErrorEstimate[] ret_errors = new ErrorEstimate[n];
    for (int i=0; inull
   *				.
   * @return                    A negative integer, zero, or a positive integer
   *                            depending on whether this ErrorEstimate is
   *                            considered less than, equal to, or greater than
   *                            the other ErrorEstimate, respectively.  If
   *                            obj == null, then a positive value
   *                            is returned.  An ErrorEstimate with no unit is
   *                            considered less than an ErrorEstimate with a
   *                            unit.
   */
  public int compareTo(Object obj) {
    int		comp;
    if (obj == null) {
      comp = 1;		// null ErrorEstimate considered smallest
    }
    else {
      ErrorEstimate	that = (ErrorEstimate)obj;
      if (unit == null)
      {
	if (that.unit == null) {
	  comp = new Double(Error).compareTo(new Double(that.Error));
	}
	else {
	  comp = -1;	// no-unit ErrorEstimate considered smaller than
			// one with unit
	}
      }
      else {
	if (that.unit == null) {
	  comp = 1;	// no-unit ErrorEstimate considered smaller than
			// one with unit
	}
	else {
	  try {
	    comp = new Double(Error).compareTo(
	      new Double(unit.toThis(that.Error, that.unit)));
	  }
	  catch (UnitException e) {
	    comp = +1;	// put problem ErrorEstimate-s at the end
	  }
	}
      }
    }
    return comp;
  }

}