UNM_write_for_gapfiller_file.m

function [ fgf, fname ]  = UNM_write_for_gapfiller_file( varargin )
% UNM_WRITE_FOR_GAPFILLER_FILE - write a delimited ASCII file that may be
% passed as input to REddyProc.
%
% given the necessary observed variables, writes a data file in the format
% expected by Max Planck Institute's eddy covariance gapfiller/flux partitioner.
% The file generated by be passed directly to UNM_run_gapfiller.
%
% The output file will be placed in a temporary directory provided by
% tempname and the full path to the file returned in fname.
%
% The gapfiller/flux partitioner is described more fully here (link is valid as
% of July 2013): http://www.bgc-jena.mpg.de/bgi/index.php/Services/REddyProcWeb
%
% Input arguments are checked that they are numeric and not empty.  No other
% validation is performed; it is the caller's responsibility to make sure inputs
% are reasonable (timestamps are valid, RH is between 0 and 1.0, etc.) for
% the units specified for each parameter-value pair.
%
% USAGE
%     UNM_write_for_gapfiller_file( 'timestamp', timestamp, ...
%                                   'NEE', NEE, ...
%                                   'LE', LE, ...
%                                   'H', H_dry, ...
%                                   'Rg', sw_incoming, ...
%                                   'Tair', Tair, ...
%                                   'Tsoil', Tsoil, ...
%                                   'RH', rH, ...
%                                   'VPD', vpd, ...
%                                   'Ustar', u_star, ...
%                                   'Precip', precip, ...
%                                   'fname', outfilename_forgapfill );
%
% PARAMETER-VALUE PAIRS:
%    timestamp: Matlab serial datenumbers; observation timestamps
%    NEE: numeric vector; net ecosystem exchange (umol m-2 s-1)
%    LE: numeric vector; latent heat flux (W m-2)
%    H: numeric vector; sensible heat flux (W m-2)
%    Rg: numeric vector; incoming shortwave radiation (W m-2)
%    Tair: numeric vector; air temperature (C)
%    Tsoil: numeric vector; soil temperature (C)
%    RH: numeric vector; relative humidity, (0-1)
%    VPD: numeric vector; vapor pressure deficit (hPa), OPTIONAL
%    Ustar: numeric vector; friction velocity (m s-1)
%    fname: character string; full path to the output file.  If unspecified,
%           defaults to a temporary file (provided by tempname)
%
% OUTPUTS
%    fgf: matlab dataset array; data formatted for the online gapfiller
%    fname: output file name
%
% SEE ALSO
%    tempname, datenum, dataset, UNM_run_gapfiller

% define a function to validate input arguments
f_validate = @(x) isnumeric(x) & not( isempty( x ) );

% -----
% parse inputs, with defaults and typechecking
% -----
args = inputParser;
args.addParameter( 'timestamp', [], f_validate );
args.addParameter( 'qcNEE', [], f_validate );
args.addParameter( 'NEE', [],  f_validate );
args.addParameter( 'LE', [], f_validate );
args.addParameter( 'H', [], f_validate );
args.addParameter( 'Rg', [], f_validate );
args.addParameter( 'Tair', [], f_validate );
args.addParameter( 'Tsoil', [], f_validate );
args.addParameter( 'RH', [], f_validate );
args.addParameter( 'VPD', [], f_validate );
args.addParameter( 'Ustar', [], f_validate );
args.addParameter( 'Precip', [], f_validate );
args.addParameter( 'fname', '', @ischar );

args.parse( varargin{ : } );

[ year, month, day, hour, minute, ~ ] = datevec( args.Results.timestamp );
%hhmm = strcat(num2str(hour), num2str(minute))

if isempty( args.Results.VPD )
    VPD = repmat( NaN, size( args.Results.timestamp ) );
else
    VPD = args.Results.VPD;
end

var_names = { 'day', 'month', 'year', 'hour', 'minute', 'qcNEE', 'NEE', 'LE', 'H', ...
              'Rg', 'Tair', 'Tsoil', 'rH', 'VPD', 'Ustar', 'Precip' };
var_units = { '--', '--', '--', '--', '--', '--', 'umolm-2s-1', 'Wm-2', 'Wm-2', ...
              'Wm-2', 'degC', 'degC', '%', 'hPa', 'ms-1', 'mm' };
fgf = array2table( [ day, ...
                   month, ...
                   year, ...
                   hour, ...
                   minute, ...
                   args.Results.qcNEE, ...
                   args.Results.NEE, ...
                   args.Results.LE, ...
                   args.Results.H, ...
                   args.Results.Rg, ...
                   args.Results.Tair, ...
                   args.Results.Tsoil, ...
                   args.Results.RH, ...
                   args.Results.VPD, ...
                   args.Results.Ustar, ...
                   args.Results.Precip], ...
                 'VariableNames', var_names );
fgf.Properties.VariableUnits = var_units;

if isempty( args.Results.fname )
    fname = tempname();
else
    fname = args.Results.fname;
end

write_table_std( fname, ...
                    fgf, ...
                    'replace_nans', -9999, ...
                    'write_units', true );