adjustPolarAngles

A function to robustly shift sets of non-uniform angular values for better downstream statistical analyses, such as angular mean.

USAGE:

a = adjustPolarAngles(angles);

DESCRIPTION:

adjustPolarAngles attempts to (re)organize a set of radian angles originally in the range (-pi, pi] into a "continuous" distribution for robust statistical compatibility and data visualization. This is because -pi is equivalent to pi in polar coordinates but produces inconsistent results depending on the frame of reference.

This function was primarily designed to work on multiple, large datasets with non-uniform distributions and is a more generalized version of existing functions such as meanangle, which only calculates angular mean. The output of adjustPolarAngles is directly compatible with standard functions such as mean, median, and std, enabling more downstream analyses than just angular mean.

INPUTS:

• angles: A numerical vector within the range (-pi, pi]. All input data should be pre-adjusted to the equivalent angular values within this range and be in RADIANS.

OUTPUTS:

• a: A numerical vector with the same size as angles, but certain entries may be shifted by 2*pi. Entry indices are not changed between angles and a, i.e. angles(ind) and a(ind) are polar equivalents, but not necessary numerically equivalent, such as -pi/4 may be expressed as 7*pi/4.

EXAMPLE:

% make up some "discontinuous" data points due to wrap around at -pi / pi and fix them
n = 200;
data = normrnd(pi + pi/16, pi/4, [n, 1]);
data(data > pi) = data(data > pi) - 2*pi;
a = adjustPolarAngles(data);

% visually validate results
figure, hold on
cmap = parula(8);  % use some pretty colors
[x, y] = pol2cart(data, unifrnd(0.9, 1.1, [n, 1])); % plot original angles, jitter radii
scatter(x, y, 8, 'marker', 'o', 'markeredgecolor', 'none', 'markerfacecolor', cmap(3, :));
[x, y] = pol2cart(mean(data), 1); % plot original angular mean
scatter(x, y, 12, 'marker', 'o', 'markeredgecolor', 'none', 'markerfacecolor', cmap(5, :));
text(x, y, ' \leftarrow original angular mean', 'horizontalalignment', 'left')
[x, y] = pol2cart(mean(a), 1); % show more accurate angular mean
scatter(x, y, 12, 'marker', 'o', 'markeredgecolor', 'none', 'markerfacecolor', cmap(6, :));
text(x, y, 'accurate angular mean \rightarrow ', 'horizontalalignment', 'right')
xlim([-2, 2]), ylim([-2, 2]), axis equal