# Changes between Version 80 and Version 81 of WKTRaster/SpecificationWorking03

Show
Ignore:
Timestamp:
05/16/11 11:54:53 (2 years ago)
Comment:

Move statistics functions to FV.16

Unmodified
Removed
Modified
• ## WKTRaster/SpecificationWorking03

v80 v81
100100
101101''' Open Question: ''' Should the function fail if an index is invalid?  How should this work when providing more than one indices to the function?
102
103 ----
104
105 '''ST_SummaryStats(raster, nband) -> record'''[[BR]]
106 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.
107
108 1. ST_SummaryStats(rast raster, nband int, hasnodata boolean) -> record
109
110   returns one record of five columns (count, mean, stddev, min, max)
111
112   nband: index of band
113
114   hasnodata: if FALSE, any pixel who's value is nodata is ignored
115
116 {{{
117 ST_SummaryStats(rast, 1, FALSE)
118 }}}
119
120 2. ST_SummaryStats(rast raster, nband int) -> record
121
122   assumes hasnodata = FALSE
123
124 {{{
125 ST_SummaryStats(rast, 2)
126 }}}
127
128 3. ST_SummaryStats(rast raster, hasnodata boolean) -> record
129
130   assumes nband = 1
131
132 {{{
133 ST_SummaryStats(rast, TRUE)
134 }}}
135
136 4. ST_SummaryStats(rast raster) -> record
137
138   assumes nband = 1 and hasnodata = FALSE
139
140 {{{
141 ST_SummaryStats(rast)
142 }}}
143
144 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...
145
146 1. select the larger dimension of the width and height.  compute the number of pixels to sample in each "row" of the larger dimension
147
148 2. pick pixels from each "row" of the larger dimension in an incremental rolling manner where each increment is randomly determined.
149
150 The set of ST_ApproxSummaryStats functions are:
151
152 1. ST_ApproxSummaryStats(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> record
153
154   sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
155
156 {{{
157 ST_ApproxSummaryStats(rast, 3, FALSE, 0.1)
158
159 ST_ApproxSummaryStats(rast, 1, TRUE, 0.5)
160 }}}
161
162 2. ST_ApproxSummaryStats(rast raster, nband int, sample_percent double precision) -> record
163
164   assumes that nband = 1
165
166 {{{
167 ST_ApproxSummaryStats(rast, 2 0.01)
168
169 ST_ApproxSummaryStats(rast, 4, 0.025)
170 }}}
171
172 3. ST_ApproxSummaryStats(rast raster, hasnodata boolean, sample_percent double precision) -> record
173
174   assumes that nband = 1
175
176 {{{
177 ST_ApproxSummaryStats(rast, FALSE, 0.01)
178
179 ST_ApproxSummaryStats(rast, TRUE, 0.025)
180 }}}
181
182 4. ST_ApproxSummaryStats(rast raster, sample_percent double precision) -> record
183
184   assumes that nband = 1 and hasnodata = FALSE
185
186 {{{
187 ST_ApproxSummaryStats(rast, 0.25)
188 }}}
189
190 5. ST_ApproxSummaryStats(rast raster) -> record
191
192   assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
193
194 {{{
195 ST_ApproxSummaryStats(rast)
196 }}}
197
198 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.
199
200 1. ST_SummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> record
201
202   rastertable: name of table with raster column
203
204   rastercolumn: name of column of data type raster
205
206 {{{
207 ST_SummaryStats('tmax_2010', 'rast', 1, FALSE)
208
209 ST_SummaryStats('precip_2011', 'rast', 1, TRUE)
210 }}}
211
212 2. ST_SummaryStats(rastertable text, rastercolumn text, nband int) -> record
213
214     hasnodata = FALSE
215
216 {{{
217 ST_SummaryStats('tmax_2010', 'rast', 1)
218 }}}
219
220 3. ST_SummaryStats(rastertable text, rastercolumn text, hasnodata boolean) -> record
221
222     nband = 1
223
224 {{{
225 ST_SummaryStats('precip_2011', 'rast', TRUE)
226 }}}
227
228 4. ST_SummaryStats(rastertable text, rastercolumn text) -> record
229
230     nband = 1 and hasnodata = FALSE
231
232 {{{
233 ST_SummaryStats('tmin_2009', 'rast')
234 }}}
235
236 Variations for ST_ApproxSummaryStats are:
237
238 1. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> record
239
240 {{{
241 ST_ApproxSummaryStats('tmax_2010', 'rast', 1, FALSE, 0.5)
242
243 ST_ApproxSummaryStats('precip_2011', 'rast', 1, TRUE, 0.2)
244 }}}
245
246 2. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> record
247
248     hasnodata = FALSE
249
250 {{{
251 ST_ApproxSummaryStats('tmax_2010', 'rast', 1, 0.5)
252
253 ST_ApproxSummaryStats('precip_2011', 'rast', 1, 0.2)
254 }}}
255
256 3. ST_ApproxSummaryStats(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> record
257
258     nband = 1
259
260 {{{
261 ST_ApproxSummaryStats('tmax_2010', 'rast', FALSE, 0.5)
262
263 ST_ApproxSummaryStats('precip_2011', 'rast', TRUE, 0.2)
264 }}}
265
266 4. ST_ApproxSummaryStats(rastertable text, rastercolumn text, sample_percent double precision) -> record
267
268     nband = 1 and hasnodata = FALSE
269
270 {{{
271 ST_ApproxSummaryStats('tmax_2010', 'rast', 0.5)
272
273 ST_ApproxSummaryStats('precip_2011', 'rast', 0.2)
274 }}}
275
276 5. ST_ApproxSummaryStats(rastertable text, rastercolumn text) -> record
277
278     nband = 1, hasnodata = FALSE and sample_percent = 0.1
279
280 {{{
281 ST_ApproxSummaryStats('tmax_2010', 'rast')
282
283 ST_ApproxSummaryStats('precip_2011', 'rast')
284 }}}
285
286 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.
287
288 ----
289
290 '''ST_Mean(raster, nband) -> double precision'''[[BR]]
291 This function calls ST_SummaryStats and only returns the mean from that function.
292
293 1. ST_Mean(rast raster, nband int, hasnodata boolean) -> double precision
294
295   returns the mean as a double precision
296
297   nband: index of band
298
299   hasnodata: if FALSE, any pixel who's value is nodata is ignored
300
301 {{{
302 ST_Mean(rast, 1, FALSE)
303 }}}
304
305 2. ST_Mean(rast raster, nband int) -> double precision
306
307   assumes hasnodata = FALSE
308
309 {{{
310 ST_Mean(rast, 2)
311 }}}
312
313 3. ST_Mean(rast raster, hasnodata boolean) -> double precision
314
315   assumes nband = 1
316
317 {{{
318 ST_Mean(rast, TRUE)
319 }}}
320
321 4. ST_Mean(rast raster) -> double precision
322
323   assumes nband = 1 and hasnodata = FALSE
324
325 {{{
326 ST_Mean(rast)
327 }}}
328
329 The set of ST_ApproxMean functions are:
330
331 1. ST_ApproxMean(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> double precision
332
333   sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
334
335 {{{
336 ST_ApproxMean(rast, 3, FALSE, 0.1)
337
338 ST_ApproxMean(rast, 1, TRUE, 0.5)
339 }}}
340
341 2. ST_ApproxMean(rast raster, nband int, sample_percent double precision) -> double precision
342
343   assumes that nband = 1
344
345 {{{
346 ST_ApproxMean(rast, 2 0.01)
347
348 ST_ApproxMean(rast, 4, 0.025)
349 }}}
350
351 3. ST_ApproxMean(rast raster, hasnodata boolean, sample_percent double precision) -> double precision
352
353   assumes that nband = 1
354
355 {{{
356 ST_ApproxMean(rast, FALSE, 0.01)
357
358 ST_ApproxMean(rast, TRUE, 0.025)
359 }}}
360
361 4. ST_ApproxMean(rast raster, sample_percent double precision) -> double precision
362
363   assumes that nband = 1 and hasnodata = FALSE
364
365 {{{
366 ST_ApproxMean(rast, 0.25)
367 }}}
368
369 5. ST_ApproxMean(rast raster) -> double precision
370
371   assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
372
373 {{{
374 ST_ApproxMean(rast)
375 }}}
376
377 The following functions are provided for coverage tables.
378
379 1. ST_Mean(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> double precision
380
381   rastertable: name of table with raster column
382
383   rastercolumn: name of column of data type raster
384
385 {{{
386 ST_Mean('tmax_2010', 'rast', 1, FALSE)
387
388 ST_Mean('precip_2011', 'rast', 1, TRUE)
389 }}}
390
391 2. ST_Mean(rastertable text, rastercolumn text, nband int) -> double precision
392
393     hasnodata = FALSE
394
395 {{{
396 ST_Mean('tmax_2010', 'rast', 1)
397 }}}
398
399 3. ST_Mean(rastertable text, rastercolumn text, hasnodata boolean) -> double precision
400
401     nband = 1
402
403 {{{
404 ST_Mean('precip_2011', 'rast', TRUE)
405 }}}
406
407 4. ST_Mean(rastertable text, rastercolumn text) -> double precision
408
409     nband = 1 and hasnodata = FALSE
410
411 {{{
412 ST_Mean('tmin_2009', 'rast')
413 }}}
414
415 Variations for ST_ApproxMean are:
416
417 1. ST_ApproxMean(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> double precision
418
419 {{{
420 ST_ApproxMean('tmax_2010', 'rast', 1, FALSE, 0.5)
421
422 ST_ApproxMean('precip_2011', 'rast', 1, TRUE, 0.2)
423 }}}
424
425 2. ST_ApproxMean(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> double precision
426
427     hasnodata = FALSE
428
429 {{{
430 ST_ApproxMean('tmax_2010', 'rast', 1, 0.5)
431
432 ST_ApproxMean('precip_2011', 'rast', 1, 0.2)
433 }}}
434
435 3. ST_ApproxMean(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> double precision
436
437     nband = 1
438
439 {{{
440 ST_ApproxMean('tmax_2010', 'rast', FALSE, 0.5)
441
442 ST_ApproxMean('precip_2011', 'rast', TRUE, 0.2)
443 }}}
444
445 4. ST_ApproxMean(rastertable text, rastercolumn text, sample_percent double precision) -> double precision
446
447     nband = 1 and hasnodata = FALSE
448
449 {{{
450 ST_ApproxMean('tmax_2010', 'rast', 0.5)
451
452 ST_ApproxMean('precip_2011', 'rast', 0.2)
453 }}}
454
455 5. ST_ApproxMean(rastertable text, rastercolumn text) -> double precision
456
457     nband = 1, hasnodata = FALSE and sample_percent = 0.1
458
459 {{{
460 ST_ApproxMean('tmax_2010', 'rast')
461
462 ST_ApproxMean('precip_2011', 'rast')
463 }}}
464
465 The mean returned in the coverage functions (has rastertable and rastercolumn arguments) is a weighted mean of the means of each raster tile.
466
467 ----
468
469 '''ST_StdDev(raster, nband) -> double precision'''[[BR]]
470 This function calls ST_SummaryStats and only returns the standard deviation from that function.
471
472 1. ST_StdDev(rast raster, nband int, hasnodata boolean) -> double precision
473
474   returns the standard deviation as a double precision
475
476   nband: index of band
477
478   hasnodata: if FALSE, any pixel who's value is nodata is ignored
479
480 {{{
481 ST_StdDev(rast, 1, FALSE)
482 }}}
483
484 2. ST_StdDev(rast raster, nband int) -> double precision
485
486   assumes hasnodata = FALSE
487
488 {{{
489 ST_StdDev(rast, 2)
490 }}}
491
492 3. ST_StdDev(rast raster, hasnodata boolean) -> double precision
493
494   assumes nband = 1
495
496 {{{
497 ST_StdDev(rast, TRUE)
498 }}}
499
500 4. ST_StdDev(rast raster) -> double precision
501
502   assumes nband = 1 and hasnodata = FALSE
503
504 {{{
505 ST_StdDev(rast)
506 }}}
507
508 The set of ST_ApproxStdDev functions are:
509
510 1. ST_ApproxStdDev(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> double precision
511
512   sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
513
514 {{{
515 ST_ApproxStdDev(rast, 3, FALSE, 0.1)
516
517 ST_ApproxStdDev(rast, 1, TRUE, 0.5)
518 }}}
519
520 2. ST_ApproxStdDev(rast raster, nband int, sample_percent double precision) -> double precision
521
522   assumes that nband = 1
523
524 {{{
525 ST_ApproxStdDev(rast, 2 0.01)
526
527 ST_ApproxStdDev(rast, 4, 0.025)
528 }}}
529
530 3. ST_ApproxStdDev(rast raster, hasnodata boolean, sample_percent double precision) -> double precision
531
532   assumes that nband = 1
533
534 {{{
535 ST_ApproxStdDev(rast, FALSE, 0.01)
536
537 ST_ApproxStdDev(rast, TRUE, 0.025)
538 }}}
539
540 4. ST_ApproxStdDev(rast raster, sample_percent double precision) -> double precision
541
542   assumes that nband = 1 and hasnodata = FALSE
543
544 {{{
545 ST_ApproxStdDev(rast, 0.25)
546 }}}
547
548 5. ST_ApproxStdDev(rast raster) -> double precision
549
550   assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
551
552 {{{
553 ST_ApproxStdDev(rast)
554 }}}
555
556 The following functions are provided for coverage tables.
557
558 1. ST_StdDev(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> double precision
559
560   rastertable: name of table with raster column
561
562   rastercolumn: name of column of data type raster
563
564 {{{
565 ST_StdDev('tmax_2010', 'rast', 1, FALSE)
566
567 ST_StdDev('precip_2011', 'rast', 1, TRUE)
568 }}}
569
570 2. ST_StdDev(rastertable text, rastercolumn text, nband int) -> double precision
571
572     hasnodata = FALSE
573
574 {{{
575 ST_StdDev('tmax_2010', 'rast', 1)
576 }}}
577
578 3. ST_StdDev(rastertable text, rastercolumn text, hasnodata boolean) -> double precision
579
580     nband = 1
581
582 {{{
583 ST_StdDev('precip_2011', 'rast', TRUE)
584 }}}
585
586 4. ST_StdDev(rastertable text, rastercolumn text) -> double precision
587
588     nband = 1 and hasnodata = FALSE
589
590 {{{
591 ST_StdDev('tmin_2009', 'rast')
592 }}}
593
594 Variations for ST_ApproxStdDev are:
595
596 1. ST_ApproxStdDev(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> double precision
597
598 {{{
599 ST_ApproxStdDev('tmax_2010', 'rast', 1, FALSE, 0.5)
600
601 ST_ApproxStdDev('precip_2011', 'rast', 1, TRUE, 0.2)
602 }}}
603
604 2. ST_ApproxStdDev(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> double precision
605
606     hasnodata = FALSE
607
608 {{{
609 ST_ApproxStdDev('tmax_2010', 'rast', 1, 0.5)
610
611 ST_ApproxStdDev('precip_2011', 'rast', 1, 0.2)
612 }}}
613
614 3. ST_ApproxStdDev(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> double precision
615
616     nband = 1
617
618 {{{
619 ST_ApproxStdDev('tmax_2010', 'rast', FALSE, 0.5)
620
621 ST_ApproxStdDev('precip_2011', 'rast', TRUE, 0.2)
622 }}}
623
624 4. ST_ApproxStdDev(rastertable text, rastercolumn text, sample_percent double precision) -> double precision
625
626     nband = 1 and hasnodata = FALSE
627
628 {{{
629 ST_ApproxStdDev('tmax_2010', 'rast', 0.5)
630
631 ST_ApproxStdDev('precip_2011', 'rast', 0.2)
632 }}}
633
634 5. ST_ApproxStdDev(rastertable text, rastercolumn text) -> double precision
635
636     nband = 1, hasnodata = FALSE and sample_percent = 0.1
637
638 {{{
639 ST_ApproxStdDev('tmax_2010', 'rast')
640
641 ST_ApproxStdDev('precip_2011', 'rast')
642 }}}
643
644 The standard deviation returned in the coverage functions (has rastertable and rastercolumn arguments) is the cumulative standard deviation of all raster tiles.
645
646 ----
647
648 '''ST_MinMax(raster, nband) -> record'''[[BR]]
649 This function calls ST_SummaryStats and only returns the min and max values from that function.
650
651 1. ST_MinMax(rast raster, nband int, hasnodata boolean) -> record
652
653   returns the record (min double precision, max double precision)
654
655   nband: index of band
656
657   hasnodata: if FALSE, any pixel who's value is nodata is ignored
658
659 {{{
660 ST_MinMax(rast, 1, FALSE)
661 }}}
662
663 2. ST_MinMax(rast raster, nband int) -> record
664
665   assumes hasnodata = FALSE
666
667 {{{
668 ST_MinMax(rast, 2)
669 }}}
670
671 3. ST_MinMax(rast raster, hasnodata boolean) -> record
672
673   assumes nband = 1
674
675 {{{
676 ST_MinMax(rast, TRUE)
677 }}}
678
679 4. ST_MinMax(rast raster) -> record
680
681   assumes nband = 1 and hasnodata = FALSE
682
683 {{{
684 ST_MinMax(rast)
685 }}}
686
687 The set of ST_ApproxMinMax functions are:
688
689 1. ST_ApproxMinMax(rast raster, nband int, hasnodata boolean, sample_percent record) -> record
690
691   sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
692
693 {{{
694 ST_ApproxMinMax(rast, 3, FALSE, 0.1)
695
696 ST_ApproxMinMax(rast, 1, TRUE, 0.5)
697 }}}
698
699 2. ST_ApproxMinMax(rast raster, nband int, sample_percent double precision) -> record
700
701   assumes that nband = 1
702
703 {{{
704 ST_ApproxMinMax(rast, 2 0.01)
705
706 ST_ApproxMinMax(rast, 4, 0.025)
707 }}}
708
709 3. ST_ApproxMinMax(rast raster, hasnodata boolean, sample_percent double precision) -> record
710
711   assumes that nband = 1
712
713 {{{
714 ST_ApproxMinMax(rast, FALSE, 0.01)
715
716 ST_ApproxMinMax(rast, TRUE, 0.025)
717 }}}
718
719 4. ST_ApproxMinMax(rast raster, sample_percent double precision) -> record
720
721   assumes that nband = 1 and hasnodata = FALSE
722
723 {{{
724 ST_ApproxMinMax(rast, 0.25)
725 }}}
726
727 5. ST_ApproxMinMax(rast raster) -> record
728
729   assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
730
731 {{{
732 ST_ApproxMinMax(rast)
733 }}}
734
735 The following functions are provided for coverage tables.
736
737 1. ST_MinMax(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> record
738
739   rastertable: name of table with raster column
740
741   rastercolumn: name of column of data type raster
742
743 {{{
744 ST_MinMax('tmax_2010', 'rast', 1, FALSE)
745
746 ST_MinMax('precip_2011', 'rast', 1, TRUE)
747 }}}
748
749 2. ST_MinMax(rastertable text, rastercolumn text, nband int) -> record
750
751     hasnodata = FALSE
752
753 {{{
754 ST_MinMax('tmax_2010', 'rast', 1)
755 }}}
756
757 3. ST_MinMax(rastertable text, rastercolumn text, hasnodata boolean) -> record
758
759     nband = 1
760
761 {{{
762 ST_MinMax('precip_2011', 'rast', TRUE)
763 }}}
764
765 4. ST_MinMax(rastertable text, rastercolumn text) -> record
766
767     nband = 1 and hasnodata = FALSE
768
769 {{{
770 ST_MinMax('tmin_2009', 'rast')
771 }}}
772
773 Variations for ST_ApproxMinMax are:
774
775 1. ST_ApproxMinMax(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> record
776
777 {{{
778 ST_ApproxMinMax('tmax_2010', 'rast', 1, FALSE, 0.5)
779
780 ST_ApproxMinMax('precip_2011', 'rast', 1, TRUE, 0.2)
781 }}}
782
783 2. ST_ApproxMinMax(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> record
784
785     hasnodata = FALSE
786
787 {{{
788 ST_ApproxMinMax('tmax_2010', 'rast', 1, 0.5)
789
790 ST_ApproxMinMax('precip_2011', 'rast', 1, 0.2)
791 }}}
792
793 3. ST_ApproxMinMax(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> record
794
795     nband = 1
796
797 {{{
798 ST_ApproxMinMax('tmax_2010', 'rast', FALSE, 0.5)
799
800 ST_ApproxMinMax('precip_2011', 'rast', TRUE, 0.2)
801 }}}
802
803 4. ST_ApproxMinMax(rastertable text, rastercolumn text, sample_percent double precision) -> record
804
805     nband = 1 and hasnodata = FALSE
806
807 {{{
808 ST_ApproxMinMax('tmax_2010', 'rast', 0.5)
809
810 ST_ApproxMinMax('precip_2011', 'rast', 0.2)
811 }}}
812
813 5. ST_ApproxMinMax(rastertable text, rastercolumn text) -> record
814
815     nband = 1, hasnodata = FALSE and sample_percent = 0.1
816
817 {{{
818 ST_ApproxMinMax('tmax_2010', 'rast')
819
820 ST_ApproxMinMax('precip_2011', 'rast')
821 }}}
822
823 ----
824
825 '''ST_Histogram(raster, nband) -> set of records'''[[BR]]
826 ST_Histogram and ST_ApproxHistogram provide methods to determine a raster's data distribution.
827
828 The return of ST_Histogram and ST_ApproxHistogram is a set of records where each record is (min, max, count, proportion).
829
830 ST_Histogram has the following variations.
831
832 1. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, width double precision[], right boolean) -> set of records
833
834   returns set of records of four columns (min, max, count, proportion)
835
836   nband: index of band to process on
837
838   hasnodata: if FALSE, any pixel who's value is nodata is ignored.
839
840   bins: the number of categories/bins to have in the histogram. If NULL or value less than one, the number of categories will be auto-computed using Sturges' formula if the number of values >= 30 or Square-root choice if number of values < 30.
841
842     http://en.wikipedia.org/wiki/Histogram#Mathematical_definition
843
844   width: an array indicating the width of each category/bin. If the number of bins is greater than the number of widths, the widths are repeated. Example: 9 bins, widths are [a, b, c] will have the output be [a, b, c, a, b, c, a, b, c].
845
846   right: compute the histogram from the right rather than from the left (default). This changes the criteria for evaluating a value x from [a, b) to (a, b].
847
848 {{{
849 ST_Histogram(rast, 2, FALSE, NULL, NULL, FALSE)
850
851 ST_Histogram(rast, 1, TRUE, 100, NULL, FALSE)
852
853 ST_Histogram(rast, 2, FALSE, NULL, ARRAY[100, 50], FALSE)
854
855 ST_Histogram(rast, 2, FALSE, 9, ARRAY[1000], TRUE)
856
857 ST_Histogram(rast, 2, FALSE, 20, ARRAY[100, 200, 300], TRUE)
858 }}}
859
860 2. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, right boolean) -> set of records
861
862   parameter "width" is not specified thus resulting in all bins having the same widths
863
864 {{{
865 ST_Histogram(rast, 2, FALSE, 5, FALSE)
866 }}}
867
868 3. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int) -> set of records
869
870   the parameter "right" is removed and assumed to be FALSE
871
872 {{{
873 ST_Histogram(rast, 2, FALSE, 5)
874 }}}
875
876 4. ST_Histogram(rast raster, nband int, hasnodata boolean) -> set of records
877
878   the parameter "bins" is removed and set to NULL.  The function will compute the number of bins to use
879
880 5. ST_Histogram(rast raster, nband int) -> set of records
881
882   parameter "hasnodata" is removed and assumed to be FALSE
883
884 6. ST_Histogram(rast raster) -> set of records
885
886   assumes that nband is 1.
887
888 7. ST_Histogram(rast raster, nband int, bins int, width double precision[], right boolean) -> set of records
889
890   hasnodata is assumed to be FALSE
891
892 8. ST_Histogram(rast raster, nband int, bins int, right boolean) -> set of records
893
894   all bins will have equal widths
895
896 9. ST_Histogram(rast raster, nband int, bins int) -> set of records
897
898   right is assumed to be FALSE
899
900 ST_ApproxHistogram should have the following variations.
901
902 1. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int, width double precision[], right boolean) -> set of record
903
904     sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider when generating the histogram.
905
906 {{{
907 ST_Histogram(rast, 2, FALSE, 0.1, NULL, NULL, FALSE)
908
909 ST_Histogram(rast, 1, TRUE, 1, 100, NULL, FALSE)
910
911 ST_Histogram(rast, 2, FALSE, 0.2, NULL, ARRAY[100, 50], FALSE)
912
913 ST_Histogram(rast, 2, FALSE, 0.25, 9, ARRAY[1000], TRUE)
914
915 ST_Histogram(rast, 2, FALSE, 0.05, 20, ARRAY[100, 200, 300], TRUE)
916 }}}
917
918 2. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int, right boolean) -> set of records
919
920   parameter "width" is not specified thus resulting in all bins having the same widths
921
922 3. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int) -> set of records
923
924   the parameter "right" is removed and assumed to be FALSE
925
926 {{{
927 ST_ApproxHistogram(rast, 2, FALSE, 5)
928 }}}
929
930 4. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> set of records
931
932   the parameter "bins" is removed and set to NULL so that function can compute the number of bins to use
933
934 5. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision) -> set of records
935
936   parameter "hasnodata" is removed and assumed to be FALSE
937
938 6. ST_ApproxHistogram(rast raster, nband int) -> set of records
939
940   assumes that sample_percent is 0.1
941
942 7. ST_ApproxHistogram(rast raster, sample_percent double_precision) -> set of records
943
944   assumes that nband is 1
945
946 8. ST_ApproxHistogram(rast raster) -> set of records
947
948   assumes that nband is 1 and sample_percent is 0.1
949
950 9. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int, width double precision[], right boolean) -> set of records
951
952   hasnodata is assumed to be FALSE
953
954 10. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int, right boolean) -> set of records
955
956   all bins will have equal widths
957
958 11. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int) -> set of records
959
960   right is assumed to be FALSE
961102
962103----

18811022
18821023----
1024
1025'''ST_SummaryStats(raster, nband) -> record'''[[BR]]
1026This 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.
1027
10281. ST_SummaryStats(rast raster, nband int, hasnodata boolean) -> record
1029
1030  returns one record of five columns (count, mean, stddev, min, max)
1031
1032  nband: index of band
1033
1034  hasnodata: if FALSE, any pixel who's value is nodata is ignored
1035
1036{{{
1037ST_SummaryStats(rast, 1, FALSE)
1038}}}
1039
10402. ST_SummaryStats(rast raster, nband int) -> record
1041
1042  assumes hasnodata = FALSE
1043
1044{{{
1045ST_SummaryStats(rast, 2)
1046}}}
1047
10483. ST_SummaryStats(rast raster, hasnodata boolean) -> record
1049
1050  assumes nband = 1
1051
1052{{{
1053ST_SummaryStats(rast, TRUE)
1054}}}
1055
10564. ST_SummaryStats(rast raster) -> record
1057
1058  assumes nband = 1 and hasnodata = FALSE
1059
1060{{{
1061ST_SummaryStats(rast)
1062}}}
1063
1064Due 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...
1065
10661. select the larger dimension of the width and height.  compute the number of pixels to sample in each "row" of the larger dimension
1067
10682. pick pixels from each "row" of the larger dimension in an incremental rolling manner where each increment is randomly determined.
1069
1070The set of ST_ApproxSummaryStats functions are:
1071
10721. ST_ApproxSummaryStats(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> record
1073
1074  sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
1075
1076{{{
1077ST_ApproxSummaryStats(rast, 3, FALSE, 0.1)
1078
1079ST_ApproxSummaryStats(rast, 1, TRUE, 0.5)
1080}}}
1081
10822. ST_ApproxSummaryStats(rast raster, nband int, sample_percent double precision) -> record
1083
1084  assumes that nband = 1
1085
1086{{{
1087ST_ApproxSummaryStats(rast, 2 0.01)
1088
1089ST_ApproxSummaryStats(rast, 4, 0.025)
1090}}}
1091
10923. ST_ApproxSummaryStats(rast raster, hasnodata boolean, sample_percent double precision) -> record
1093
1094  assumes that nband = 1
1095
1096{{{
1097ST_ApproxSummaryStats(rast, FALSE, 0.01)
1098
1099ST_ApproxSummaryStats(rast, TRUE, 0.025)
1100}}}
1101
11024. ST_ApproxSummaryStats(rast raster, sample_percent double precision) -> record
1103
1104  assumes that nband = 1 and hasnodata = FALSE
1105
1106{{{
1107ST_ApproxSummaryStats(rast, 0.25)
1108}}}
1109
11105. ST_ApproxSummaryStats(rast raster) -> record
1111
1112  assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
1113
1114{{{
1115ST_ApproxSummaryStats(rast)
1116}}}
1117
1118The 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.
1119
11201. ST_SummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> record
1121
1122  rastertable: name of table with raster column
1123
1124  rastercolumn: name of column of data type raster
1125
1126{{{
1127ST_SummaryStats('tmax_2010', 'rast', 1, FALSE)
1128
1129ST_SummaryStats('precip_2011', 'rast', 1, TRUE)
1130}}}
1131
11322. ST_SummaryStats(rastertable text, rastercolumn text, nband int) -> record
1133
1134    hasnodata = FALSE
1135
1136{{{
1137ST_SummaryStats('tmax_2010', 'rast', 1)
1138}}}
1139
11403. ST_SummaryStats(rastertable text, rastercolumn text, hasnodata boolean) -> record
1141
1142    nband = 1
1143
1144{{{
1145ST_SummaryStats('precip_2011', 'rast', TRUE)
1146}}}
1147
11484. ST_SummaryStats(rastertable text, rastercolumn text) -> record
1149
1150    nband = 1 and hasnodata = FALSE
1151
1152{{{
1153ST_SummaryStats('tmin_2009', 'rast')
1154}}}
1155
1156Variations for ST_ApproxSummaryStats are:
1157
11581. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> record
1159
1160{{{
1161ST_ApproxSummaryStats('tmax_2010', 'rast', 1, FALSE, 0.5)
1162
1163ST_ApproxSummaryStats('precip_2011', 'rast', 1, TRUE, 0.2)
1164}}}
1165
11662. ST_ApproxSummaryStats(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> record
1167
1168    hasnodata = FALSE
1169
1170{{{
1171ST_ApproxSummaryStats('tmax_2010', 'rast', 1, 0.5)
1172
1173ST_ApproxSummaryStats('precip_2011', 'rast', 1, 0.2)
1174}}}
1175
11763. ST_ApproxSummaryStats(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> record
1177
1178    nband = 1
1179
1180{{{
1181ST_ApproxSummaryStats('tmax_2010', 'rast', FALSE, 0.5)
1182
1183ST_ApproxSummaryStats('precip_2011', 'rast', TRUE, 0.2)
1184}}}
1185
11864. ST_ApproxSummaryStats(rastertable text, rastercolumn text, sample_percent double precision) -> record
1187
1188    nband = 1 and hasnodata = FALSE
1189
1190{{{
1191ST_ApproxSummaryStats('tmax_2010', 'rast', 0.5)
1192
1193ST_ApproxSummaryStats('precip_2011', 'rast', 0.2)
1194}}}
1195
11965. ST_ApproxSummaryStats(rastertable text, rastercolumn text) -> record
1197
1198    nband = 1, hasnodata = FALSE and sample_percent = 0.1
1199
1200{{{
1201ST_ApproxSummaryStats('tmax_2010', 'rast')
1202
1203ST_ApproxSummaryStats('precip_2011', 'rast')
1204}}}
1205
1206The 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.
1207
1208----
1209
1210'''ST_Mean(raster, nband) -> double precision'''[[BR]]
1211This function calls ST_SummaryStats and only returns the mean from that function.
1212
12131. ST_Mean(rast raster, nband int, hasnodata boolean) -> double precision
1214
1215  returns the mean as a double precision
1216
1217  nband: index of band
1218
1219  hasnodata: if FALSE, any pixel who's value is nodata is ignored
1220
1221{{{
1222ST_Mean(rast, 1, FALSE)
1223}}}
1224
12252. ST_Mean(rast raster, nband int) -> double precision
1226
1227  assumes hasnodata = FALSE
1228
1229{{{
1230ST_Mean(rast, 2)
1231}}}
1232
12333. ST_Mean(rast raster, hasnodata boolean) -> double precision
1234
1235  assumes nband = 1
1236
1237{{{
1238ST_Mean(rast, TRUE)
1239}}}
1240
12414. ST_Mean(rast raster) -> double precision
1242
1243  assumes nband = 1 and hasnodata = FALSE
1244
1245{{{
1246ST_Mean(rast)
1247}}}
1248
1249The set of ST_ApproxMean functions are:
1250
12511. ST_ApproxMean(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> double precision
1252
1253  sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
1254
1255{{{
1256ST_ApproxMean(rast, 3, FALSE, 0.1)
1257
1258ST_ApproxMean(rast, 1, TRUE, 0.5)
1259}}}
1260
12612. ST_ApproxMean(rast raster, nband int, sample_percent double precision) -> double precision
1262
1263  assumes that nband = 1
1264
1265{{{
1266ST_ApproxMean(rast, 2 0.01)
1267
1268ST_ApproxMean(rast, 4, 0.025)
1269}}}
1270
12713. ST_ApproxMean(rast raster, hasnodata boolean, sample_percent double precision) -> double precision
1272
1273  assumes that nband = 1
1274
1275{{{
1276ST_ApproxMean(rast, FALSE, 0.01)
1277
1278ST_ApproxMean(rast, TRUE, 0.025)
1279}}}
1280
12814. ST_ApproxMean(rast raster, sample_percent double precision) -> double precision
1282
1283  assumes that nband = 1 and hasnodata = FALSE
1284
1285{{{
1286ST_ApproxMean(rast, 0.25)
1287}}}
1288
12895. ST_ApproxMean(rast raster) -> double precision
1290
1291  assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
1292
1293{{{
1294ST_ApproxMean(rast)
1295}}}
1296
1297The following functions are provided for coverage tables.
1298
12991. ST_Mean(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> double precision
1300
1301  rastertable: name of table with raster column
1302
1303  rastercolumn: name of column of data type raster
1304
1305{{{
1306ST_Mean('tmax_2010', 'rast', 1, FALSE)
1307
1308ST_Mean('precip_2011', 'rast', 1, TRUE)
1309}}}
1310
13112. ST_Mean(rastertable text, rastercolumn text, nband int) -> double precision
1312
1313    hasnodata = FALSE
1314
1315{{{
1316ST_Mean('tmax_2010', 'rast', 1)
1317}}}
1318
13193. ST_Mean(rastertable text, rastercolumn text, hasnodata boolean) -> double precision
1320
1321    nband = 1
1322
1323{{{
1324ST_Mean('precip_2011', 'rast', TRUE)
1325}}}
1326
13274. ST_Mean(rastertable text, rastercolumn text) -> double precision
1328
1329    nband = 1 and hasnodata = FALSE
1330
1331{{{
1332ST_Mean('tmin_2009', 'rast')
1333}}}
1334
1335Variations for ST_ApproxMean are:
1336
13371. ST_ApproxMean(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> double precision
1338
1339{{{
1340ST_ApproxMean('tmax_2010', 'rast', 1, FALSE, 0.5)
1341
1342ST_ApproxMean('precip_2011', 'rast', 1, TRUE, 0.2)
1343}}}
1344
13452. ST_ApproxMean(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> double precision
1346
1347    hasnodata = FALSE
1348
1349{{{
1350ST_ApproxMean('tmax_2010', 'rast', 1, 0.5)
1351
1352ST_ApproxMean('precip_2011', 'rast', 1, 0.2)
1353}}}
1354
13553. ST_ApproxMean(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> double precision
1356
1357    nband = 1
1358
1359{{{
1360ST_ApproxMean('tmax_2010', 'rast', FALSE, 0.5)
1361
1362ST_ApproxMean('precip_2011', 'rast', TRUE, 0.2)
1363}}}
1364
13654. ST_ApproxMean(rastertable text, rastercolumn text, sample_percent double precision) -> double precision
1366
1367    nband = 1 and hasnodata = FALSE
1368
1369{{{
1370ST_ApproxMean('tmax_2010', 'rast', 0.5)
1371
1372ST_ApproxMean('precip_2011', 'rast', 0.2)
1373}}}
1374
13755. ST_ApproxMean(rastertable text, rastercolumn text) -> double precision
1376
1377    nband = 1, hasnodata = FALSE and sample_percent = 0.1
1378
1379{{{
1380ST_ApproxMean('tmax_2010', 'rast')
1381
1382ST_ApproxMean('precip_2011', 'rast')
1383}}}
1384
1385The mean returned in the coverage functions (has rastertable and rastercolumn arguments) is a weighted mean of the means of each raster tile.
1386
1387----
1388
1389'''ST_StdDev(raster, nband) -> double precision'''[[BR]]
1390This function calls ST_SummaryStats and only returns the standard deviation from that function.
1391
13921. ST_StdDev(rast raster, nband int, hasnodata boolean) -> double precision
1393
1394  returns the standard deviation as a double precision
1395
1396  nband: index of band
1397
1398  hasnodata: if FALSE, any pixel who's value is nodata is ignored
1399
1400{{{
1401ST_StdDev(rast, 1, FALSE)
1402}}}
1403
14042. ST_StdDev(rast raster, nband int) -> double precision
1405
1406  assumes hasnodata = FALSE
1407
1408{{{
1409ST_StdDev(rast, 2)
1410}}}
1411
14123. ST_StdDev(rast raster, hasnodata boolean) -> double precision
1413
1414  assumes nband = 1
1415
1416{{{
1417ST_StdDev(rast, TRUE)
1418}}}
1419
14204. ST_StdDev(rast raster) -> double precision
1421
1422  assumes nband = 1 and hasnodata = FALSE
1423
1424{{{
1425ST_StdDev(rast)
1426}}}
1427
1428The set of ST_ApproxStdDev functions are:
1429
14301. ST_ApproxStdDev(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> double precision
1431
1432  sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
1433
1434{{{
1435ST_ApproxStdDev(rast, 3, FALSE, 0.1)
1436
1437ST_ApproxStdDev(rast, 1, TRUE, 0.5)
1438}}}
1439
14402. ST_ApproxStdDev(rast raster, nband int, sample_percent double precision) -> double precision
1441
1442  assumes that nband = 1
1443
1444{{{
1445ST_ApproxStdDev(rast, 2 0.01)
1446
1447ST_ApproxStdDev(rast, 4, 0.025)
1448}}}
1449
14503. ST_ApproxStdDev(rast raster, hasnodata boolean, sample_percent double precision) -> double precision
1451
1452  assumes that nband = 1
1453
1454{{{
1455ST_ApproxStdDev(rast, FALSE, 0.01)
1456
1457ST_ApproxStdDev(rast, TRUE, 0.025)
1458}}}
1459
14604. ST_ApproxStdDev(rast raster, sample_percent double precision) -> double precision
1461
1462  assumes that nband = 1 and hasnodata = FALSE
1463
1464{{{
1465ST_ApproxStdDev(rast, 0.25)
1466}}}
1467
14685. ST_ApproxStdDev(rast raster) -> double precision
1469
1470  assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
1471
1472{{{
1473ST_ApproxStdDev(rast)
1474}}}
1475
1476The following functions are provided for coverage tables.
1477
14781. ST_StdDev(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> double precision
1479
1480  rastertable: name of table with raster column
1481
1482  rastercolumn: name of column of data type raster
1483
1484{{{
1485ST_StdDev('tmax_2010', 'rast', 1, FALSE)
1486
1487ST_StdDev('precip_2011', 'rast', 1, TRUE)
1488}}}
1489
14902. ST_StdDev(rastertable text, rastercolumn text, nband int) -> double precision
1491
1492    hasnodata = FALSE
1493
1494{{{
1495ST_StdDev('tmax_2010', 'rast', 1)
1496}}}
1497
14983. ST_StdDev(rastertable text, rastercolumn text, hasnodata boolean) -> double precision
1499
1500    nband = 1
1501
1502{{{
1503ST_StdDev('precip_2011', 'rast', TRUE)
1504}}}
1505
15064. ST_StdDev(rastertable text, rastercolumn text) -> double precision
1507
1508    nband = 1 and hasnodata = FALSE
1509
1510{{{
1511ST_StdDev('tmin_2009', 'rast')
1512}}}
1513
1514Variations for ST_ApproxStdDev are:
1515
15161. ST_ApproxStdDev(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> double precision
1517
1518{{{
1519ST_ApproxStdDev('tmax_2010', 'rast', 1, FALSE, 0.5)
1520
1521ST_ApproxStdDev('precip_2011', 'rast', 1, TRUE, 0.2)
1522}}}
1523
15242. ST_ApproxStdDev(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> double precision
1525
1526    hasnodata = FALSE
1527
1528{{{
1529ST_ApproxStdDev('tmax_2010', 'rast', 1, 0.5)
1530
1531ST_ApproxStdDev('precip_2011', 'rast', 1, 0.2)
1532}}}
1533
15343. ST_ApproxStdDev(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> double precision
1535
1536    nband = 1
1537
1538{{{
1539ST_ApproxStdDev('tmax_2010', 'rast', FALSE, 0.5)
1540
1541ST_ApproxStdDev('precip_2011', 'rast', TRUE, 0.2)
1542}}}
1543
15444. ST_ApproxStdDev(rastertable text, rastercolumn text, sample_percent double precision) -> double precision
1545
1546    nband = 1 and hasnodata = FALSE
1547
1548{{{
1549ST_ApproxStdDev('tmax_2010', 'rast', 0.5)
1550
1551ST_ApproxStdDev('precip_2011', 'rast', 0.2)
1552}}}
1553
15545. ST_ApproxStdDev(rastertable text, rastercolumn text) -> double precision
1555
1556    nband = 1, hasnodata = FALSE and sample_percent = 0.1
1557
1558{{{
1559ST_ApproxStdDev('tmax_2010', 'rast')
1560
1561ST_ApproxStdDev('precip_2011', 'rast')
1562}}}
1563
1564The standard deviation returned in the coverage functions (has rastertable and rastercolumn arguments) is the cumulative standard deviation of all raster tiles.
1565
1566----
1567
1568'''ST_MinMax(raster, nband) -> record'''[[BR]]
1569This function calls ST_SummaryStats and only returns the min and max values from that function.
1570
15711. ST_MinMax(rast raster, nband int, hasnodata boolean) -> record
1572
1573  returns the record (min double precision, max double precision)
1574
1575  nband: index of band
1576
1577  hasnodata: if FALSE, any pixel who's value is nodata is ignored
1578
1579{{{
1580ST_MinMax(rast, 1, FALSE)
1581}}}
1582
15832. ST_MinMax(rast raster, nband int) -> record
1584
1585  assumes hasnodata = FALSE
1586
1587{{{
1588ST_MinMax(rast, 2)
1589}}}
1590
15913. ST_MinMax(rast raster, hasnodata boolean) -> record
1592
1593  assumes nband = 1
1594
1595{{{
1596ST_MinMax(rast, TRUE)
1597}}}
1598
15994. ST_MinMax(rast raster) -> record
1600
1601  assumes nband = 1 and hasnodata = FALSE
1602
1603{{{
1604ST_MinMax(rast)
1605}}}
1606
1607The set of ST_ApproxMinMax functions are:
1608
16091. ST_ApproxMinMax(rast raster, nband int, hasnodata boolean, sample_percent record) -> record
1610
1611  sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider
1612
1613{{{
1614ST_ApproxMinMax(rast, 3, FALSE, 0.1)
1615
1616ST_ApproxMinMax(rast, 1, TRUE, 0.5)
1617}}}
1618
16192. ST_ApproxMinMax(rast raster, nband int, sample_percent double precision) -> record
1620
1621  assumes that nband = 1
1622
1623{{{
1624ST_ApproxMinMax(rast, 2 0.01)
1625
1626ST_ApproxMinMax(rast, 4, 0.025)
1627}}}
1628
16293. ST_ApproxMinMax(rast raster, hasnodata boolean, sample_percent double precision) -> record
1630
1631  assumes that nband = 1
1632
1633{{{
1634ST_ApproxMinMax(rast, FALSE, 0.01)
1635
1636ST_ApproxMinMax(rast, TRUE, 0.025)
1637}}}
1638
16394. ST_ApproxMinMax(rast raster, sample_percent double precision) -> record
1640
1641  assumes that nband = 1 and hasnodata = FALSE
1642
1643{{{
1644ST_ApproxMinMax(rast, 0.25)
1645}}}
1646
16475. ST_ApproxMinMax(rast raster) -> record
1648
1649  assumes that nband = 1, hasnodata = FALSE and sample_percent = 0.1
1650
1651{{{
1652ST_ApproxMinMax(rast)
1653}}}
1654
1655The following functions are provided for coverage tables.
1656
16571. ST_MinMax(rastertable text, rastercolumn text, nband int, hasnodata boolean) -> record
1658
1659  rastertable: name of table with raster column
1660
1661  rastercolumn: name of column of data type raster
1662
1663{{{
1664ST_MinMax('tmax_2010', 'rast', 1, FALSE)
1665
1666ST_MinMax('precip_2011', 'rast', 1, TRUE)
1667}}}
1668
16692. ST_MinMax(rastertable text, rastercolumn text, nband int) -> record
1670
1671    hasnodata = FALSE
1672
1673{{{
1674ST_MinMax('tmax_2010', 'rast', 1)
1675}}}
1676
16773. ST_MinMax(rastertable text, rastercolumn text, hasnodata boolean) -> record
1678
1679    nband = 1
1680
1681{{{
1682ST_MinMax('precip_2011', 'rast', TRUE)
1683}}}
1684
16854. ST_MinMax(rastertable text, rastercolumn text) -> record
1686
1687    nband = 1 and hasnodata = FALSE
1688
1689{{{
1690ST_MinMax('tmin_2009', 'rast')
1691}}}
1692
1693Variations for ST_ApproxMinMax are:
1694
16951. ST_ApproxMinMax(rastertable text, rastercolumn text, nband int, hasnodata boolean, sample_percent double precision) -> record
1696
1697{{{
1698ST_ApproxMinMax('tmax_2010', 'rast', 1, FALSE, 0.5)
1699
1700ST_ApproxMinMax('precip_2011', 'rast', 1, TRUE, 0.2)
1701}}}
1702
17032. ST_ApproxMinMax(rastertable text, rastercolumn text, nband int, sample_percent double precision) -> record
1704
1705    hasnodata = FALSE
1706
1707{{{
1708ST_ApproxMinMax('tmax_2010', 'rast', 1, 0.5)
1709
1710ST_ApproxMinMax('precip_2011', 'rast', 1, 0.2)
1711}}}
1712
17133. ST_ApproxMinMax(rastertable text, rastercolumn text, hasnodata boolean, sample_percent double precision) -> record
1714
1715    nband = 1
1716
1717{{{
1718ST_ApproxMinMax('tmax_2010', 'rast', FALSE, 0.5)
1719
1720ST_ApproxMinMax('precip_2011', 'rast', TRUE, 0.2)
1721}}}
1722
17234. ST_ApproxMinMax(rastertable text, rastercolumn text, sample_percent double precision) -> record
1724
1725    nband = 1 and hasnodata = FALSE
1726
1727{{{
1728ST_ApproxMinMax('tmax_2010', 'rast', 0.5)
1729
1730ST_ApproxMinMax('precip_2011', 'rast', 0.2)
1731}}}
1732
17335. ST_ApproxMinMax(rastertable text, rastercolumn text) -> record
1734
1735    nband = 1, hasnodata = FALSE and sample_percent = 0.1
1736
1737{{{
1738ST_ApproxMinMax('tmax_2010', 'rast')
1739
1740ST_ApproxMinMax('precip_2011', 'rast')
1741}}}
1742
1743----
1744
1745'''ST_Histogram(raster, nband) -> set of records'''[[BR]]
1746ST_Histogram and ST_ApproxHistogram provide methods to determine a raster's data distribution.
1747
1748The return of ST_Histogram and ST_ApproxHistogram is a set of records where each record is (min, max, count, proportion).
1749
1750ST_Histogram has the following variations.
1751
17521. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, width double precision[], right boolean) -> set of records
1753
1754  returns set of records of four columns (min, max, count, proportion)
1755
1756  nband: index of band to process on
1757
1758  hasnodata: if FALSE, any pixel who's value is nodata is ignored.
1759
1760  bins: the number of categories/bins to have in the histogram. If NULL or value less than one, the number of categories will be auto-computed using Sturges' formula if the number of values >= 30 or Square-root choice if number of values < 30.
1761
1762    http://en.wikipedia.org/wiki/Histogram#Mathematical_definition
1763
1764  width: an array indicating the width of each category/bin. If the number of bins is greater than the number of widths, the widths are repeated. Example: 9 bins, widths are [a, b, c] will have the output be [a, b, c, a, b, c, a, b, c].
1765
1766  right: compute the histogram from the right rather than from the left (default). This changes the criteria for evaluating a value x from [a, b) to (a, b].
1767
1768{{{
1769ST_Histogram(rast, 2, FALSE, NULL, NULL, FALSE)
1770
1771ST_Histogram(rast, 1, TRUE, 100, NULL, FALSE)
1772
1773ST_Histogram(rast, 2, FALSE, NULL, ARRAY[100, 50], FALSE)
1774
1775ST_Histogram(rast, 2, FALSE, 9, ARRAY[1000], TRUE)
1776
1777ST_Histogram(rast, 2, FALSE, 20, ARRAY[100, 200, 300], TRUE)
1778}}}
1779
17802. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, right boolean) -> set of records
1781
1782  parameter "width" is not specified thus resulting in all bins having the same widths
1783
1784{{{
1785ST_Histogram(rast, 2, FALSE, 5, FALSE)
1786}}}
1787
17883. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int) -> set of records
1789
1790  the parameter "right" is removed and assumed to be FALSE
1791
1792{{{
1793ST_Histogram(rast, 2, FALSE, 5)
1794}}}
1795
17964. ST_Histogram(rast raster, nband int, hasnodata boolean) -> set of records
1797
1798  the parameter "bins" is removed and set to NULL.  The function will compute the number of bins to use
1799
18005. ST_Histogram(rast raster, nband int) -> set of records
1801
1802  parameter "hasnodata" is removed and assumed to be FALSE
1803
18046. ST_Histogram(rast raster) -> set of records
1805
1806  assumes that nband is 1.
1807
18087. ST_Histogram(rast raster, nband int, bins int, width double precision[], right boolean) -> set of records
1809
1810  hasnodata is assumed to be FALSE
1811
18128. ST_Histogram(rast raster, nband int, bins int, right boolean) -> set of records
1813
1814  all bins will have equal widths
1815
18169. ST_Histogram(rast raster, nband int, bins int) -> set of records
1817
1818  right is assumed to be FALSE
1819
1820ST_ApproxHistogram should have the following variations.
1821
18221. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int, width double precision[], right boolean) -> set of record
1823
1824    sample_percent: a value between 0 and 1 indicating the percentage of the raster band's pixels to consider when generating the histogram.
1825
1826{{{
1827ST_Histogram(rast, 2, FALSE, 0.1, NULL, NULL, FALSE)
1828
1829ST_Histogram(rast, 1, TRUE, 1, 100, NULL, FALSE)
1830
1831ST_Histogram(rast, 2, FALSE, 0.2, NULL, ARRAY[100, 50], FALSE)
1832
1833ST_Histogram(rast, 2, FALSE, 0.25, 9, ARRAY[1000], TRUE)
1834
1835ST_Histogram(rast, 2, FALSE, 0.05, 20, ARRAY[100, 200, 300], TRUE)
1836}}}
1837
18382. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int, right boolean) -> set of records
1839
1840  parameter "width" is not specified thus resulting in all bins having the same widths
1841
18423. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision, bins int) -> set of records
1843
1844  the parameter "right" is removed and assumed to be FALSE
1845
1846{{{
1847ST_ApproxHistogram(rast, 2, FALSE, 5)
1848}}}
1849
18504. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean, sample_percent double precision) -> set of records
1851
1852  the parameter "bins" is removed and set to NULL so that function can compute the number of bins to use
1853
18545. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision) -> set of records
1855
1856  parameter "hasnodata" is removed and assumed to be FALSE
1857
18586. ST_ApproxHistogram(rast raster, nband int) -> set of records
1859
1860  assumes that sample_percent is 0.1
1861
18627. ST_ApproxHistogram(rast raster, sample_percent double_precision) -> set of records
1863
1864  assumes that nband is 1
1865
18668. ST_ApproxHistogram(rast raster) -> set of records
1867
1868  assumes that nband is 1 and sample_percent is 0.1
1869
18709. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int, width double precision[], right boolean) -> set of records
1871
1872  hasnodata is assumed to be FALSE
1873
187410. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int, right boolean) -> set of records
1875
1876  all bins will have equal widths
1877
187811. ST_ApproxHistogram(rast raster, nband int, sample_percent double precision, bins int) -> set of records
1879
1880  right is assumed to be FALSE
1881
1882----
18831883== '''Objective FV.17 - Being able to refer to band by textual name.''' ==
18841884