offapi/com/sun/star/chart2/XRegressionCurveCalculator.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XRegressionCurveCalculator.idl,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef com_sun_star_chart2_XRegressionCurveCalculator_idl
  31 #define com_sun_star_chart2_XRegressionCurveCalculator_idl
  32
  33 #include <com/sun/star/uno/XInterface.idl>
  34
  35 #include <com/sun/star/util/XNumberFormatsSupplier.idl>
  36 #include <com/sun/star/lang/IllegalArgumentException.idl>
  37 #include <com/sun/star/geometry/RealPoint2D.idl>
  38 #include <com/sun/star/chart2/XScaling.idl>
  39
  40 module com
  41 {
  42 module sun
  43 {
  44 module star
  45 {
  46 module chart2
  47 {
  48
  49 interface XRegressionCurveCalculator : com::sun::star::uno::XInterface
  50 {
  51     /** recalculates the parameters of the internal regression curve according to
  52         the <it>x</it>- and <it>y</it>-values given.
  53
  54         @param aXValues
  55             All x-values that represent the measurement points on
  56             which the regression is based
  57
  58         @param aYValues
  59             All y-values that represent the measurement points on
  60             which the regression is based
  61     */
  62     void recalculateRegression( [in] sequence< double > aXValues,
  63                                 [in] sequence< double > aYValues );
  64
  65
  66     /** calculates the value of the regression curve for <it>x</it>.
  67
  68         @param x
  69             The abscissa value for which the value of the regression
  70             curve should be calculated.  All numbers that are part of
  71             the domain of the regression function are valid.
  72
  73         @return
  74             If <it>x</it> is element of the domain of the regression
  75             curve function, the result is its value.
  76
  77         @throws com::sun::star::lang::IllegalArgumentException
  78             If <it>x</it> is not part of the domain of the regression
  79             function.
  80      */
  81     double getCurveValue( [in] double x )
  82         raises( com::sun::star::lang::IllegalArgumentException );
  83
  84     /** calculate multiple points of a regression curve at once. Note
  85         that this method may optimize the output by returning less
  86         points, e.g. for a line you may get only two resulting points
  87         instead of <member>nPointCount</member> points.  This is only
  88         allowed if the parameter
  89         <member>bMaySkipPointsInCalculation</member> is set to
  90         <TRUE/>.
  91
  92         <p>It is important that a renderer takes the scalings into
  93         account. When one of these parameters is unknown, no
  94         optimization must be done.</p>
  95
  96         @param bMaySkipPointsInCalculation determines whether it is
  97                allowed to skip points in the calculation. When this
  98                parameter is <TRUE/> it is assumed that the underlying
  99                coordinate system is cartesian.
 100
 101         @param xScalingX a scaling that is used for the values in
 102                x-direction
 103
 104         @param xScalingY a scaling that is used for the values in
 105                y-direction
 106      */
 107     sequence< com::sun::star::geometry::RealPoint2D > getCurveValues(
 108         [in] double min,
 109         [in] double max,
 110         [in] long nPointCount,
 111         [in] XScaling xScalingX,
 112         [in] XScaling xScalingY,
 113         [in] boolean bMaySkipPointsInCalculation )
 114         raises( com::sun::star::lang::IllegalArgumentException );
 115
 116     /** Returns the value of the correlation coefficient for the given
 117         regression.  This value is often denoted as <it>r</it> or
 118         <it>R</it>.
 119
 120         <p>The value of <it>r</it> is signed.  Often
 121         <it>r</it><sup>2</sup> is used instead of <it>r</it> to denote
 122         a regression curve's accuray.</p>
 123
 124         @return
 125             The return value is the fraction of the variance in the
 126             data that is explained by the regression.
 127      */
 128     double getCorrelationCoefficient();
 129
 130     /** Retrieve a string showing the regression curve's function with
 131         calculated parameters.
 132
 133         @return
 134             The string returned contains the regression curve's
 135             formula in a form <pre>"f(x) = ..."</pre>, where the
 136             calculated parts are filled out.  For a linear regression
 137             you might get <pre>"f(x) = 0.341 x + 1.45"</pre>.
 138      */
 139     string getRepresentation();
 140
 141     /** Returns a representation using the given numnber format for formatting all numbers
 142         contained in the formula.
 143
 144         @see getRepresentation
 145      */
 146     string getFormattedRepresentation( [in] com::sun::star::util::XNumberFormatsSupplier xNumFmtSupplier,
 147                                        [in] long nNumberFormatKey );
 148 };
 149
 150 } ; // chart2
 151 } ; // com
 152 } ; // sun
 153 } ; // star
 154
 155 #endif