wmean documentation
The wmean function computes the weighted average or weighted mean value.
Back to Climate Data Tools Contents
Contents
Syntax
M = wmean(A,weights) M = wmean(...,'all') M = wmean(...,'dim',dim) M = wmean(...,'nanflag')
Description
M = wmean(A,weights) returns the weighted mean of the elements of A along the first array dimension whose size does not equal 1. Dimensions of A must match the dimensions of weights.
- If A is a vector, then wmean(A,weights) returns the weighted mean of the elements.
- If A is a matrix, then wmean(A,weights) returns a row vector containing the weighted mean of each column.
- If A is a multidimensional array, then wmean(A,weights) operates along the first array dimension whose size does not equal 1, treating the elements as vectors. This dimension becomes 1 while the sizes of all other dimensions remain the same.
M = wmean(...,'all') computes the weighted mean over all elements. (Requires Matlab R2018b or later.)
M = wmean(...,'dim',dim) returns the mean along dimension dim. For example, if A is a matrix, then wmean(A,weights,'dim',2) is a column vector containing the weighted mean of each row.
M = wmean(...,'nanflag') specifies whether to include or omit NaN values from the calculation for any of the previous syntaxes. wmean(A,weights,'includenan') includes all NaN values in the calculation while wmean(A,weights,'omitnan') ignores them.
Example 1: 1D array
Here's an array of values y and their mean without any special weighting:
y = 0:2:10 mean(y)
y =
Columns 1 through 5
0 2.00 4.00 6.00 8.00
Column 6
10.00
ans =
5.00
The answer above is equivalent to using wmean with equal weights for each value in y:
weight = [1 1 1 1 1 1]; wmean(y,weight)
ans =
5.00
But perhaps you're doing a calculation in which the values close to zero are to be weighted most heavily, like this:
weight = logspace(1,0,6) wmean(y,weight)
weight =
Columns 1 through 5
10.00 6.31 3.98 2.51 1.58
Column 6
1.00
ans =
2.61
Example 2: 2D matrix
Here's a 2D matrix A, and just like in Example 1 we'll start by using equal weights across the board:
% A data matrix: A = [0 1 2 2 3 4 4 5 6 6 7 8] % Equal weights everywhere: w = ones(size(A)) wmean(A,w)
A =
0 1.00 2.00
2.00 3.00 4.00
4.00 5.00 6.00
6.00 7.00 8.00
w =
1.00 1.00 1.00
1.00 1.00 1.00
1.00 1.00 1.00
1.00 1.00 1.00
ans =
3.00 4.00 5.00
If you need to operate across rows instead of down the columns of A, specify dimension 2 as follows:
wmean(A,w,'dim',2)
ans =
1.00
3.00
5.00
7.00
If you're following along at home, you can prove to yourself that the answer above, in which all weights are equal, gives the same answer as mean(A,2).
Question: How could we make the weighted mean of A turn out to be equal to the second row of A?
Answer: I can think of two ways. One way is to set all the weights to zero, except row 2. Alternatively, we could keep those rows the way they are, and instead set the second row of weights to some insanely large number:
w(2,:) = 1e100 wmean(A,w)
w =
1.00 1.00 1.00
10000000000000000159028911097599180468360808563945281389781327557747838772170381060813469985856815104.00 10000000000000000159028911097599180468360808563945281389781327557747838772170381060813469985856815104.00 10000000000000000159028911097599180468360808563945281389781327557747838772170381060813469985856815104.00
1.00 1.00 1.00
1.00 1.00 1.00
ans =
2.00 3.00 4.00
What if one element in A is NaN?
A(2,2) = NaN wmean(A,w)
A =
0 1.00 2.00
2.00 NaN 4.00
4.00 5.00 6.00
6.00 7.00 8.00
ans =
2.00 NaN 4.00
We can ignore that missing entry instead of turning the whole solution for that column to NaN:
wmean(A,w,'omitnan')
ans =
2.00 4.33 4.00
Example 3: Area-weighted SST
Here's a map of sea surface temperatures using some example data that comes with CDT:
% Load the sample data: load global_sst % Convert from Kelvin to Celsius: sst = sst-273.15; % Plot SSTs: imagescn(lon,lat,sst) cmocean thermal % colormap cb = colorbar; ylabel(cb,'sea surface temperature \circC')
A beginner might try to get the average global sea surface temperature by taking the unweighted mean of all sst values:
mean(sst,'all','omitnan')
ans =
13.84
However, we must recall that the sst grid corresponds to equally spaced latitudes and longitudes, which are not all equal in area. Lines of longitude converge at the poles, so an area-averaged measure of SST requires weighting the mean by are of each grid cell.
To accomplish this, turn the lat and lon arrays into grids and use cdtarea to get the area of each grid cell. Here are the areas of each grid cell:
% turn lat,lon arrays into grids: [Lon,Lat] = meshgrid(lon,lat); % Get the area of each grid cell: A = cdtarea(Lat,Lon,'km2'); imagescn(lon,lat,A) hold on borders % national borders cb = colorbar; ylabel(cb,'grid cell area (km^2)')
With the grid cell areas A, we can now get the area-averaged sea surface temperature with wmean:
wmean(sst,A,'all','omitnan')
ans =
18.45
That's quite a difference from the 13.8 degree value we obtained using the unweighted mean! And it's not surprising: The "unweighted" mean in this context was actually a misnomer because by giving equal weight to each grid cell in the mean SST calculation, we were actually giving undue weight to the tiny grid, cold grid cells near the poles. So it is no surprise that the "unweighted" mean SST value is lower than the area-averaged SST value.
Author Info
This function is part of the Climate Data Toolbox for Matlab. The function and supporting documentation were written by Chad A. Greene of the University of Texas at Austin.