function [success] = Westerschelde_Volumes(File,varargin)
%Westerschelde_Volumes  Compute and plot various volumes in the 
%                       Westernscheldt estuary.
%
%  Information is read from an xls-file with information and volumes can be
%  computed for combinations of vakken like trenches, macrocells and individual
%  compartments. The volumes are (can be) plotted for the selection.
%
%   Syntax:
%   [success] = Westerschelde_Volumes(File,varargin)
%
%   Input:
%   File      = the path and name of the excell sheet to be used
%   varargin  = information on what combination must be plotted. key/value
%               pairs are used.
%               'selection'  - what selection of compartments must be
%                              computed
%                    'macrocel'  
%                            'set' - give the number of the macrocell
%                            'trenchtype' - with macrocell one
%                                             of this key/value combinations
%                                             is possible
%                                  'flood', 'ebb' or '' (NEITHER flood
%                                             NOR ebb, when available)
%                                  'trenches' both flood and ebb are used
%                                  'all'      as trenches extended with the
%                                             compartments NOT flood or ebb
%                                             (default)
%                    'Heakon'     - one or more Heakon compartments
%                    'Compartments'- one or more Rvaksas compartments (combined)
%                            'set'    - give a set of numbers for 'Heakon' 
%                                       or 'Compartments' in a [] set array
%               'volumes'    - what volumes must be computed and plotted:
%                                'total'   = total volume 
%                                'diep'    = volume below -5m NAP
%                                'ondiep'  = volume below -2m NAP
%                                'plaat'   = volume above -2m NAP
%                                'tussen'  = volume between -5m and -2m NAP
%                                'ingreep' = volume van de ingrepen (per
%                                             jaar)
%                              When the key is not found everything ('all')
%                              is plotted.
%                              Any combination of types is allowed and will
%                              be plotted.
%               'show'       - overview of the selected combination is written to the given
%                              file (default nothing is shown)
%               'plotname'   - set the name and the plot type in a cell:
%                              {name type} the default type is jpg, when
%                              not given or empty nothing is plotted
%               'cd'         - when given change to that directory
%               'subtitle'   - sub-title of the plot
%               'x' / 'y'    - the axes texts
%               'legend'     - the position of the legend with respect to
%                              the graph (southeast a.s.o)
%      
%   Output:
%   varargout = was the result successfull (yes or no) 
%
%   Example
%   Untitled
%
%   See also 

%% Copyright notice
%   --------------------------------------------------------------------
%   Copyright (C) 2010 <COMPANY>
%       Lou Verhage
%
%       <lou.verhage@deltares.nl>	
%
%       <ADDRESS>
%
%   This library is free software: you can redistribute it and/or
%   modify it under the terms of the GNU Lesser General Public
%   License as published by the Free Software Foundation, either
%   version 2.1 of the License, or (at your option) any later version.
%
%   This library is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Lesser General Public License for more details.
%
%   You should have received a copy of the GNU Lesser General Public
%   License along with this library. If not, see <http://www.gnu.org/licenses/>.
%   --------------------------------------------------------------------

% This tool is part of <a href="http://OpenEarth.nl">OpenEarthTools</a>.
% OpenEarthTools is an online collaboration to share and manage data and 
% programming tools in an open source, version controlled environment.
% Sign up to recieve regular updates of this function, and to contribute 
% your own tools.

%% Version <http://svnbook.red-bean.com/en/1.5/svn.advanced.props.special.keywords.html>
% Created: 06 Sep 2010
% Created with Matlab version: 7.8.0.347 (R2009a)

% $Id: $
% $Date: $
% $Author: $
% $Revision: $
% $HeadURL: $
% $Keywords: $

%% initialise the computation

success =  true;
if nargin > 0
    % open the file and get the sheet names
    try
        file = validpath(File,'.xls');
    catch exception
        errordlg(sprintf('File "%s  not found.',File),'!!Excell file!!','modal');
        success = false;
        return
    end
else
    errordlg('No file name given.','!!Excell file!!','modal');
    success = false;
    return
end

%get the sheets names
theSheets = xlsSheets(file);

OPT.selection   = 'macrocel'; %possible: 'macrocel', 'Heakon', 'compartments' (=rvaksas)
OPT.trenchtype  = 'all'; %used for 'macrocell' possible: flood, eb, tide, all
OPT.set         = 1; %default number is set to 1, it is possible to give a 
                     %set of compartments for 'Heakon' or 'compartments'                   
OPT.volumes     = 'all';
OPT.show        = false;
OPT.plotname    = ['test','jpg'];
OPT.cd          = '';
OPT.subtitle    = '';
OPT.x           = 'Tijd (jaar)';%x-axis legend
OPT.y           = 'Volumes t.o.v. 1955 (m3)'  ;%x-axis legend
OPT.legend      = 'best';
OPT.date        = '';

OPT = setproperty(OPT,varargin{:});

%compose the names of the sheets to be used for the computation
[sheets,vakken,ok] = getSheetCombination(file,OPT,theSheets);
if ~ok
    success = false;    
    return
end

%do the computation
[volumes,ok] = computeVolumes(file,sheets,OPT.volumes,OPT.date);
if ~ok
    success = false;    
    return
end

%plot the result
if ~isempty(OPT.plotname)
    plotVolumes(OPT,volumes);
end