matlab_class/gcmfaces_IO/write2nctiles.m

function [dimOut]=write2nctiles(fileOut,fldIn,doCreate,varargin);
%object : write gcmfaces object to netcdf files (tiled)
%inputs : fileOut is the name of the file to be created
%         fldIn is the array to write to disk
%         doCreate is a 0/1 switch; 1 => create file ; 0 => append to file. 
%optional paramaters :
%         can be provided in the form {'name',value}
%         those that are currently active are
%               'descr' is the file description (default '').
%               'rdm' is the extended estimate description (default '').
%               'fldName' is the nc variable name for fld (default : the outside name of fldIn).
%               'longName' is the corresponding long name (default : '').
%               'units' is the unit of fld (default : '(unknown)').
%               'missval' is the missing value (default : NaN).
%               'fillval' is the fill value (default : NaN).
%               'tileNo' is a map of tile indices (default is face number)
%               'coord' is auxilliary coordinates attribute (e.g. 'lon lat dep')
%netcdf dimensions : array dimensions are simply set to 'i1,i2,...'

gcmfaces_global;
if ~(myenv.useNativeMatlabNetcdf);
  error('only native matlab nectdf is supported in write2nctiles');
end;

doCheck=0;%set to one to print stuff to screen

fldInIsaGcmfaces=isa(fldIn,'gcmfaces');

%set more optional paramaters to default values
descr=''; 
rdm='';
fldName=inputname(2); longName=''; 
units='(unknown)'; missval=NaN; fillval=NaN; dimIn=[];
tileNo=mygrid.XC; for ff=1:mygrid.nFaces; tileNo{ff}(:)=ff; end;
coord='';

