PlotLogCompand

Two functions to plot diverse y dynamic ranges into one axis with ticks on axis, and continuous compression across y=0.

When one wants to show in the same axis several curves with very different dynamic ranges
the smallest dyn range will appear as a flat 0 curve.
These 2 functions solve this issue by means of a controlled signed-log-companding of the input signed y values.

1) function [ph, A,PCL, yLin,ym3dB] = plotLogCompand(x,y, params, comp_mode, varargin)
Add plot to axis one by one, already log companded along y
2) add_Y_LogCompand_Controls( axH )
Add 2 interactive controls [+],[-] to an existing plot, to enable zooming in the smallest dynamic ranges.

% [ph, A,PCL, yLin,ym3dB] = PLOTLOGCOMPAND(x,y, params, [comp_mode], [varargin])
%
% The companding is such that the derivative is unit and continuous @ y=0
% [params,comp_mode] control the amount of distortion (see further)
% Values displayed in the y axis are the original linear data values
%
% INPUTS:
% --------
% x,y : the data to be plotted, leave x empty if you want to use indexes
% params,[comp_mode] : specifies the companding magnitude (distortion amount)
%
% 4 modes, from largest (max companding) to lowest distortion (min companding) :
% comp_mode = 'One_Half', : yMin to appear half way to ymax over all curves
% : param= [yMax,yMin] y values which we intend to plot
% comp_mode = 'One_Third', : yMin to appear 1/3 way to ymax
% : param= [yMax,yMin] y values which we intend to plot
% comp_mode = 'value_min3dB' : y value @ -3dB distortion
% : param= y value with 3dB shape distortion
% y1 > y*0.707 ; y1' > y'*0.5182 , for |y|<param ; A = param/0.93; yLin = param/2.244
% comp_mode = 'linear_region': y value @ -3dB slope distortion
% : param= y value with little distortion (-1.5dB peak, slope=-3dB)
% y1 > y*0.838 ; y1' > y'*0.707 , for |y|<param ; A = param/0.41; yLin = param
% comp_mode ='Compression_dB': y value @ -k dB value compression
% : param [yVal,KdB], where
% - yVal where we refer the compression to
% - KdB compression level
% DEFAULT comp_mode: One_Third
%
% OUTPUTS:
% -------
% A : companding function parameter
% PCL : shape distortion = peak comrpession level
% yLin : y range where companding is in linear region (-1.5 dB)
% ym3dB : y range where companding is low distortion (-3 dB)
% -------------------------------------------------------------------------------------
% EXAMPLE:
% -------
% % signal peak values
% a = 1; b = 0.1; c = 0.01;
% % Define signals
% NP = 2;
% x = 1:.1:100;
% ya = a*sin(2*pi*x/x(end)*NP);
% yb = ya/a*b;
% yc = ya/a*c;
%
% % get smallest signal to occupy 1/3 of range
% figure(); set(gca,'color',[1,1,1]); hold on; grid on;
% comp_mode = 'One_Third';
% param = [a,c];
% %make companded plots, @ last plot activate addyTicks=1
% plotLogCompand(x,ya,param,comp_mode);
% plotLogCompand(x,yb,param,comp_mode);
% plotLogCompand(x,yc,param,comp_mode);
% title(sprintf('LogCompand, comp_mode=%s',comp_mode),'interpreter','none');
% -------------------------------------------------------------------------------------
% DETAILS :
% -------
% Compression of the dynamic range is obtained via :
% Companding Function : y1 = A*(log(A+|y|)-log(A))*sign(y)
% Inverse Comp.Function : y = A*(exp(|y1|/A)-1)*sign(y1)
%
% Table of [mode, y(A), param], (val and slope) :
%
% A = internal compander scale param such that param can be in these range:
% Compression | yValue | Inequalities
% ----------------------------+--------+---------------------------------------------------
% Linear Region (slope -3dB) |0.41*A | (slope > 0.707, val > 0.83) , for |y|<param 1.5 dB peak val compress
% Val -3dB |0.93*A | (val > y*0.707, slope > 0.5182) , for |y|<param 3 dB peak val compress
% Discernible Region |9*A | (slope > 0.1, val > 0.256) , for |y|<param 12 dB peak val compress
% Barely Discernible Region |99*A | (slope > 0.01, val > 0.046) , for |y|<param 27 dB peak val compress
% This allows to cover ~48 dB of dynamic range above the linear region, and still recognize the shapes though distorted
%
% A = SlopeCompressFactor/(1-SlopeCompressFactor) * yVal Slope Compression control
% A = yVal/KdB*exp(1.48145-0.0933225*KdB^1.03646)) Value Compression control
%
% 2019/10/06, M.Ciacci