Changes between Version 75 and Version 76 of WKTRaster/SpecificationWorking03

Timestamp:

05/15/11 16:47:53 (14 years ago)

Author:

dustymugs

Comment:

Added ST_SummaryStats

WKTRaster/SpecificationWorking03

@@ -102 +102 @@
 
 ----
+
+'''ST_SummaryStats(raster, nband) -> record'''[[BR]]
+This is the core function that gets the summary statistics (# of values, mean, standard deviation, minimum value, maximum value) of a specified raster's band.  It is this function that ST_Mean, ST_StdDev and ST_MinMax calls for their appropriate values.
+
+1. ST_SummaryStats(rast raster, nband int, hasnodata boolean) -> record
+
+  returns one record of five columns (count, mean, stddev, min, max)
+
+  nband: index of band
+
+  hasnodata: if FALSE, any pixel who's value is nodata is ignored
+
+{{{
+ST_SummaryStats(rast, 1, FALSE)
+}}}
+
+2. ST_SummaryStats(rast raster, nband int) -> record
+
+  assumes hasnodata = FALSE
+
+{{{
+ST_SummaryStats(rast, 2)
+}}}
+
+3. ST_SummaryStats(rast raster, hasnodata boolean) -> record
+
+  assumes nband = 1
+
+{{{
+ST_SummaryStats(rast, TRUE)
+}}}
+
+4. ST_SummaryStats(rast raster) -> record
+
+  assumes nband = 1 and hasnodata = FALSE
+
+{{{
+ST_SummaryStats(rast)
+}}}
+
+Due to the time it may take to do on-the-fly calculation of summary stats for large rasters (say 10000 x 10000), an alternative that sacrifices accuracy for speed is required.  The following functions sample a percentage of the raster in a methodical randomized manner.  The algorithm used for sampling is...
+
+1. select the larger dimension of the width and height.  compute the number of pixels to sample in each "row" of the larger dimension
+
+2. pick pixels from each "row" of the larger dimension in an incremental rolling manner where each increment is randomly determined.
+
+The set of ST_ApproxSummaryStats functions are:
+
+1. ST_ApproxSummaryStats(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> record
+
+  sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
+
+{{{
+ST_ApproxSummaryStats(rast, 3, FALSE, 0.1)
+
+ST_ApproxSummaryStats(rast, 1, TRUE, 0.5)
+}}}
+
+2. ST_ApproxSummaryStats(rast raster, nband int, sample_percent double precision) -> record
+
+  assumes that nband = 1
+
+{{{
+ST_ApproxSummaryStats(rast, 2 0.01)
+
+ST_ApproxSummaryStats(rast, 4, 0.025)
+}}}
+
+3. ST_ApproxSummaryStats(rast raster, hasnodata boolean, sample_percent double precision) -> record
+
+  assumes that nband = 1
+
+{{{
+ST_ApproxSummaryStats(rast, FALSE, 0.01)
+
+ST_ApproxSummaryStats(rast, TRUE, 0.025)
+}}}
+
+4. ST_ApproxSummaryStats(rast raster, sample_percent double precision) -> record
+
+  assumes that nband = 1 and hasnodata = FALSE
+
+{{{
+ST_ApproxSummaryStats(rast, 0.25)
+}}}
+
+5. ST_ApproxSummaryStats(rast raster) -> record
+
+  assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
+
+{{{
+ST_ApproxSummaryStats(rast)
+}}}
+
+The situation arises where the summary statistics of a coverage table is required.  As the coverage may be large (tens of gigabytes of memory or larger), the following functions are provided to permit an incremental computation of the summary statistics.
+
+1. ST_SummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> record
+
+  rastertable: name of table with raster column
+
+  rastercolumn: name of column of data type raster
+
+{{{
+ST_SummaryStats('tmax_2010', 'rast', 1, FALSE)
+
+ST_SummaryStats('precip_2011', 'rast', 1, TRUE)
+}}}
+
+2. ST_SummaryStats(rastertable text, rastercolumn text, nband int) -> record
+
+    hasnodata = FALSE
+
+{{{
+ST_SummaryStats('tmax_2010', 'rast', 1)
+}}}
+
+3. ST_SummaryStats(rastertable text, rastercolumn text, hasnodata boolean) -> record
+
+    nband = 1
+
+{{{
+ST_SummaryStats('precip_2011', 'rast', TRUE)
+}}}
+
+4. ST_SummaryStats(rastertable text, rastercolumn text) -> record
+
+    nband = 1 and hasnodata = FALSE
+
+{{{
+ST_SummaryStats('tmin_2009', 'rast')
+}}}
+
+Variations for ST_ApproxSummaryStats are:
+
+1. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> record
+
+{{{
+ST_ApproxSummaryStats('tmax_2010', 'rast', 1, FALSE, 0.5)
+
+ST_ApproxSummaryStats('precip_2011', 'rast', 1, TRUE, 0.2)
+}}}
+
+2. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> record
+
+    hasnodata = FALSE
+
+{{{
+ST_ApproxSummaryStats('tmax_2010', 'rast', 1, 0.5)
+
+ST_ApproxSummaryStats('precip_2011', 'rast', 1, 0.2)
+}}}
+
+3. ST_ApproxSummaryStats(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> record
+
+    nband = 1
+
+{{{
+ST_ApproxSummaryStats('tmax_2010', 'rast', FALSE, 0.5)
+
+ST_ApproxSummaryStats('precip_2011', 'rast', TRUE, 0.2)
+}}}
+
+4. ST_ApproxSummaryStats(rastertable text, rastercolumn text, sample_percent double precision) -> record
+
+    nband = 1 and hasnodata = FALSE
+
+{{{
+ST_ApproxSummaryStats('tmax_2010', 'rast', 0.5)
+
+ST_ApproxSummaryStats('precip_2011', 'rast', 0.2)
+}}}
+
+5. ST_ApproxSummaryStats(rastertable text, rastercolumn text) -> record
+
+    nband = 1, hasnodata = FALSE and sample_percent = 0.1
+
+{{{
+ST_ApproxSummaryStats('tmax_2010', 'rast')
+
+ST_ApproxSummaryStats('precip_2011', 'rast')
+}}}
+
+The mean returned in the coverage functions (has rastertable and rastercolumn arguments) is a weighted mean of the means of each raster tile. The standard deviation returned is the cumulative standard deviation of all raster tiles.
+
+----
+
 '''ST_MinMax(raster, nband) -> record'''[[BR]]
-As part of the process to provide complete implementations of ST_AsJPEG and ST_AsPNG, a method is required to reclassify larger numbers unable to be contained in 8BUI (JPEG and PNG) and 16BUI (PNG). For this reclassification function, we need to get the min and max values of a band, thus ST_MinMax.
+As part of the process to provide complete implementations of ST_AsJPEG and ST_AsPNG, a method is required to reclassify larger numbers unable to be contained in 8BUI (JPEG and PNG) and 16BUI (PNG). For this reclassification function, we need to get the min and max values of a band, thus ST_MinMax.  This function calls upon ST_SummaryStats.
 
 1. ST_MinMax(rast raster, nband int, hasnodata boolean) -> record
@@ -141 +327 @@
 }}}
 
-Due to the time it may take to do on-the-fly determination of min/max for large rasters (say 10000 x 10000), an alternative that sacrifices accuracy for speed is required.  The following functions sample a percentage of the raster in a methodical randomized manner.  The algorithm used for sampling is...
-
-1. select the larger dimension of the width and height.  compute the number of pixels to sample in each "row" of the larger dimension
-
-2. pick pixels from each "row" of the larger dimension in an incremental rolling manner where each increment is randomly determined.
-
-The functions are:
+The ST_ApproxMinMax functions are:
 
 1. ST_ApproxMinMax(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> record