source: trunk/src/showgrid.m @ 327

function [result]=showgrid(lon_value, lat_value, mode)

%SHOWGRID show grid on a world map

%+
%
% ==========
% showgrid.m
% ==========
%
% .. function:: showgrid(lon_value, lat_value, mode)
%
% DESCRIPTION
% ===========
%
%    :param lon_value: longitude array
%    :type lon_value: 1D array
%    :raise lon_value: required
%
%    :param lat_value: latitude array
%    :type lat_value: 1D array
%    :raise lat_value: required
%
%    :param mode: 'line' or 'grid'
%    :type mode: string
%    :raise mode: required
%
%    :returns: 0 if ok or -1 if error
%    :rtype: integer
%
% On a new figure, plot over a world map the grid defined by **lon_value**
% and **lat_value**.
%
% Dimensions of the plot is 2° larger than latitudes and longitudes given in
% input.
%
% If mode is set to 'line', lon_value and lat_value are plotted as they are.
%
% If mode is set to 'grid', lon_value and lat_valuer are reorganized to be plot.
%
% EXAMPLES
% ========
%
% From scratch to show grid of the simulated LAI "1" latitude and longitude:
%
% see demo 1
%
% From scratch to show grid of the simulated LAI "1" 2D latitude and longitude:
%
% see demo 2
%
% From scratch to show grid of the simulated LAI "2" latitude and longitude:
%
% see demo 3
%
% From real file MSG file
% :file:`${PROJECT_ID}/MSG/2006/07/msg-tb108_2006-07-31_15min.nc`:
%
% see demo 4
%
% From real file AMSU
% :file:`${PROJECT_ID}/AMSU/2006/07/amsubch5-noaa17_20060731-225107_afratl_Nadir.nc`:
%
% see demo 5
%
% From real file :file:`${PROJECT_ID}/LAI/laisen2001_float.txt`:
%
% see demo 6
%
% From scratch to show grid of the simulated EPSAT latitude and longitude:
%
% see demo 7
%
% SEE ALSO
% ========
%
% :ref:`data_lai`
% :ref:`data_msg`
% :ref:`data_amsu`
% :ref:`data_epsat`
%
% :ref:`world_map`
%
% :func:`simul_lai_2d`
% :func:`read_lai_2d`
%
% :func:`simul_epsat`
%
% TODO
% ====
%
% ++ check arguments (type, value)
%
% use reshape and meshgrid instead of loop
%
% lien sur traitdecote.mat
%
%
% label x, y et info résolution si mode grid sur le plot
%
% EVOLUTIONS
% ==========
%
% $Id: showgrid.m 325 2011-08-04 15:30:01Z pinsard $
%
% $URL$
%
% - fplod 20110609T094538Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * demo usin simul_msg
%
% - fplod 20110310T144432Z cratos.locean-ipsl.upmc.fr (Linux)
%
%   * add demo using :func:`simul_epsat`
%   * add references in rst header
%
% - fplod 20110302T172026Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * adapation for matlab : can not use octave size_equal
%
% - fplod 20110302T085925Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * test inconsistent dimensions of parameters
%
% - fplod 20110228T141829Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * examples moved to demos
%
% - fplod 20101208T103621Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * add some argument checking
%
% - fplod 20101207T082027Z adonis.locean-ipsl.upmc.fr (Linux)
%
%   * add some argument checking
%
% - fplod 20101202T133821Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * add parameter information in header
%   * laiyyyy_float.txt is replaced by laisenyyyy_float.txt (new format also)
%
% - fplod 20100923T154311Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * add mode parameter
%
% - fplod 20100901T111043Z aedon.locean-ipsl.upmc.fr (Darwin)
%
%   * creation to point out non orthogonal grid of LAI data
%
%     This point can be quickly shown by::
%
%      $ awk ' NR > 1 {print $1}' ${PROJECT_ID}/LAI/laisen2001_float.txt > lat.txt
%      $ awk ' NR > 1 {print $2}' ${PROJECT_ID}/LAI/laisen2001_float.txt > lon.txt
%      octave> lat_value=load('lat.txt');
%      octave> lon_value=load('lon.txt');
%      octave> plot(lon_value,lat_value)
%
%
%-
%
global application;
%
result=-1;
%
usage='result=showgrid(lon_value, lat_value, mode)';
%
if nargin~=3
   disp(['Incorrect number of arguments']);
   error(usage);
end
%
arg_info=whos('lon_value');
if ~strcmp(arg_info.class,'double')
   disp(['Incorrect type of arg lon_value']);
   whos lon_value
   error(usage);
end
clear arg_info
%
arg_info=whos('lat_value');
if ~strcmp(arg_info.class,'double')
   disp(['Incorrect type of arg lat_value']);
   whos lat_value
   error(usage);
end
clear arg_info
%
arg_info=whos('mode');
if ~strcmp(arg_info.class,'char')
   disp(['Incorrect type of arg mode']);
   whos mode
   error(usage);
end
clear arg_info
%
switch mode
   case {'line'}
      switch application
        case {'matlab'}
           test_consistent=isequal(numel(lon_value), numel(lat_value));
        case {'octave'}
           test_consistent=size_equal(lon_value, lat_value);
        otherwise
           error('unknown application running');
      end
      if (not(test_consistent))
         disp(['eee : inconsistent dimensions of lon_value and lat_value']);
         whos lon_value
         whos lat_value
         error(usage);
      end
   case {'grid'}
   otherwise
       disp(['eee : unknown mode : ' mode]);
       error(usage);
