View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.estimation;
19  
20  /**
21   * This interface represents solvers for estimation problems.
22   *
23   * <p>The classes which are devoted to solve estimation problems
24   * should implement this interface. The problems which can be handled
25   * should implement the {@link EstimationProblem} interface which
26   * gather all the information needed by the solver.</p>
27   *
28   * <p>The interface is composed only of the {@link #estimate estimate}
29   * method.</p>
30   *
31   * @see EstimationProblem
32   *
33   * @version $Revision: 754732 $ $Date: 2009-03-15 15:30:44 -0400 (Sun, 15 Mar 2009) $
34   * @since 1.2
35   * @deprecated as of 2.0, everything in package org.apache.commons.math.estimation has
36   * been deprecated and replaced by package org.apache.commons.math.optimization.general
37   *
38   */
39  @Deprecated
40  public interface Estimator {
41  
42    /** 
43     * Solve an estimation problem.
44     *
45     * <p>The method should set the parameters of the problem to several
46     * trial values until it reaches convergence. If this method returns
47     * normally (i.e. without throwing an exception), then the best
48     * estimate of the parameters can be retrieved from the problem
49     * itself, through the {@link EstimationProblem#getAllParameters
50     * EstimationProblem.getAllParameters} method.</p>
51     *
52     * @param problem estimation problem to solve
53     * @exception EstimationException if the problem cannot be solved
54     *
55     */
56    public void estimate(EstimationProblem problem)
57      throws EstimationException;
58  
59    /** 
60     * Get the Root Mean Square value.
61     * Get the Root Mean Square value, i.e. the root of the arithmetic
62     * mean of the square of all weighted residuals. This is related to the
63     * criterion that is minimized by the estimator as follows: if
64     * <em>c</em> is the criterion, and <em>n</em> is the number of
65     * measurements, then the RMS is <em>sqrt (c/n)</em>.
66     * @see #guessParametersErrors(EstimationProblem)
67     * 
68     * @param problem estimation problem
69     * @return RMS value
70     */
71    public double getRMS(EstimationProblem problem);
72  
73    /**
74     * Get the covariance matrix of estimated parameters.
75     * @param problem estimation problem
76     * @return covariance matrix
77     * @exception EstimationException if the covariance matrix
78     * cannot be computed (singular problem)
79     */
80    public double[][] getCovariances(EstimationProblem problem)
81      throws EstimationException;
82  
83    /**
84     * Guess the errors in estimated parameters.
85     * @see #getRMS(EstimationProblem)
86     * @param problem estimation problem
87     * @return errors in estimated parameters
88       * @exception EstimationException if the error cannot be guessed
89     */
90    public double[] guessParametersErrors(EstimationProblem problem)
91      throws EstimationException;
92  
93  }