function [xn,dyn_range] = normalize(x,dyn_range,columns)
% function [xn,dyn_range] = normalize(x,dyn_range,columns)
%
% normalizes any input from 0 to 1. Works on first dimension {default}, or
% normalizes entire array if third input is false.
%
% optional input changes the dynamic range.  Default is min(x):max(x).
% Setting dyn_range > data causes the data < 1
% Setting dyn_range < data zeros low values
% This is analogous to how an instrument performs.  Best way to understand
% is by plotting different output for various dynamic ranges.

% When DR is reduced, data will always span [0,1]
% When DR is increased, it is optional/relative whether it spans the upper
% or lower section of (0,1).  I've chosen to go with upper (#,1], since
% this is more useful for my dB radar values.

assert(isreal(x),'this function does horrible things to complex data')

dim = size(x);

if nargin < 3 || columns % normalize column-wise
    x = reshape(x,[dim(1) prod(dim(2:end))]);
else % normalize entire array
    x = x(:);
end

x(isinf(x)) = nan; % can't handle nans in these calculations.

xmin = nanmin(x);
xmax = nanmax(x);
xdr = xmax-xmin; % data dynamic range

if nargin < 2 || isempty(dyn_range)
    dyn_range = xdr; % default
end 

dyn_range = abs(dyn_range); 

% expand values if necessary
xmax = expand(xmax,dim(1));
dyn_range = expand(dyn_range,dim(1));

% the zero point determines how increased DR behaves:
zero = xmax - dyn_range;
 
% normalize
x = x - zero;
x(x<0) = 0; % only occurs for reduced dynamic range
xn = x ./ dyn_range;

xn = reshape(xn,dim);

function x = expand(x,N)
% check for scalar value:
chk = unique(x); 
if length(chk) ==1
    x = chk;
else
    x = repmat(x,N,1);
end