wolffd@0: function [nAxis] = addTopXAxis (varargin)
wolffd@0: 
wolffd@0: % [nAxis] = addTopXAxis (axisH, properties ...)
wolffd@0: % Add an X-axis on top (additional to the one on bottom) of the figure,
wolffd@0: % with its own ticks labels and axis label (allow double scale).
wolffd@0: % Ticks, minor ticks positions and x limits are set to be identical for top and bottom
wolffd@0: % axis. Moreover, they are linked, i.e. a modification of one of them, even after execution
wolffd@0: % of this function, will result in modification of the other one.
wolffd@0: %
wolffd@0: % Parameters:
wolffd@0: % 	axisH = handle for axes (dafault = current axes, given by |gca|)
wolffd@0: %	properties: syntax is two-folded arguments for each property,
wolffd@0: %       	    on the form: 'name of property' (case insensitive), value of property
wolffd@0: %		    and properties can be 
wolffd@0: %		xLabStr : the label for the top X-axis (string)
wolffd@0: %			default = ''
wolffd@0: %		expression or exp : expression for transforming bottom X-tick labels to
wolffd@0: %			      top X-tick labels. In the expression, |argu| will refer
wolffd@0: %				to the value of the bottom X-tick labels.
wolffd@0: %				eg. going from |log10(x)| to linear |x| values will be done with
wolffd@0: %				the string '10.^argu' for expression.
wolffd@0: %			default = ''
wolffd@0: %		Note : if expression needs to use some variables, that are not accessible to this function, they need to be evaluated
wolffd@0: %			before being passed to this function (see exemples below).
wolffd@0: %		xTickLabelFormat : display format, used for converting numerical values for tick labels in strings. (string)
wolffd@0: %				The computation of top axis tick labels using |expression| can lead to numbers taking a lot of space
wolffd@0: %				because of the precision of the display. Reducing the precision will reduce the size of the labels.
wolffd@0: %			default = '%4.1f'
wolffd@0: %
wolffd@0: %  Exemples:
wolffd@0: %
wolffd@0: %	axisH = axes % create new axes, and save the handle in axisH
wolffd@0: %       addTopXAxis(axisH, 'expression', '-argu') % change the label of the ticks by their opposite
wolffd@0: %	
wolffd@0: %
wolffd@0: %  addTopXAxis('xticklabel', '(k0.*10.^argu)', 'xlabel', '$\lambda_{up}$ (cm)')
wolffd@0: %	will use the current axis (handle is not passed to the function), and will compute the new X-tick values according to
wolffd@0: %		x' = k0.*10.^argu;
wolffd@0: %	where |k0| is a variable whose value has to be set in the 'base' workspace.
wolffd@0: 
wolffd@0: %
wolffd@0: %	V2 - 11/27/2005
wolffd@0: %	Modifs for V2:
wolffd@0: %		* - now evaluates expression in 'base' workspace.
wolffd@0: %		Therefore, variables (like 'k0' in the second example) do not need to be evaluated anymore before being passed, 
wolffd@0: %		as long as they already exist in 'base' workspace. It should allow more complex expressions to be passed than previously.
wolffd@0: %		Example 2 then becomes
wolffd@0: %			addTopXAxis('expression', '(k0.*10.^argu)', 'xLabStr', '$\lambda_{up}$ (cm)')
wolffd@0: %		instead of
wolffd@0: %			addTopXAxis('expression', ['(', num2str(k0),'.*10.^argu)'], 'xLabStr', '$\lambda_{up}$ (cm)'
wolffd@0: %		Drawback: the function create/assign a variable called 'axisH' in base workspace. Potential conflicts here ...
wolffd@0: %		* - properties are not case sensitive anymore
wolffd@0: %		* - 'exp' can be used instead of 'expression' for property name (following John D'Errico comment, if I understood it well ....)
wolffd@0: %		
wolffd@0: %
wolffd@0: %	Author : Emmanuel P. Dinnat
wolffd@0: %	Date : 09/2005
wolffd@0: %	Contact: emmanueldinnat@yahoo.fr
wolffd@0: 
wolffd@0: global hlink % make the properties link global
wolffd@0: 
wolffd@0: %% Default values for properties
wolffd@0: axisH = gca;
wolffd@0: xTickLabelFormat = '%4.1f';
wolffd@0: xLabStr = '';
wolffd@0: expression = '';
wolffd@0: 
wolffd@0: %% Process input parameters (if they exist)
wolffd@0: % if input parameters
wolffd@0: if length(varargin) > 0
wolffd@0: 	if isstr(varargin{1}) % if no axes handle is passed ...
wolffd@0: 		axisH = gca;
wolffd@0: 		if (length(varargin) > 1)
wolffd@0: 			properties = varargin(1:end);
wolffd@0: 		end
wolffd@0: 	else % else deal with passed axes handle
wolffd@0: 		if ishandle(varargin{1})
wolffd@0: 			axisH = varargin{1};
wolffd@0: 		else
wolffd@0: 			error('addTopXAxis : handle for axes invalid.')
wolffd@0: 		end
wolffd@0: 		properties = varargin(2:end);
wolffd@0: 	end
wolffd@0: 	if ~mod(length(properties),2)
wolffd@0: 		for iArg = 1:length(properties)/2
wolffd@0: 			% switch properties{2*iArg-1}
wolffd@0: 			switch lower(properties{2*iArg-1}) % modif V2 - suppress case sensitivity
wolffd@0: 				case {'xticklabel','expression' , 'exp'} 
wolffd@0: 					expression = properties{2*iArg};
wolffd@0: 				% case 'xLabStr'
wolffd@0: 				case {'xlabel','xlabstr'} % V2
wolffd@0: 					xLabStr = properties{2*iArg};
wolffd@0: 				% case 'xTickLabelFormat'
wolffd@0: 				case 'xticklabelformat' % V2
wolffd@0: 					xTickLabelFormat = properties{2*iArg};
wolffd@0: 				otherwise
wolffd@0: 					error(['addTopXAxis : property ''', properties{2*iArg-1},''' does not exist.'])
wolffd@0: 			end
wolffd@0: 		end
wolffd@0: 	else
wolffd@0: 		error('addTopXAxis : arguments number for proporties should be even.')
wolffd@0: 	end
wolffd@0: end % if input parameters
wolffd@0: %% replace |argu| by x-tick labels in the computation expression for new x-tick labels	
wolffd@0: % 	newXtickLabel_command = regexprep(expression, 'argu', 'get(axisH, ''xTick'')''');
wolffd@0: 
wolffd@0: %% Get paramters of figures to be modified (other parameters to be copied on the new axis are not extracted)
wolffd@0: 	set(axisH, 'units', 'normalized');
wolffd@0: 	cAxis_pos = get(axisH, 'position');
wolffd@0: %% shift downward original axis a little bit
wolffd@0:  	cAxis_pos(2) = cAxis_pos(2)*0.8;
wolffd@0: 	set(axisH, 'position', cAxis_pos);
wolffd@0: %% Make new axis
wolffd@0: 	nAxis = subplot('position', [cAxis_pos(1), (cAxis_pos(2)+cAxis_pos(4))*1.007, cAxis_pos(3), 0.0001]);
wolffd@0: %% put new Xaxis on top
wolffd@0: 	set(nAxis, 'xaxisLocation', 'top');
wolffd@0: %% Improve readability
wolffd@0: 	%% delete Y label on new axis
wolffd@0: 	set(nAxis, 'yTickLabel', []);
wolffd@0: 	% remove box for original axis
wolffd@0: % 	set(axisH, 'box', 'off');
wolffd@0: 	% remove grids
wolffd@0: 	set(nAxis, 'yGrid', 'off');
wolffd@0: 	set(nAxis, 'xGrid', 'off');
wolffd@0: %% Set new Xaxis limits, ticks and subticks the same as original ones (by link) ...
wolffd@0: 	set(nAxis, 'xlim', get(axisH, 'xlim'));
wolffd@0: 	set(nAxis, 'XTick', get(axisH, 'XTick'));
wolffd@0: 	set(nAxis, 'XMinorTick', get(axisH, 'XMinorTick'));
wolffd@0: 	hlink = linkprop([nAxis, axisH], {'xLim','XTick','XMinorTick'});
wolffd@0: %% ... but replace ticks labels by new ones !!!
wolffd@0: 	assignin('base', 'axisH', axisH)
wolffd@0: 	% set(nAxis, 'xtickLabel',  num2str(evalin('base', newXtickLabel_command), xTickLabelFormat));
wolffd@0:     set(nAxis, 'xtickLabel', expression);
wolffd@0:     %% but label for new axis
wolffd@0: 	if exist('xLabStr')
wolffd@0:         xlabel(xLabStr)
wolffd@0: 	end
wolffd@0: %% return current axis to original one (for further modification affecting original axes)
wolffd@0: 	axes(axisH);
wolffd@0: %	hlink = linkprop([nAxis, gca], {'xLim','XTick','XMinorTick'})