working on finishing release 2.2

Several updates and improvements. Harmonization of the documentation and
help sections of each function.

@FLOWobj/FLOWobj.m

@@ -1,6 +1,6 @@
 classdef FLOWobj
 
-% Create flow direction object
+%FLOWOBJ create flow direction object
 %
 % Syntax
 %
@@ -584,8 +584,13 @@
  error('unknown flow direction type')
  end
 
- p = toposort(digraph(M));
- p = uint32(p);
+ try
+ p = toposort(digraph(M));
+ p = uint32(p);
+ catch
+ [p,~] = dmperm(speye(size(M))-M);
+ p = uint32(p);
+ end
 
  [FD.ix,FD.ixc,FD.fraction] = find(M(p,p));
 

@FLOWobj/FLOWobj2GRIDobj.m

@@ -1,10 +1,10 @@
 function G = FLOWobj2GRIDobj(F)
 
-% create ESRI ArcGIS flow direction grid from FLOWobj
+%FLOWOBJ2GRIDOBJ create ESRI ArcGIS flow direction grid from FLOWobj
 %
 % Syntax
 %
-% G = FLOWobj2GRIDobj(F)
+% AF = FLOWobj2GRIDobj(FD)
 %
 % Description
 %
@@ -15,20 +15,30 @@
 % 
 % Input arguments
 %
-% F  instance of FLOWobj
+% FD instance of FLOWobj
 %
 % Output arguments
 %
-% G  instance of GRIDobj that stores the flow directions in the
+% AF instance of GRIDobj that stores the flow directions in the
 % format used by ESRI ArcGIS.
 %
+% Example
+%
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% ArcFlow = FLOWobj2GRIDobj(FD);
+% imagesc(ArcFlow)
+%
 % 
 % See also: GRIDobj, GRIDobj2geotiff
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
 % Date: 5. October, 2013
 
-
+switch lower(F.type)
+ case {'multi' 'dinf'}
+ error('not possible for multiple flow directions')
+end
 
 G = copy2GRIDobj(F);
 

@FLOWobj/FLOWobj2M.m

@@ -1,6 +1,6 @@
 function M = FLOWobj2M(FD)
 
-% convert instance of FLOWobj to flow direction matrix 
+%FLOWOBJ2M convert instance of FLOWobj to flow direction matrix 
 %
 % Syntax
 %
@@ -11,9 +11,26 @@
 % FLOWobj2M converts an instance of FLOWobj to the flow direction
 % matrix M as used in TopoToolbox 1.
 %
+% Input arguments 
+%
+% FD FLOWobj
+%
+% Output arguments
+%
+% M sparse transfer matrix
+%
+% Example
+%
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% M = FLOWobj2M(FD);
+% [x,y] = getcoordinates(DEM);
+% [x,y] = meshgrid(x,y);
+% gplot(M,[x(:) y(:)]) 
+%
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
-% Date: 23. February, 2013
+% Date: 18. August, 2017
 
 
 nrc = prod(FD.size);

@FLOWobj/FLOWobj2cell.m

@@ -1,6 +1,6 @@
 function [CFD,D,A,cfix] = FLOWobj2cell(FD,IX)
 
-% Return cell array of FLOWobjs for individual drainage basins
+%FLOWOBJ2CELL return cell array of FLOWobjs for individual drainage basins
 %
 % Syntax
 %
@@ -31,6 +31,13 @@
 %
 % Example
 %
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% [CFD,~,a] = FLOWobj2cell(FD);
+% [~,ix] = max(a);
+% A = flowacc(CFD{ix});
+% imageschs(DEM,log(A))
+%
 % See also: FLOWobj, STREAMobj/STREAMobj2cell
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
@@ -49,6 +56,8 @@
  error('a forth output argument is only allowed for two input arguments');
 end
 
+
+
 FDcopy = FD;
 FDcopy.ix = [];
 FDcopy.ixc = [];

@FLOWobj/FLOWobj2gradient.m

@@ -1,6 +1,6 @@
 function G = FLOWobj2gradient(FD,DEM)
 
-% gradient along flow direction
+%FLOWOBJ2GRADIENT gradient along flow direction
 %
 % Syntax 
 %
@@ -14,8 +14,23 @@
 % GRIDobj that contains the gradient along the flow paths.
 %
 % If FLOWobj has been derived using a multiple or Dinf flow direction
-% algorithm, then G is calculated as the weighted mean gradient. 
+% algorithm, then G is calculated as the weighted mean gradient.
 %
+% Input arguments
+%
+% FD FLOWobj
+% DEM digital elevation model (GRIDobj)
+%
+% Output arguments
+%
+% G along-flow gradient
+%
+% Example
+%
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% G = FLOWobj2gradient(FD,DEM);
+% imageschs(DEM,G)
 %
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)

@FLOWobj/dbentropy.m

@@ -1,6 +1,6 @@
 function [OUT,Pc] = dbentropy(FD,ix)
 
-% entropy of drainage basin delineation
+%DBENTROPY entropy of drainage basin delineation
 %
 % Syntax
 %

@FLOWobj/dependencemap.m

@@ -1,7 +1,7 @@
 function OUT = dependencemap(FD,varargin)
 
 
-% upslope area for specific locations in a digital elevation model
+%DEPENDENCEMAP upslope area for specific locations in a DEM
 %
 % Syntax
 %
@@ -11,8 +11,10 @@
 %
 % Description
 %
-% dependencemap returns a logical matrix masking the upslope part
-% of the digital elevation model that drain into the specified cells.
+% dependencemap returns a GRIDobj with true values masking the upslope
+% part of the digital elevation model that contributes to the specified
+% area in the region in L or pixels with the linear index ix or
+% coordinates x,y.
 %
 % Input
 %
@@ -27,11 +29,17 @@
 %
 % Example
 %
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% I = GRIDobj(DEM,'logical');
+% I.Z(300:500,300:500) = true;
+% FD = FLOWobj(DEM,'preprocess','c');
+% D = dependencemap(FD,I);
+% imageschs(DEM,I+D)
 %
 % See also: FLOWobj, FLOWobj/INFLUENCEMAP
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
-% Date: 4. March, 2016
+% Date: 17. August, 2017
 
 
 % 4/3/2016: the function now makes copies of FD.ix and FD.ixc (see 

@FLOWobj/drainagebasins.m

@@ -1,6 +1,6 @@
 function [OUT,varargout] = drainagebasins(FD,varargin)
 
-% drainage basin delineation/catchments
+%DRAINAGEBASINS drainage basin delineation/catchments
 %
 % Syntax
 %

@FLOWobj/drainagebasinstats.m

@@ -1,6 +1,6 @@
 function stats = drainagebasinstats(FD,L,varargin)
 
-% Zonal statistics on drainage basins
+%DRAINAGEBASINSTATS zonal statistics on drainage basins
 % 
 % Syntax
 %
@@ -34,11 +34,20 @@
 %
 % stats structure array with statistics
 %
+% Example: Plot the distribution of mean gradients upstream of channelheads
+%
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% S = STREAMobj(FD,'minarea',1000);
+% ix = streampoi(S,'channelheads','ix');
+% G = gradient8(DEM);
+% stats = drainagebasinstats(FD,ix,'grad',G);
+% histogram([stats.grad_mean])
 %
 % See also: FLOWobj, drainagebasins
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
-% Date: 9. January, 2015
+% Date: 17. August, 2017
 
 % check additional input grids
 narg = numel(varargin);
@@ -68,11 +77,16 @@
  nrlabels = numel(ix);
  l = 1:nrlabels;
 end
-
-h = waitbar(0,'please wait');
+
+wb = nrlabels > 2;
+if wb
+ h = waitbar(0,'please wait');
+end
 
 for r=1:nrlabels;
- waitbar(r/nrlabels,h);
+ if wb
+ waitbar(r/nrlabels,h);
+ end
  switch inp
  case 'GRIDobj'
  I = L==l(r);
@@ -106,16 +120,20 @@
  end
  end
 
- I = dependencemap(FD,I) & ~I;
+ I = dependencemap(FD,I);% & ~I;
 
  % In addition, optionally get outline
  stats(r).Geometry = 'Polygon';
  [~,X,Y] = GRIDobj2polygon(I);
  stats(r).X = X;
  stats(r).Y = Y;
-
- stats(r).label = l(r);
+
+ % Some basic geometric values
+ stats(r).label = double(l(r));
  stats(r).upslopearea = nnz(I.Z)*I.cellsize^2;
+ [xx,yy] = findcoord(I);
+ stats(r).Xcentr = mean(xx);
+ stats(r).Ycentr = mean(yy);
 
  if narg > 0
  for r2 = 1:narg;
@@ -145,15 +163,13 @@
  stats(r).([varargin{(r2-1)*2 +1} '_range']) = maxv-minv;
  stats(r).([varargin{(r2-1)*2 +1} '_kurtosis']) = kurtosis(v);
  stats(r).([varargin{(r2-1)*2 +1} '_skewness']) = skewness(v);
-
-
-
+
 
  end
  end
  end
 end
-
+if wb
 close(h);
-
+end
 

@FLOWobj/find.m

@@ -1,13 +1,30 @@
 function [ix,ixc,frac] = find(FD)
 
-% find indices and values of edges in the flow direction graph
+%FIND find indices and values of edges in the flow direction graph
 %
 % Syntax
 %
 % [ix,ixc] = find(FD); % for single flow direction
 % [ix,ixc,frac] = find(FD); % for multiple flow direction
 %
+% Description
 %
+% FIND returns the linear indices of nodes in the flow network stored
+% in an instance FD of FLOWobj. frac contains the fraction that each
+% cell in ix delivers to its downstream neighbor in ixc. frac is an
+% empty array if FD represents single flow directions.
+%
+% Input arguments
+%
+% FD FLOWobj
+%
+% Output arguments
+%
+% ix giver indices
+% ixc receiver indices
+% frac fraction
+%
+% See also: FLOWobj, FLOWobj2M
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
 % Date: 23. February, 2013

@FLOWobj/flowacc.m

@@ -1,6 +1,6 @@
 function OUT = flowacc(FD,W0,RR)
 
-% flow accumulation (upslope area, contributing area)
+%FLOWACC flow accumulation (upslope area, contributing area)
 %
 % Syntax
 %

@FLOWobj/flowconvergence.m

@@ -1,6 +1,6 @@
 function N = flowconvergence(FD)
 
-% compute flow convergence of a digital elevation model
+%FLOWCONVERGENCE compute flow convergence of a digital elevation model
 % 
 % Syntax
 %
@@ -24,12 +24,15 @@
 %
 % Example
 % 
-% 
+% DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
+% FD = FLOWobj(DEM,'preprocess','c');
+% C = flowconvergence(FD);
+% imageschs(DEM,C)
 %
 % See also: FLOWOBJ
 %
 % Author: Wolfgang Schwanghart (w.schwanghart[at]geo.uni-potsdam.de)
-% Date: 14. November, 2016
+% Date: 18. August, 2017
 
 
 % 4/3/2016: the function now makes copies of FD.ix and FD.ixc (see 

@FLOWobj/flowdistance.m

@@ -1,6 +1,6 @@
 function OUT = flowdistance(FD,varargin) 
 
-% flow distance in upstream and downstream direction
+%FLOWDISTANCE flow distance in upstream and downstream direction
 %
 % Syntax
 %