Debug outputs conventions

From OPS
Jump to: navigation, search

All CReSIS Toolbox Development Guides


Any function that generates debug or status outputs should use the following conventions:

  1. The param input structure for this function should include the following fields: debug_out_dir, debug_plots. For example, the script collate_deconv should have param.collate_deconv.debug_out_dir and so on.
  2. Any additional fields required for the debug plots should begin with "debug_"
  3. The outputs should be stored in a filepath generated with ct_filename_ct_tmp.m
  4. Figures should be stored in jpg and fig formats. If the fig file is too large, it can be left off if necessary: but ideally data would be decimated in this case so the file is not too large.


The default value for debug_out_dir must always be a string containing the name of the function and generally users should be discouraged from changing it. Typical "input checks" section code should include:

if ~isfield(param.(mfilename),'debug_out_dir') || isempty(param.(mfilename).debug_out_dir)
  param.check_surface.debug_out_dir = mfilename;

The file names should be constructed like this:

fn = [ct_filename_ct_tmp(param,'',debug_out_dir,sprintf('table_wf_%02d_adc_%02d',wf,adc)) '.txt'];

Note that if files are specific to a waveform-adc pair, then these fields should be included in the filename. Filenames should be generated so that alphabetical ordering of the files helps make browsing the images convenient. For gRadar.ct_tmp_path "/work/USER/Scratch/", a typical output filename would be:



The param.(mfilename).debug_plots field should be a cell array of strings which enable different output plots or tables. The default value for debug_plots depends on the function and may be an empty cell array or include any number of the debug plot commands.

The debug_plots field should always support a 'visible' property that allows plots to be generated in the background or hidden from view. Generally if 'visible' is set and the plots are generated with the visible property set to true, then the function should drop into a debug prompt to allow the user to look at the plots before continuing on.

Plots should be generated with a set of code like this:

% Example which creates 4 debug plots to work with.
if ~isempty(param.(mfilename).debug_plots)
  h_fig = get_figures(4,any(strcmp('visible',param.(mfilename).debug_plots)));

The plots should be created and saved in a way similar to the following. It is critical that the GUI parameters h_fig, h_axes, etc are used to generate the plots. Never rely on the figure or axes focus to be correct (i.e. never use gca.m or gcf.m functions): always explicitly specify the axes and figure that is being manipulated.

set(h_fig(1),'Name',['Peakiness ' param.day_seg]);
h_axes = subplot(2,1,1,'parent',h_fig(1));
plot(h_axes(1), spec.frm, spec.peakiness,'x');
xlabel(h_axes(1), 'Frame');
ylabel(h_axes(1), 'Peakiness (higher is better)');
title(h_axes(1), regexprep(param.day_seg,'_','\\_'));
grid(h_axes(1), 'on');

h_axes(2) = subplot(2,1,2,'parent',h_fig(1));
plot(h_axes(2), spec.rec, spec.peakiness,'x');
xlabel(h_axes(2), 'Record');
ylabel(h_axes(2), 'Peakiness (higher is better)');
grid(h_axes(2), 'on');

fig_fn = [ct_filename_ct_tmp(param,'',debug_out_dir,sprintf('%s_peakiness_wf_%02d_adc_%02d',param.collate_deconv.out_path,wf,adc)) '.fig'];
fprintf('Saving %s\n', fig_fn);
fig_fn_dir = fileparts(fig_fn);
if ~exist(fig_fn_dir,'dir')
fig_fn = [ct_filename_ct_tmp(param,'',debug_out_dir,sprintf('%s_peakiness_wf_%02d_adc_%02d',param.collate_deconv.out_path,wf,adc)) '.jpg'];
fprintf('Saving %s\n', fig_fn);

Also, if visible is false, then the figures should always be closed at the end of the function to prevent hidden figures from lingering.

if ~any(strcmp('visible',param.(mfilename).debug_plots))

Plots should always be saved with the "ct_saveas" command rather than the "saveas" command.

Personal tools