001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 package org.apache.commons.math.optimization.fitting; 019 020 import java.util.ArrayList; 021 import java.util.List; 022 023 import org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction; 024 import org.apache.commons.math.analysis.MultivariateMatrixFunction; 025 import org.apache.commons.math.FunctionEvaluationException; 026 import org.apache.commons.math.optimization.DifferentiableMultivariateVectorialOptimizer; 027 import org.apache.commons.math.optimization.OptimizationException; 028 import org.apache.commons.math.optimization.VectorialPointValuePair; 029 030 /** Fitter for parametric univariate real functions y = f(x). 031 * <p>When a univariate real function y = f(x) does depend on some 032 * unknown parameters p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>, 033 * this class can be used to find these parameters. It does this 034 * by <em>fitting</em> the curve so it remains very close to a set of 035 * observed points (x<sub>0</sub>, y<sub>0</sub>), (x<sub>1</sub>, 036 * y<sub>1</sub>) ... (x<sub>k-1</sub>, y<sub>k-1</sub>). This fitting 037 * is done by finding the parameters values that minimizes the objective 038 * function ∑(y<sub>i</sub>-f(x<sub>i</sub>))<sup>2</sup>. This is 039 * really a least squares problem.</p> 040 * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $ 041 * @since 2.0 042 */ 043 public class CurveFitter { 044 045 /** Optimizer to use for the fitting. */ 046 private final DifferentiableMultivariateVectorialOptimizer optimizer; 047 048 /** Observed points. */ 049 private final List<WeightedObservedPoint> observations; 050 051 /** Simple constructor. 052 * @param optimizer optimizer to use for the fitting 053 */ 054 public CurveFitter(final DifferentiableMultivariateVectorialOptimizer optimizer) { 055 this.optimizer = optimizer; 056 observations = new ArrayList<WeightedObservedPoint>(); 057 } 058 059 /** Add an observed (x,y) point to the sample with unit weight. 060 * <p>Calling this method is equivalent to call 061 * <code>addObservedPoint(1.0, x, y)</code>.</p> 062 * @param x abscissa of the point 063 * @param y observed value of the point at x, after fitting we should 064 * have f(x) as close as possible to this value 065 * @see #addObservedPoint(double, double, double) 066 * @see #addObservedPoint(WeightedObservedPoint) 067 * @see #getObservations() 068 */ 069 public void addObservedPoint(double x, double y) { 070 addObservedPoint(1.0, x, y); 071 } 072 073 /** Add an observed weighted (x,y) point to the sample. 074 * @param weight weight of the observed point in the fit 075 * @param x abscissa of the point 076 * @param y observed value of the point at x, after fitting we should 077 * have f(x) as close as possible to this value 078 * @see #addObservedPoint(double, double) 079 * @see #addObservedPoint(WeightedObservedPoint) 080 * @see #getObservations() 081 */ 082 public void addObservedPoint(double weight, double x, double y) { 083 observations.add(new WeightedObservedPoint(weight, x, y)); 084 } 085 086 /** Add an observed weighted (x,y) point to the sample. 087 * @param observed observed point to add 088 * @see #addObservedPoint(double, double) 089 * @see #addObservedPoint(double, double, double) 090 * @see #getObservations() 091 */ 092 public void addObservedPoint(WeightedObservedPoint observed) { 093 observations.add(observed); 094 } 095 096 /** Get the observed points. 097 * @return observed points 098 * @see #addObservedPoint(double, double) 099 * @see #addObservedPoint(double, double, double) 100 * @see #addObservedPoint(WeightedObservedPoint) 101 */ 102 public WeightedObservedPoint[] getObservations() { 103 return observations.toArray(new WeightedObservedPoint[observations.size()]); 104 } 105 106 /** 107 * Remove all observations. 108 */ 109 public void clearObservations() { 110 observations.clear(); 111 } 112 113 /** Fit a curve. 114 * <p>This method compute the coefficients of the curve that best 115 * fit the sample of observed points previously given through calls 116 * to the {@link #addObservedPoint(WeightedObservedPoint) 117 * addObservedPoint} method.</p> 118 * @param f parametric function to fit 119 * @param initialGuess first guess of the function parameters 120 * @return fitted parameters 121 * @exception FunctionEvaluationException if the objective function throws one during the search 122 * @exception OptimizationException if the algorithm failed to converge 123 * @exception IllegalArgumentException if the start point dimension is wrong 124 */ 125 public double[] fit(final ParametricRealFunction f, 126 final double[] initialGuess) 127 throws FunctionEvaluationException, OptimizationException, IllegalArgumentException { 128 129 // prepare least squares problem 130 double[] target = new double[observations.size()]; 131 double[] weights = new double[observations.size()]; 132 int i = 0; 133 for (WeightedObservedPoint point : observations) { 134 target[i] = point.getY(); 135 weights[i] = point.getWeight(); 136 ++i; 137 } 138 139 // perform the fit 140 VectorialPointValuePair optimum = 141 optimizer.optimize(new TheoreticalValuesFunction(f), target, weights, initialGuess); 142 143 // extract the coefficients 144 return optimum.getPointRef(); 145 146 } 147 148 /** Vectorial function computing function theoretical values. */ 149 private class TheoreticalValuesFunction 150 implements DifferentiableMultivariateVectorialFunction { 151 152 /** Function to fit. */ 153 private final ParametricRealFunction f; 154 155 /** Simple constructor. 156 * @param f function to fit. 157 */ 158 public TheoreticalValuesFunction(final ParametricRealFunction f) { 159 this.f = f; 160 } 161 162 /** {@inheritDoc} */ 163 public MultivariateMatrixFunction jacobian() { 164 return new MultivariateMatrixFunction() { 165 public double[][] value(double[] point) 166 throws FunctionEvaluationException, IllegalArgumentException { 167 168 final double[][] jacobian = new double[observations.size()][]; 169 170 int i = 0; 171 for (WeightedObservedPoint observed : observations) { 172 jacobian[i++] = f.gradient(observed.getX(), point); 173 } 174 175 return jacobian; 176 177 } 178 }; 179 } 180 181 /** {@inheritDoc} */ 182 public double[] value(double[] point) throws FunctionEvaluationException, IllegalArgumentException { 183 184 // compute the residuals 185 final double[] values = new double[observations.size()]; 186 int i = 0; 187 for (WeightedObservedPoint observed : observations) { 188 values[i++] = f.value(observed.getX(), point); 189 } 190 191 return values; 192 193 } 194 195 } 196 197 }