end
%
% ++ check arguments (values)
%
% find min and max of latitude and longitude
% to define axis not to close from data to be plot
latmin=min(lat_value);
latmax=max(lat_value);
ymin=latmin - 2;
ymax=latmax + 2;
clear latmin;
clear latmax;
lonmin=min(lon_value);
lonmax=max(lon_value);
xmin=lonmin - 2;
xmax=lonmax + 2;
clear lonmin;
clear lonmax;
%
% read world map
load('cmgco_traitdecote.mat','Xgco','Ygco');
%
% initialiaze a new figure
ifigure=gcf()+1;
figure(ifigure);
%
% plot world map (black dots)
plot(Xgco,Ygco,'k.','MarkerSize',1)
clear Xgco;
clear Ygco
%
% build x and y data from lat_value and lon_value
switch mode
   case {'line'}
      xdata=lon_value;
      ydata=lat_value;
   case {'grid'}
      nb_lat=size(lat_value,1);
      nb_lon=size(lon_value,1);
      % here we repeat each lon_value nb_lat times and
      % we repeat lat_value nb_lon times to have two arrays xdata and ydata
      % of the same dimension
      %
      for index_lon=1:nb_lon
       index_x1=(index_lon-1)*nb_lat + 1;
       index_x2=(index_lon)*nb_lat;
       xdata(index_x1:index_x2)=repmat(lon_value(index_lon),nb_lat,1);
      end
      clear index_lon;
      clear index_x1;
      clear index_x2;
      ydata=transpose(repmat(lat_value,nb_lon,1));
      %
      clear nb_lat;
      clear nb_lon;
      %
      % +todo+this might be done with something like
      %  [XX, YY] = meshgrid (lon_value, lat_value)
      % xdata=reshape(XX,nb_lon*nb_lat,1)
      % ydata=reshape(YY,nb_lon*nb_lat,1)
      %
   otherwise
      error(['unknown mode ', mode]);
end
% overplot grid points
hold on
plot(xdata,ydata,'ro')
clear xdata;
clear ydata;
% limit world map around latmin,latmax and lonmin, lonmax + 2 on each side
axis([xmin xmax ymin ymax]);
clear xmin;
clear xmax;
clear ymin;
clear ymax;
%
% clean memory
clear ifigure;
%
result=0;
%
end

%!demo
%! % From scratch to show grid of the simulated LAI "1" latitude and longitude::
%! varamma_startup
%! more off
%! index_simulation=int8(1);
%! [lon_value, lat_value, datestr_value, lai_value]=simul_lai(index_simulation);
%! mode='grid';
%! result=showgrid(lon_value, lat_value, mode);

%!demo
%! % From scratch to show grid of the simulated LAI "1" 2D latitude and longitude::
%! varamma_startup
%! more off
%! index_simulation=int8(1);
%! [lon_value, lat_value, datestr_value, lai_value]=simul_lai_2d(index_simulation);
%! mode='line';
%! result=showgrid(lon_value, lat_value, mode)

%!demo
%! % From scratch to show grid of the simulated LAI "2" latitude and longitude::
%! varamma_startup
%! more off
%! index_simulation=int8(2);
%! [lon_value, lat_value, datestr_value, lai_value]=simul_lai(index_simulation);
%! mode='grid';
%! result=showgrid(lon_value, lat_value, mode);

%!demo
%! % From real file MSG file
%! % :file:`${PROJECT_ID}/MSG/2006/07/msg-tb108_2006-07-31_15min.nc`::
%! varamma_startup
%! filename=['msg-tb108_2006-07-31_15min.nc'];
%! fullfilename=[PROJECT_ID,'MSG/2006/07/', filename];
%! file=netcdf(fullfilename,'nowrite');
%! lon_value=file{'LONGITUDE'};
%! lat_value=file{'LATITUDE'};
%! mode='grid';
%! result=showgrid(lon_value(:),lat_value(:), mode)

%!demo
%! % From real file AMSU
%! % :file:`${PROJECT_ID}/AMSU/2006/07/amsubch5-noaa17_20060731-225107_afratl_Nadir.nc`::
%! varamma_startup
%! filename=['amsubch5-noaa17_20060731-225107_afratl_Nadir.nc'];
%! fullfilename=[PROJECT_ID,'AMSU/2006/07/', filename];
%! file=netcdf(fullfilename,'nowrite');
%! lon_value=file{'lon'};
%! lat_value=file{'lat'};
%! mode='grid';
%! result=showgrid(lon_value(:),lat_value(:), mode)

%!demo
%!  % From real file :file:`${PROJECT_ID}/LAI/laisen2001_float.txt`::
%! varamma_startup
%! more off
%! yyyy=int16(2001);
%! [lon_value, lat_value, datestr_value, lai_value]=read_lai_2d(yyyy);
%! mode='grid';
%! result=showgrid(lon_value, lat_value, mode);

%!demo
%! % From scratch to show grid of the simulated EPSAT latitude and longitude::
%! varamma_startup
%! more off
%! index_simulation=int8(2);
%! [lon_value, lat_value, datejul_value, datestr_value, epsat_value]=simul_epsat(index_simulation);
%! mode='grid';
%! result=showgrid(lon_value, lat_value, mode)

%!demo
%! % From scratch to show grid of the simulated MSG latitude and longitude::
%! varamma_startup
%! more off
%! index_simulation=int8(3);
%! [lon_value, lat_value, datejul_value, datestr_value, epsat_value]=simul_msg(index_simulation);
%! mode='grid';
%! result=showgrid(lon_value, lat_value, mode)