add_var_FVCOM_river

 add time dependent scalar variable to a Riverfile

 function add_var_FVCOM_river(RiverFile,VarName,VarLongName,VarUnits,VarData)

 DESCRIPTION:
    Write an additional scalar variable (e.g. sediment, DO) to a netCDF
    River file.  Note that the concentration of the scalar variable
    is set the same at all river points in the file so it is assumed
    that even if the file contains multiple nodes, they all refer to the same
    river.

 INPUT
    RiverFile:   FVCOM 3.x netCDF river forcing file
    VarName:     Variable name (will be the name of the array in the netCDF file)
    VarLongName: Variable attribute "long_name"
    VarUnits:    Variable attribute "units"
    VarData:     1-D time series of variable data of exact same dimensions as
                 the river flux

 OUTPUT:
    Modified FVCOM RiverFile

 EXAMPLE USAGE
    add_var_FVCOM_river('tst_riv.nc','medium_sand','medium sand','kg-m^-3',sand_ts)

 Author(s):
    Geoff Cowles (University of Massachusetts Dartmouth)
    Pierre Cazenave (Plymouth Marine Laboratory)

 Revision history
    2016-04-01 Updated the code to use the native MATLAB netCDF routines.

==============================================================================

0001 function add_var_FVCOM_river(RiverFile,VarName,VarLongName,VarUnits,VarData)
0002 % add time dependent scalar variable to a Riverfile
0003 %
0004 % function add_var_FVCOM_river(RiverFile,VarName,VarLongName,VarUnits,VarData)
0005 %
0006 % DESCRIPTION:
0007 %    Write an additional scalar variable (e.g. sediment, DO) to a netCDF
0008 %    River file.  Note that the concentration of the scalar variable
0009 %    is set the same at all river points in the file so it is assumed
0010 %    that even if the file contains multiple nodes, they all refer to the same
0011 %    river.
0012 %
0013 % INPUT
0014 %    RiverFile:   FVCOM 3.x netCDF river forcing file
0015 %    VarName:     Variable name (will be the name of the array in the netCDF file)
0016 %    VarLongName: Variable attribute "long_name"
0017 %    VarUnits:    Variable attribute "units"
0018 %    VarData:     1-D time series of variable data of exact same dimensions as
0019 %                 the river flux
0020 %
0021 % OUTPUT:
0022 %    Modified FVCOM RiverFile
0023 %
0024 % EXAMPLE USAGE
0025 %    add_var_FVCOM_river('tst_riv.nc','medium_sand','medium sand','kg-m^-3',sand_ts)
0026 %
0027 % Author(s):
0028 %    Geoff Cowles (University of Massachusetts Dartmouth)
0029 %    Pierre Cazenave (Plymouth Marine Laboratory)
0030 %
0031 % Revision history
0032 %    2016-04-01 Updated the code to use the native MATLAB netCDF routines.
0033 %
0034 %==============================================================================
0035 
0036 %warning off
0037 
0038 [~, subname] = fileparts(mfilename('fullpath'));
0039 global ftbverbose
0040 if ftbverbose
0041     fprintf('\nbegin : %s\n', subname)
0042 end
0043 
0044 if ftbverbose
0045     fprintf('adding variable %s to file %s\n', VarName, RiverFile)
0046 end
0047 
0048 %------------------------------------------------------------------------------
0049 % Open River Netcdf and read dimensions
0050 %------------------------------------------------------------------------------
0051 if exist(RiverFile, 'file') ~= 2
0052     error('file: %s does not exist', RiverFile)
0053 end
0054 
0055 % read dimensions
0056 flux = ncread(RiverFile, 'river_flux');
0057 [nTimes, nRivnodes] = size(flux);
0058 
0059 % make sure time dimension matches FVCOM river dims
0060 tempTimes = numel(VarData);
0061 if nTimes ~= tempTimes
0062     fprintf('# of time frames in file %s is %d\n', RiverFile, tempTimes)
0063     fprintf('# of time frames in VarData is %d\n', nTimes)
0064     error('You have chosen the wrong vocation')
0065 end
0066 
0067 
0068 %------------------------------------------------------------------------------
0069 % Write variable definition and data and close file
0070 %------------------------------------------------------------------------------
0071 
0072 % set field
0073 river_field = repmat(VarData, nRivnodes, 1);
0074 
0075 %------------------------------------------------------------------------------
0076 % dump to netcdf file
0077 %------------------------------------------------------------------------------
0078 
0079 % open boundary forcing
0080 nc = netcdf.open(RiverFile, 'NC_WRITE');
0081 
0082 % define dimensions
0083 time_dimid = netcdf.inqDimID(nc, 'time');
0084 rivers_dimid = netcdf.inqDimID(nc, 'rivers');
0085 
0086 % add the new variable if it doesn't already exist.
0087 try
0088     netcdf.reDef(nc);
0089     varid = netcdf.defVar(nc, VarName, 'NC_FLOAT', [rivers_dimid, time_dimid]);
0090     netcdf.putAtt(nc, varid, 'long_name', VarLongName);
0091     netcdf.putAtt(nc, varid, 'units', VarUnits);
0092 
0093     % end definitions
0094     netcdf.endDef(nc);
0095 
0096     % dump dynamic data
0097     netcdf.putVar(nc, varid, river_field);
0098 catch e
0099     fprintf(e.message)
0100     error('Adding variable %s failed - does the variable already exist?', VarName)
0101 end
0102 
0103 netcdf.close(nc);
0104 
0105 if ftbverbose
0106     fprintf('end   : %s\n', subname)
0107 end
0108