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

regline_weight

Calculates the linear regression coefficient between two series where one variable is weighted by some measure of uncertainty.

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 (i.e. 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