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
37module com
38{
39module sun
40{
41module star
42{
43module chart2
44{
45
46interface 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
153