NCL Home > Documentation > Functions > Array query

# month_to_annual_weighted

Converts monthly values to annual values weighted by the number of days in a month.

## Prototype

; from NCL V6.2.0 onward.
; No need for user to explicitly load.

function month_to_annual_weighted (
yyyymm [*] : numeric,
x          : numeric,
opt    [1] : integer
)

## Arguments

yyyymm

Year-month dates [e.g., 198401,198402,...]. This must be the same size as the "time" dimension of x.

x

An array containing monthly values. The 'temporal' dimension must be the leftmost dimension if there are multiple dimensions. The size of the 'temporal' dimension must be evenly divisible by 12.

opt

option:

opt=0 returns the weighted sum
opt=1 return the weighted annual mean
opt=2 return the weighted sum divided by 12 to get monthly mean value

## Return value

Returns an array where the 'temporal' dimension is decimated by a factor of 12. Note: Upon return the 'temporal' dimension will be named year to avoid confusing dimension names.

## Description

Typical usage is that an array of monthly precipitation rate (e.g., mm/day) or monthly mean temperatures are input. For precipitation, generally opt=0, and the weighted average is returned. For temperature, generally opt=1, and the weighted annual average is returned.

The weights are the appropriate number days for a month. February of leap years uses 29 days.

This function does not check for January (mm=1) to be the first month of the yyyymm. Thus, if yyyymm(0)=198103 [say], then the 12-month year will be March 1983 to April 1984.

If the time span is not divisible by 12 then the 'extra' months are ignored. For example, if yyyymm spans 199101 to 199603, weighted annual means will be calculated for 1991 to 1995. There will be no value returned for 1996.

Caveat: This function works as expected for one-dimensional arrays. Also, it works fine when all grid points have 12 non-missing monthly values for any year. However, if any grid point does not have 12 valid values, then the annual values will be returned as missing for all grid points for that year.

## Examples

Example 1

A one-dimensional array of monthly precipitation [mm/day] is to be converted to an annual total. If prc(time), and the size of time is 240 monthly values, than 20 (=240/12) values (years) will be returned. The 'temporal' dimension will be named year.

prc_annual_total = month_to_annual_weighted(yyyymm, prc, 0)  ; prc_annual_total(20)
If the array contains, say, monthly mean temperatures (tmp), then
tmp_annual_mean = month_to_annual_weighted(yyyymm, tmp, 1)   ; tmp_annual_mean(20)
Example 2

A multi-dimensional array of monthly precipitation totals [mm/day] is to be converted to an annual total. If prc(time,lat,lon), and the size of time is 1200 monthly values, than 100 (=120/12) values (years) will be returned. The 'temporal' dimension will be named year.

PRC = month_to_annual_weighted(yyyymm, prc, 0)  ; PRC(100,nlat,mlon)
If the array contains, say, monthly mean temperatures [tmp(time,lev,lat,lon)], then
TMP = month_to_annual_weighted(yyyymm, tmp, 1)  ; TMP(100,klev,nlat,mlon)