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

/**************************************************************
 * 
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 *************************************************************/


#ifndef com_sun_star_chart2_XRegressionCurveCalculator_idl
#define com_sun_star_chart2_XRegressionCurveCalculator_idl

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/util/XNumberFormatsSupplier.idl>
#include <com/sun/star/lang/IllegalArgumentException.idl>
#include <com/sun/star/geometry/RealPoint2D.idl>
#include <com/sun/star/chart2/XScaling.idl>

module com
{
module sun
{
module star
{
module chart2
{

interface XRegressionCurveCalculator : com::sun::star::uno::XInterface
{
    /** recalculates the parameters of the internal regression curve according to
        the <it>x</it>- and <it>y</it>-values given.

        @param aXValues
            All x-values that represent the measurement points on
            which the regression is based

        @param aYValues
            All y-values that represent the measurement points on
            which the regression is based
    */
    void recalculateRegression( [in] sequence< double > aXValues,
                                [in] sequence< double > aYValues );


    /** calculates the value of the regression curve for <it>x</it>.

        @param x
            The abscissa value for which the value of the regression
            curve should be calculated.  All numbers that are part of
            the domain of the regression function are valid.

        @return
            If <it>x</it> is element of the domain of the regression
            curve function, the result is its value.

        @throws com::sun::star::lang::IllegalArgumentException
            If <it>x</it> is not part of the domain of the regression
            function.
     */
    double getCurveValue( [in] double x )
        raises( com::sun::star::lang::IllegalArgumentException );

    /** calculate multiple points of a regression curve at once. Note
        that this method may optimize the output by returning less
        points, e.g. for a line you may get only two resulting points
        instead of <member>nPointCount</member> points.  This is only
        allowed if the parameter
        <member>bMaySkipPointsInCalculation</member> is set to
        <TRUE/>.

        <p>It is important that a renderer takes the scalings into
        account. When one of these parameters is unknown, no
        optimization must be done.</p>

        @param bMaySkipPointsInCalculation determines whether it is
               allowed to skip points in the calculation. When this
               parameter is <TRUE/> it is assumed that the underlying
               coordinate system is cartesian.

        @param xScalingX a scaling that is used for the values in
               x-direction

        @param xScalingY a scaling that is used for the values in
               y-direction
     */
    sequence< com::sun::star::geometry::RealPoint2D > getCurveValues(
        [in] double min,
        [in] double max,
        [in] long nPointCount,
        [in] XScaling xScalingX,
        [in] XScaling xScalingY,
        [in] boolean bMaySkipPointsInCalculation )
        raises( com::sun::star::lang::IllegalArgumentException );

    /** Returns the value of the correlation coefficient for the given
        regression.  This value is often denoted as <it>r</it> or
        <it>R</it>.

        <p>The value of <it>r</it> is signed.  Often
        <it>r</it><sup>2</sup> is used instead of <it>r</it> to denote
        a regression curve's accuray.</p>

        @return
            The return value is the fraction of the variance in the
            data that is explained by the regression.
     */
    double getCorrelationCoefficient();

    /** Retrieve a string showing the regression curve's function with
        calculated parameters.

        @return
            The string returned contains the regression curve's
            formula in a form <pre>"f(x) = ..."</pre>, where the
            calculated parts are filled out.  For a linear regression
            you might get <pre>"f(x) = 0.341 x + 1.45"</pre>.
     */
    string getRepresentation();

    /** Returns a representation using the given numnber format for formatting all numbers
        contained in the formula.

        @see getRepresentation
     */
    string getFormattedRepresentation( [in] com::sun::star::util::XNumberFormatsSupplier xNumFmtSupplier,
                                       [in] long nNumberFormatKey );
};

} ; // chart2
} ; // com
} ; // sun
} ; // star

#endif