%set more optional paramaters to user defined values
for ii=1:nargin-3;
    if ~iscell(varargin{ii});
        warning('inputCheck:write2nctiles_1',...
            ['write2nctiles expects \n'...
            '         its optional parameters as cell arrays. \n'...
            '         Argument no. ' num2str(ii+1) ' was ignored \n'...
            '         Type ''help write2nctiles'' for details.']);
    elseif ~ischar(varargin{ii}{1});
        warning('inputCheck:write2nctiles_2',...
            ['write2nctiles expects \n'...
            '         its optional parameters cell arrays \n'...
            '         to start with character string. \n'...
            '         Argument no. ' num2str(ii+1) ' was ignored \n'...
            '         Type ''help write2nctiles'' for details.']);
    else;
        if strcmp(varargin{ii}{1},'descr')|...
                strcmp(varargin{ii}{1},'rdm')|...
                strcmp(varargin{ii}{1},'fldName')|...
                strcmp(varargin{ii}{1},'longName')|...
                strcmp(varargin{ii}{1},'units')|...
                strcmp(varargin{ii}{1},'missval')|...
                strcmp(varargin{ii}{1},'fillval')|...
                strcmp(varargin{ii}{1},'tileNo')|...
                strcmp(varargin{ii}{1},'coord')|...
                strcmp(varargin{ii}{1},'dimIn');
            eval([varargin{ii}{1} '=varargin{ii}{2};']);
        else;
            warning('inputCheck:write2nctiles_3',...
                ['unknown option ''' varargin{ii}{1} ''' was ignored']);
        end;
    end;
end;

%split fldIn (if isa gcmfaces) into tiles
tileList=unique(convert2vector(tileNo)); 
tileList=tileList(~isnan(tileList));
ntile=length(tileList);
%
if fldInIsaGcmfaces;
 for ff=1:ntile; 
   tmp1=[];
   for gg=1:mygrid.nFaces;
     [tmpi,tmpj]=find(tileNo{gg}==ff);
     if ~isempty(tmpi);
       tmpi=[min(tmpi(:)):max(tmpi(:))];
       tmpj=[min(tmpj(:)):max(tmpj(:))];
       tmp1=fldIn{gg}(tmpi,tmpj,:,:);
     end;
   end;
   fldTiles{ff}=tmp1;
 end;
 clear fldIn;
end;

%start processing loop
for ff=1:ntile;

if fldInIsaGcmfaces;
  fldTile=fldTiles{ff};
  %reverse order of dimensions
  nn=length(size(fldTile));
  fldTile=permute(fldTile,[nn:-1:1]);
  if ntile==1; clear fldTiles; end;
else;
  fldTile=fldIn;
end;
fileTile=[fileOut sprintf('.%04d.nc',ff)];

%select dimensions of relevance:
nDim=length(size(fldTile));
dimsize=size(fldTile);
for iDim=1:nDim;
if size(fldTile,iDim)~=1;
    dimlist{iDim}=['i' num2str(iDim)];
    dimName{iDim}=['array index ' num2str(iDim)];
    eval(['dimvec.i' num2str(iDim) '=[1:size(fldTile,iDim)];']);
end;
end;

%omit singleton dimensions:
ii=find(dimsize~=1);
dimsize=dimsize(ii);
dimlist={dimlist{ii}};
dimName={dimName{ii}};

%check : 
if doCheck;
whos fldTile
descr
fldName
longName
units
missval
fillval
dimlist
dimName
dimsize
dimvec
keyboard;
end;

%output dimension information
dimOut{ff}=dimlist;

if doCreate;
  %create netcdf file:
  %-------------------
  if prod(size(fldTile))*4/1e9<1.5;%use (always available) basic ncetcf:
    mode='clobber';
  else;%to allow for large file:
    mode='NETCDF4';
  end;
  ncid=nccreate(fileTile,mode);
  nc_global=netcdf.getConstant('NC_GLOBAL');

  if ~isempty(rdm); 
    descr2=[descr ' -- ' rdm{1}];
  else;
    descr2=descr;
  end;
  ncputAtt(ncid,'','description',descr2);
  for pp=2:length(rdm);
  tmp1=char(pp+63);
  netcdf.putAtt(ncid,nc_global,tmp1,rdm{pp});
  end;
  %append readme
  pp=length(rdm)+1;
  netcdf.putAtt(ncid,nc_global,tmp1,'file created using gcmfaces_IO/write2nctiles.m');
  ncputAtt(ncid,'','date',date);
  netcdf.putAtt(ncid,nc_global,'Conventions','CF-1.6')   

  ncputAtt(ncid,'','_FillValue',fillval);
  ncputAtt(ncid,'','missing_value',missval);

  ncdefDim(ncid,'itxt',30);
  for dd=1:length(dimlist); ncdefDim(ncid,dimlist{dd},dimsize(dd)); end;

  for dd=1:length(dimlist);
    ncdefVar(ncid,dimlist{dd},'double',{dimlist{dd}});
    ncputAtt(ncid,dimlist{dd},'long_name',dimName{dd});
    ncputAtt(ncid,dimlist{dd},'units','1');
  end;
  ncclose(ncid);

  %fill in the dimensions dimensions values vectors:
  %-------------------------------------------------
  ncid=ncopen(fileTile,'write');
  for dd=1:length(dimlist);
    ncputvar(ncid,dimlist{dd},getfield(dimvec,dimlist{dd}));
  end;
  ncclose(ncid);
end;

%use dimentsion specified by user
if ~isempty(dimIn); dimlist=dimIn{ff}; end;

%define and fill field:
%----------------------
ncid=ncopen(fileTile,'write');
%
netcdf.reDef(ncid);
ncdefVar(ncid,fldName,'double',flipdim(dimlist,2));%note the direction flip
if ~isempty(longName); ncputAtt(ncid,fldName,'long_name',longName); end;
if ~isempty(units); ncputAtt(ncid,fldName,'units',units); end;
if ~isempty(coord); ncputAtt(ncid,fldName,'coordinates',coord); end; 
if strcmp(fldName,'lon'); ncputAtt(ncid,fldName,'standard_name','longitude'); end;
if strcmp(fldName,'lat'); ncputAtt(ncid,fldName,'standard_name','latitude'); end;
if strcmp(fldName,'dep'); ncputAtt(ncid,fldName,'standard_name','depth'); end;
if strcmp(fldName,'tim'); ncputAtt(ncid,fldName,'standard_name','time'); end;
if strcmp(fldName,'land'); ncputAtt(ncid,fldName,'standard_name','land_binary_mask'); end;
if strcmp(fldName,'area'); ncputAtt(ncid,fldName,'standard_name','cell_area'); end;
if strcmp(fldName,'thic'); ncputAtt(ncid,fldName,'standard_name','cell_thickness'); end;
netcdf.endDef(ncid);
%
ncputvar(ncid,fldName,fldTile);
ncclose(ncid);

end;%for ff=1:ntile;

1	gforget	1.1	function [dimOut]=write2nctiles(fileOut,fldIn,doCreate,varargin);
2			%object : write gcmfaces object to netcdf files (tiled)
3			%inputs : fileOut is the name of the file to be created
4			% fldIn is the array to write to disk
5			% doCreate is a 0/1 switch; 1 => create file ; 0 => append to file.
6			%optional paramaters :
7			% can be provided in the form {'name',value}
8			% those that are currently active are
9			% 'descr' is the file description (default '').
10	gforget	1.2	% 'rdm' is the extended estimate description (default '').
11	gforget	1.1	% 'fldName' is the nc variable name for fld (default : the outside name of fldIn).
12			% 'longName' is the corresponding long name (default : '').
13			% 'units' is the unit of fld (default : '(unknown)').
14			% 'missval' is the missing value (default : NaN).
15			% 'fillval' is the fill value (default : NaN).
16	gforget	1.4	% 'tileNo' is a map of tile indices (default is face number)
17	gforget	1.5	% 'coord' is auxilliary coordinates attribute (e.g. 'lon lat dep')
18	gforget	1.1	%netcdf dimensions : array dimensions are simply set to 'i1,i2,...'
19
20			gcmfaces_global;
21	gforget	1.5	if ~(myenv.useNativeMatlabNetcdf);
22			error('only native matlab nectdf is supported in write2nctiles');
23			end;
24	gforget	1.1
25			doCheck=0;%set to one to print stuff to screen
26
27	gforget	1.7	fldInIsaGcmfaces=isa(fldIn,'gcmfaces');
28
29	gforget	1.1	%set more optional paramaters to default values
30			descr='';
31	gforget	1.2	rdm='';
32	gforget	1.1	fldName=inputname(2); longName='';
33	gforget	1.4	units='(unknown)'; missval=NaN; fillval=NaN; dimIn=[];
34			tileNo=mygrid.XC; for ff=1:mygrid.nFaces; tileNo{ff}(:)=ff; end;
35	gforget	1.5	coord='';
36	gforget	1.1
37			%set more optional paramaters to user defined values
38			for ii=1:nargin-3;
39			if ~iscell(varargin{ii});
40			warning('inputCheck:write2nctiles_1',...
41			['write2nctiles expects \n'...
42			' its optional parameters as cell arrays. \n'...
43			' Argument no. ' num2str(ii+1) ' was ignored \n'...
44			' Type ''help write2nctiles'' for details.']);
45			elseif ~ischar(varargin{ii}{1});
46			warning('inputCheck:write2nctiles_2',...
47			['write2nctiles expects \n'...
48			' its optional parameters cell arrays \n'...
49			' to start with character string. \n'...
50			' Argument no. ' num2str(ii+1) ' was ignored \n'...
51			' Type ''help write2nctiles'' for details.']);
52			else;
53			if strcmp(varargin{ii}{1},'descr')\|...
54	gforget	1.2	strcmp(varargin{ii}{1},'rdm')\|...
55	gforget	1.1	strcmp(varargin{ii}{1},'fldName')\|...
56			strcmp(varargin{ii}{1},'longName')\|...
57			strcmp(varargin{ii}{1},'units')\|...
58			strcmp(varargin{ii}{1},'missval')\|...
59			strcmp(varargin{ii}{1},'fillval')\|...
60	gforget	1.4	strcmp(varargin{ii}{1},'tileNo')\|...
61	gforget	1.5	strcmp(varargin{ii}{1},'coord')\|...
62	gforget	1.1	strcmp(varargin{ii}{1},'dimIn');
63			eval([varargin{ii}{1} '=varargin{ii}{2};']);
64			else;
65			warning('inputCheck:write2nctiles_3',...
66			['unknown option ''' varargin{ii}{1} ''' was ignored']);
67			end;
68			end;
69			end;
70
71	gforget	1.4	%split fldIn (if isa gcmfaces) into tiles
72			tileList=unique(convert2vector(tileNo));
73			tileList=tileList(~isnan(tileList));
74			ntile=length(tileList);
75			%
76	gforget	1.7	if fldInIsaGcmfaces;
77	gforget	1.4	for ff=1:ntile;
78			tmp1=[];
79			for gg=1:mygrid.nFaces;
80			[tmpi,tmpj]=find(tileNo{gg}==ff);
81			if ~isempty(tmpi);
82			tmpi=[min(tmpi(:)):max(tmpi(:))];
83			tmpj=[min(tmpj(:)):max(tmpj(:))];
84			tmp1=fldIn{gg}(tmpi,tmpj,:,:);
85			end;
86			end;
87			fldTiles{ff}=tmp1;
88			end;
89	gforget	1.7	clear fldIn;
90	gforget	1.4	end;
91
92			%start processing loop
93			for ff=1:ntile;
94	gforget	1.1
95	gforget	1.7	if fldInIsaGcmfaces;
96	gforget	1.4	fldTile=fldTiles{ff};
97	gforget	1.1	%reverse order of dimensions
98			nn=length(size(fldTile));
99			fldTile=permute(fldTile,[nn:-1:1]);
100	gforget	1.7	if ntile==1; clear fldTiles; end;
101	gforget	1.1	else;
102			fldTile=fldIn;
103			end;
104	gforget	1.4	fileTile=[fileOut sprintf('.%04d.nc',ff)];
105	gforget	1.1
106			%select dimensions of relevance:
107			nDim=length(size(fldTile));
108			dimsize=size(fldTile);
109			for iDim=1:nDim;
110			if size(fldTile,iDim)~=1;
111			dimlist{iDim}=['i' num2str(iDim)];
112			dimName{iDim}=['array index ' num2str(iDim)];
113			eval(['dimvec.i' num2str(iDim) '=[1:size(fldTile,iDim)];']);
114			end;
115			end;
116
117			%omit singleton dimensions:
118			ii=find(dimsize~=1);
119			dimsize=dimsize(ii);
120			dimlist={dimlist{ii}};
121			dimName={dimName{ii}};
122
123			%check :
124			if doCheck;
125			whos fldTile
126			descr
127			fldName
128			longName
129			units
130			missval
131			fillval
132			dimlist
133			dimName
134			dimsize
135			dimvec
136			keyboard;
137			end;
138
139			%output dimension information
140			dimOut{ff}=dimlist;
141
142			if doCreate;
143			%create netcdf file:
144			%-------------------
145	gforget	1.7	if prod(size(fldTile))*4/1e9<1.5;%use (always available) basic ncetcf:
146			mode='clobber';
147			else;%to allow for large file:
148			mode='NETCDF4';
149			end;
150			ncid=nccreate(fileTile,mode);
151	gforget	1.6	nc_global=netcdf.getConstant('NC_GLOBAL');
152	gforget	1.1
153	gforget	1.3	if ~isempty(rdm);
154			descr2=[descr ' -- ' rdm{1}];
155			else;
156			descr2=descr;
157			end;
158	gforget	1.4	ncputAtt(ncid,'','description',descr2);
159	gforget	1.2	for pp=2:length(rdm);
160			tmp1=char(pp+63);
161			netcdf.putAtt(ncid,nc_global,tmp1,rdm{pp});
162			end;
163			%append readme
164			pp=length(rdm)+1;
165			netcdf.putAtt(ncid,nc_global,tmp1,'file created using gcmfaces_IO/write2nctiles.m');
166	gforget	1.1	ncputAtt(ncid,'','date',date);
167	gforget	1.5	netcdf.putAtt(ncid,nc_global,'Conventions','CF-1.6')
168
169			ncputAtt(ncid,'','_FillValue',fillval);
170			ncputAtt(ncid,'','missing_value',missval);
171	gforget	1.1
172			ncdefDim(ncid,'itxt',30);
173			for dd=1:length(dimlist); ncdefDim(ncid,dimlist{dd},dimsize(dd)); end;
174
175			for dd=1:length(dimlist);
176			ncdefVar(ncid,dimlist{dd},'double',{dimlist{dd}});
177			ncputAtt(ncid,dimlist{dd},'long_name',dimName{dd});
178	gforget	1.5	ncputAtt(ncid,dimlist{dd},'units','1');
179	gforget	1.1	end;
180			ncclose(ncid);
181
182			%fill in the dimensions dimensions values vectors:
183			%-------------------------------------------------
184			ncid=ncopen(fileTile,'write');
185			for dd=1:length(dimlist);
186			ncputvar(ncid,dimlist{dd},getfield(dimvec,dimlist{dd}));
187			end;
188			ncclose(ncid);
189			end;
190
191			%use dimentsion specified by user
192			if ~isempty(dimIn); dimlist=dimIn{ff}; end;
193
194			%define and fill field:
195			%----------------------
196			ncid=ncopen(fileTile,'write');
197	gforget	1.5	%
198			netcdf.reDef(ncid);
199	gforget	1.1	ncdefVar(ncid,fldName,'double',flipdim(dimlist,2));%note the direction flip
200			if ~isempty(longName); ncputAtt(ncid,fldName,'long_name',longName); end;
201			if ~isempty(units); ncputAtt(ncid,fldName,'units',units); end;
202	gforget	1.5	if ~isempty(coord); ncputAtt(ncid,fldName,'coordinates',coord); end;
203			if strcmp(fldName,'lon'); ncputAtt(ncid,fldName,'standard_name','longitude'); end;
204			if strcmp(fldName,'lat'); ncputAtt(ncid,fldName,'standard_name','latitude'); end;
205			if strcmp(fldName,'dep'); ncputAtt(ncid,fldName,'standard_name','depth'); end;
206			if strcmp(fldName,'tim'); ncputAtt(ncid,fldName,'standard_name','time'); end;
207			if strcmp(fldName,'land'); ncputAtt(ncid,fldName,'standard_name','land_binary_mask'); end;
208			if strcmp(fldName,'area'); ncputAtt(ncid,fldName,'standard_name','cell_area'); end;
209			if strcmp(fldName,'thic'); ncputAtt(ncid,fldName,'standard_name','cell_thickness'); end;
210			netcdf.endDef(ncid);
211			%
212	gforget	1.1	ncputvar(ncid,fldName,fldTile);
213			ncclose(ncid);
214
215	gforget	1.4	end;%for ff=1:ntile;
216	gforget	1.1