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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef com_sun_star_chart2_XRegressionCurveCalculator_idl
  20 #define com_sun_star_chart2_XRegressionCurveCalculator_idl
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/util/XNumberFormatsSupplier.idl>
  24 #include <com/sun/star/lang/IllegalArgumentException.idl>
  25 #include <com/sun/star/geometry/RealPoint2D.idl>
  26 #include <com/sun/star/chart2/XScaling.idl>
  27
  28 module com
  29 {
  30 module sun
  31 {
  32 module star
  33 {
  34 module chart2
  35 {
  36
  37 interface XRegressionCurveCalculator : com::sun::star::uno::XInterface
  38 {
  39     /** set calculation properties for curve calculation.
  40
  41         @param degree
  42             Degree of polynomial regression curve, value should be greater than zero
  43             If the curve is not polynomial, this property has no effect.
  44
  45         @param period
  46             Period of a moving average regression curve, value should greater or equal to 2
  47             If the curve is not moving average regression curve, this property has no effect.
  48
  49         @param forceIntercept
  50             Should force the intercept value.
  51
  52         @param interceptValue
  53             Intercept value.
  54
  55     */
  56     void setRegressionProperties( [in] long degree,
  57                                   [in] boolean forceIntercept,
  58                                   [in] double interceptValue,
  59                                   [in] long period);
  60
  61     /** recalculates the parameters of the internal regression curve according to
  62         the <i>x</i>- and <i>y</i>-values given.
  63
  64         @param aXValues
  65             All x-values that represent the measurement points on
  66             which the regression is based
  67
  68         @param aYValues
  69             All y-values that represent the measurement points on
  70             which the regression is based
  71     */
  72     void recalculateRegression( [in] sequence< double > aXValues,
  73                                 [in] sequence< double > aYValues);
  74
  75
  76     /** calculates the value of the regression curve for <i>x</i>.
  77
  78         @param x
  79             The abscissa value for which the value of the regression
  80             curve should be calculated.  All numbers that are part of
  81             the domain of the regression function are valid.
  82
  83         @return
  84             If <i>x</i> is element of the domain of the regression
  85             curve function, the result is its value.
  86
  87         @throws com::sun::star::lang::IllegalArgumentException
  88             If <i>x</i> is not part of the domain of the regression
  89             function.
  90      */
  91     double getCurveValue( [in] double x )
  92         raises( com::sun::star::lang::IllegalArgumentException );
  93
  94     /** calculate multiple points of a regression curve at once. Note
  95         that this method may optimize the output by returning less
  96         points, e.g. for a line you may get only two resulting points
  97         instead of nPointCount() points.  This is only
  98         allowed if the parameter
  99         bMaySkipPointsInCalculation() is set to
 100         `TRUE`.
 101
 102         <p>It is important that a renderer takes the scalings into
 103         account. When one of these parameters is unknown, no
 104         optimization must be done.</p>
 105
 106         @param min the abscissa value for the starting point.
 107         @param max the abscissa value for the ending point.
 108
 109         @param nPointCount the number of points to calculate.
 110
 111         @param bMaySkipPointsInCalculation determines whether it is
 112                allowed to skip points in the calculation. When this
 113                parameter is `TRUE` it is assumed that the underlying
 114                coordinate system is Cartesian.
 115
 116         @param xScalingX a scaling that is used for the values in
 117                x-direction
 118
 119         @param xScalingY a scaling that is used for the values in
 120                y-direction
 121      */
 122     sequence< com::sun::star::geometry::RealPoint2D > getCurveValues(
 123         [in] double min,
 124         [in] double max,
 125         [in] long nPointCount,
 126         [in] XScaling xScalingX,
 127         [in] XScaling xScalingY,
 128         [in] boolean bMaySkipPointsInCalculation )
 129         raises( com::sun::star::lang::IllegalArgumentException );
 130
 131     /** Returns the value of the correlation coefficient for the given
 132         regression.  This value is often denoted as <i>r</i> or
 133         <i>R</i>.
 134
 135         <p>The value of <i>r</i> is signed.  Often
 136         <i>r</i><sup>2</sup> is used instead of <i>r</i> to denote
 137         a regression curve's accuracy.</p>
 138
 139         @return
 140             The return value is the fraction of the variance in the
 141             data that is explained by the regression.
 142      */
 143     double getCorrelationCoefficient();
 144
 145     /** Retrieve a string showing the regression curve's function with
 146         calculated parameters.
 147
 148         @return
 149             The string returned contains the regression curve's
 150             formula in a form <pre>"f(x) = ..."</pre>, where the
 151             calculated parts are filled out.  For a linear regression
 152             you might get <pre>"f(x) = 0.341 x + 1.45"</pre>.
 153      */
 154     string getRepresentation();
 155
 156     /** Returns a representation using the given number format for formatting all numbers
 157         contained in the formula. Wrap equation to fit in nFormulaLength characters
 158
 159         @see getRepresentation
 160      */
 161     string getFormattedRepresentation( [in] com::sun::star::util::XNumberFormatsSupplier xNumFmtSupplier,
 162                                        [in] long nNumberFormatKey,
 163                                        [in] long nFormulaLength );
 164
 165 };
 166
 167 } ; // chart2
 168 } ; // com
 169 } ; // sun
 170 } ; // star
 171
 172 #endif
 173
 174 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */