quantize.m

%-----------------------------------------------------------------------------
%
% Copyright (C) 2016
% ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>
% P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%-----------------------------------------------------------------------------
% Author: E. Kooistra, 2016
%
% quantize - quantize signed input data
%     The output has nof_bits.
%     Internally in_max maps to 2^(nof_bits-1)-1.
%     The direction determines how -0.5 is rounded:
%     . 'half_away': Round half away from zero, so +0.5 --> 1, -0.5 --> -1.
%     . 'half_up'  : Round half up to +infinity, so +0.5 --> 1, -0.5 --> 0.
%     Quantized data that is out of range -s_min : s_max gets treated 
%     dependent on overflow:
%     . 'clip' : Clip to -s_min or s_max
%     . 'wrap' : Wrap within nof_bits signed integer range
%     The output data range is scaled back to the original in_max.

function out_data = quantize(in_data, in_max, nof_bits, direction, overflow)

if ~exist('direction', 'var'); direction = 'half_away'; end;
if ~exist('overflow', 'var'); overflow = 'clip'; end;
    
q_bit = 1;
q_max =  2^(nof_bits-1)-1;
q_min = -2^(nof_bits-1);
q_period = 2^nof_bits;

% Map maximum input data value to positive maximum of nof_bits value
q_data = in_data * q_max/in_max;

% Quantize
if strcmp(direction, 'half_away')
    q_data = round(q_data);
else
    q_data = floor(q_data + q_bit/2);
end

if strcmp(overflow, 'clip')
    q_data(q_data>q_max) = q_max;
    q_data(q_data<q_min) = q_min;
else
    q_data = mod(q_data - q_min, q_period) + q_min;  % = nof_bits signed integer wrap
end
    
% Back to original full scale
out_data = q_data * in_max/q_max;