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.

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

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: