; $Id: mean_spec.pro,v 1.1 2004/02/09 14:27:47 oivindw Exp $
;+
; NAME:
;       mean_spec
;
; PURPOSE:
;       MEAN_SPEC calculates the mean spectrum of a 2D or 3D data
;       cube. 
;
; CATEGORY:
;       Hansteen/Wikstol Data analysis SW
;
; CALLING SEQUENCE:
;       mspec = mean_spec(data)
;
; INPUTS:
;       data: The spectral data from which the average spectrum will
;       be calculated. Typically this will be of type: data(lambda,
;       x,y)
;
; KEYWORD PARAMETERS:
;       retain_x: Keep x-dimension. Only average over y
;       retain_y: Keep y-dimension. Only average over x
;
; OUTPUTS:
;       Average spectrum: mspec(lambda)
;
; CALLS:
;
;
; COMMON BLOCKS:
;       
;
; PROCEDURE:
;  
; 
; RESTRICTIONS:
;       The input data needs to have lambda as the first dimension
;
;
; MODIFICATION HISTORY:
;       09-Feb-2004: Oivind Wikstol, version 1.0
;-
function mean_spec, data, retain_x = retain_x, retain_y = retain_y

  if n_params() eq 0 then begin
    print, 'usage: mean_spec,data'
    return, -99
  endif

  sz = size(data)
  
  if sz[0] lt 2 then begin
    print, 'mean_spec: Data must be at least 2D'
    return, -99
  endif

  if sz[0] lt 3 then begin
    mspec = total(data, 2)/sz[2]
    return, mspec
  endif else begin 
    if n_elements(retain_x) ne 0 then begin
      mspec = total(data, 3)/sz[3]
      return, mspec
    endif
    if n_elements(retain_y) ne 0 then begin
      mspec = total(data, 2)/sz[2]
      return, mspec
    endif
    mspec = total(data, 2)/sz[2]
    mspec = total(mspec, 2)/sz[3]
  endelse
  return, mspec
end