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

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