NCL Website header
NCL Home > Documentation > Functions > General applied math, Statistics

regline_weight

Calculates the linear regression coefficient between two series where the dependent (y) variable's values are weighted by some measure of uncertainty (typically, standard deviations) such that the Chi-square goodness-of-fit is minimized.

Available in version 6.5.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"  ; This library is automatically loaded
                                                             ; from NCL V6.2.0 onward.
                                                             ; No need for user to explicitly load.

	function regline_weight (
		x   [*] : numeric,  
		y   [*] : numeric,  
		yu      : numeric,  
		opt [1] : integer   
	)

	return_val [1] :  float or double

Arguments

x
y

One-dimensional arrays of the same length. Missing values should be indicated by x@_FillValue and y@_FillValue. If x@_FillValue or y@_FillValue are not set, then the NCL default (appropriate to the type of x and y) will be assumed.

yu

Estimates of the uncertainties (errors) of each y(i). Commonly, theyu are the standard deviations. Internally, the yu are converted to weights such that the sum of the weight variances is one: SUM[1/yu^2]=1.

opt

Integer flag:

  • opt=0: do not use the yu values. Internally, all weighting is set to one. This will return the same regression coefficient and y-intercept as regline.
  • opt=1: use the yu values and weight uncertainty values such that: SUM[1/yu^2]=1.

    Return value

    The return value is a scalar of type double if x, y or yu are double, and float otherwise. Some attributes are returned as well. See the description below.

    Description

    <regline_weight computes the information needed to construct a regression line where each value of y may have an uncertainty/error estimate. Most commonly, this is the standard deviation. Internally, the yu are converted to weights such that the variance of the weights is [1/yu^2]

    regline_weight also returns the following attributes:

    std_rc (scalar, float or double, depending on x and y)
    standard error of the regression coefficient
    std_yi (scalar, float or double, depending on x and y)
    standard error of the y-intercept
    resid (float or double)
    residuals from fitted regression line
    chi2 (float or double)
    Chi-square goodness of fit.
    nptxy (scalar, integer)
    number of points used

    This function is a translation of the following Fortran-77 code:

       Author:  Donald G. Luttermoser, ETSU/Physics, 2 October 2013.
       History: Based on the FIT subroutine of Numerical Recipes for FORTRAN 77
       fit.txt
    

    See Also

    regline, regline_stats, regCoef, regCoef_n, reg_multlin_stats, equiv_sample_size, rtest

    Examples

    Example 1 The following example is based upon data from:

        Brownlee
        Statistical Theory and Methodology
        J Wiley 1965   pgs: 342-346     QA276  .B77
    
    This is the same data as Example 1 for regline except bogus measurement standard deviation (ie: uncertainties/errors) have been created for illustration. As noted in the above documentation, internally, the yu are converted to weights=[1/yu^2] where the variance of the weights is one.
          x    = (/ 1190.,1455.,1550.,1730.,1745.,1770. \
                 ,  1900.,1920.,1960.,2295.,2335.,2490. \
                 ,  2720.,2710.,2530.,2900.,2760.,3010. /)
          
          y    = (/ 1115.,1425.,1515.,1795.,1715.,1710. \
                 ,  1830.,1920.,1970.,2300.,2280.,2520. \
                 ,  2630.,2740.,2390.,2800.,2630.,2970. /)
          nxy  = dimsizes(y)  
    
        ; create *bogus* uncertainties
    
          YSTD = stddev(y)
          yu   = random_uniform(-0.2*YSTD, 0.3*YSTD, nxy)    ; yu[*]
                 
          rcw  = regline_weight(x,y,yu,1) ; opt=1
          print(rcw)
    
    The output yields:
    
          Variable: RC_ER
          Type: float
          Total Size: 4 bytes
                      1 values
          Number of Dimensions: 1
          Dimensions and sizes:	[1]
          Coordinates: 
          Number Of Attributes: 7
            yintercept :	-69.74747
            residuals :	
            std_yi :	24.64047       ; standard error of y-intercept
            std_rc :	0.0119971      ; standard error of the regression coefficient
            chi2 :	        0.8846564      ; goodness-of-fit statistic
            p_value :	2.455325e-08   ; statistical p-value
            nxy :	18
          
          (0)	1.026713        ; compare with Example 1 for regline