[GRASS-SVN] r71501 - grass-addons/grass7/raster/r.hants

[svn_grass at osgeo.org]

Author: veroandreo
Date: 2017-09-24 06:19:07 -0700 (Sun, 24 Sep 2017)
New Revision: 71501

Modified:
   grass-addons/grass7/raster/r.hants/r.hants.html
Log:
r.hants addon: explanations added to manual page

Modified: grass-addons/grass7/raster/r.hants/r.hants.html
===================================================================
--- grass-addons/grass7/raster/r.hants/r.hants.html	2017-09-19 09:35:03 UTC (rev 71500)
+++ grass-addons/grass7/raster/r.hants/r.hants.html	2017-09-24 13:19:07 UTC (rev 71501)
@@ -14,13 +14,13 @@
 analysing one year. If two peaks are assumed per year, the number of 
 frequencies should be at least 5 when analysing one year.
 
-<p>The number of frequencies should also not be too large. With a large 
+<p>The number of frequencies should not be too large, either. With a large 
 number of frequencies, outliers can no longer be identified because the 
-fit is "too good", outliers can be represented by the estimate. 
-The number of frequencies should also be smaller than <em>n input maps / 2</em>
-if missing values should be reconstructed.
+fit is "too good", i.e. outliers can be represented by the 
+estimates of the curve. Moreover, the number of frequencies should be 
+smaller than <em>n input maps / 2</em> if missing values should be 
+reconstructed.
 
-
 <h2>NOTES</h2>
 
 The optional <em>amplitude</em> and <em>phase</em> output maps contain 
@@ -36,22 +36,49 @@
 frequency is the base period, i.e. one peak per base period.
 
 <p>
-If the <em>range</em> option is given, any values which fall outside
-that range will be treated as if they were NULL.
+HANTS operates in time, i.e. it looks at the time series of each cell. 
+To fit a harmonic curve, it requires that the time series of each cell 
+has a minimum amount of valid data. The number of valid observations 
+must always be greater than or equal to the number of parameters that 
+describe the harmonic curve (2 x nf - 1). The user can decide to use 
+more observations than this minimum required. The option <b>dod</b> 
+(degree of over-determination) is the minimum number of "extra" 
+valid observations that should be considered to fit the curve. This 
+parameter is optional, but it is recommended to be set.
+
+<p>
 The <em>range</em> parameter can be set to <em>low,high</em> thresholds:
-values outside of this range are treated as NULL.
+values outside of this range are treated as NULL. The <em>low,high</em> 
+thresholds are floating point, so use <em>-inf</em> or <em>inf</em> for 
+a single threshold (e.g., <em>range=0,inf</em> to ignore negative 
+values, or <em>range=-inf,-200.4</em> to ignore values above -200.4).
 
 <p>
-The <em>low,high</em> thresholds are floating point, so use <em>-inf</em> or
-<em>inf</em> for a single threshold (e.g., <em>range=0,inf</em> to ignore
-negative values, or <em>range=-inf,-200.4</em> to ignore values above -200.4).
+The length of the <em>base_period</em> is by default the number of input 
+maps. If the user wants a base period of one year and the <em>input</em> 
+or <em>file</em> options (note that they are mutually exclusive) provides 
+a list of maps covering one year, then there is no need to set the base 
+period. Besides, if the input maps are equidistant in time, e.g. every 
+8 days, there is no need to set <em>time_steps</em>. However, if the 
+interval is not constant (i.e. masp are not equidistant), the user needs 
+to assign time steps. These must always increase (i.e. each time step 
+must be larger than the previous one) and the total number of time steps 
+must be equal to the number of input maps. 
 
 <p>
+Optionally, low and/or high outliers can be removed by means of the 
+<em>-l</em> and <em>-h</em> flags, respectively. In this case, the 
+parameter <b>fet</b> (fit error tolerance) must be provided. The 
+value of fet is relative to the value range of the variable being 
+considered. For further details on the usage of the option fet, see  
+Roerink et al. (2000).
+
+<p>
 The maximum number of raster maps that can be processed is given by the 
 per-user limit of the operating system. For example, the soft limits 
 for users are typically 1024. The soft limit can be changed with e.g. 
-<tt>ulimit -n 4096</tt> (UNIX-based operating systems) but not higher 
-than the hard limit. If it is too low, you can as superuser add an 
+<tt>ulimit -n 4096</tt> (UNIX-based operating systems) but it cannot be 
+higher than the hard limit. If it is too low, you can as superuser add an 
 entry in
 
 <div class="code"><pre>
@@ -65,23 +92,23 @@
 <div class="code"><pre>
 cat /proc/sys/fs/file-max
 </pre></div>
-which is on modern Linux systems several 100,000 files.
+which on modern Linux systems is several 100,000 files.
 
-
-<p>Use the <em>file</em> option to analyze large amount of raster maps 
+<p>
+Use the <em>file</em> option to analyze large amount of raster maps 
 without hitting open files limit and the size limit of command line 
-arguments. The computation is slower than the <em>input</em> option 
+arguments. The computation is slower than with the <em>input</em> option 
 method. For every single row in the output map(s) all input maps are 
-opened and closed. The amount of RAM will rise linear with the number of 
+opened and closed. The amount of RAM will rise linearly with the number of 
 specified input maps. The input and file options are mutually exclusive.
-Input is a text file with a new line separated list of raster map names.
+The option <em>input</em> is a comma separated list of raster map names 
+and the option <em>file</em> is a text file with a new line separated 
+list of raster map names. Note that the order of maps in one option or 
+the other is very important.
 
-<p>For the usage of the option <b>fet</b> see Roerink et al. (2000). Its
-value is relative to the value range of the variable being considered.
-
 <h2>EXAMPLES</h2>
 
-<h3>Precipitation data example</h3>
+<h3>Average temperature data example</h3>
 This small example is based on a climatic dataset for North Carolina which
 was from publicly available data (monthly temperature averages and monthly
 precipitation sums from 2000 to 2012, downloadable as
@@ -110,8 +137,7 @@
 # generate and check list of input maps (the order matters!)
 g.list type=raster pattern="20??_??_tempmean" output=tempmean.csv
 
-r.hants file=tempmean.csv \
-  nf=6 fet=0.1 dod=5 delta=0.1 base_period=12
+r.hants file=tempmean.csv nf=6 dod=5 delta=0.1 base_period=12
 
 # assign reasonable color tables for temperature
 for map in `g.list type=raster pattern="*tempmean_hants"` ; do