;+
;
; Laboratory for Atmospheric and Space Physics
; University of Colorado, Boulder, Colorado, USA
;
; FILENAME:
;   find_image_95th_percentile.pro
;
; AUTHOR:
;   James Everton
;
; DATE:    June 1, 2007
;
; PURPOSE:
;   This file creates the function 'find_image_95th_percentile':
;      Receives an array of images and calculates the maximum 95th percentile 
;
; BACKGROUND:
;   With some data, spikes may occur, so we remove the upper 5th percent
;   to account for them.
;
; ALGORITHM:
;   To find the 95th percent, each image is sorted into an array, all NaN
;   values are removed, and then the 95th percentile is found from that.
;
; REFERENCES:
;
; NOTES:
;
; CONSTRAINTS:
;
; OTHER SERVERS/MODULES USED:
;
; RELATED MODULES / CLASSES:
;
; SUPPORTING DATABASE TABLES OR FILES:
;
; USAGE EXAMPLE:
;   maximum = find_image_95th_percentile(image_array)
;-

; --------------------------------------------------------------------------
; FUNCTION find_image_95th_percentile
; --------------------------------------------------------------------------
; PURPOSE:
;   This function takes an array of pointers to images, then returns the
;   maximum value found in all the images.
;
; ARGUMENTS:
;   The only argument needed is an array of image (2-D array) pointers
;
; RETURN VALUE:
;   The 95th percentile is calculated for each image, then the maximum
;   of all those gets returned.
;
function find_image_95th_percentile, images
   maximum = 0
   for i=0, N_ELEMENTS(images)-1 do begin
      array = (*images[i])[sort(*images[i])]
      array = array[where(strtrim(array,2) ne 'NaN')]
      new_max = array[n_elements(array)*.95]
      if new_max gt maximum then maximum = new_max
   endfor
   return, maximum
end