; docformat = 'rst'
;
; NAME:
;   mad
; PURPOSE:
;   Compute the Median Absolute Deviation (MAD)
;
;+
; :Description:
;   Compute the Median Absolute Deviation (MAD)
;
; :Categories:
;    Maths, Moment
;    
; :Params:
;   VAL: in, required, type=float
;        An array of values for which the median absolute deviation is sought
;
; :Returns: The median absolute deviation of the VALUES
;
; :Examples:
;    Compute the Median Absolute Deviation (MAD) of 5 measurements::
;      IDL> measures= [ 1.8,2.0,2.2,1.9,2.1]
;      IDL> print, MAD( measures )
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;       Original Version written in September 2014, B. Carry (IMCCE)
;-
function mad, val

 ;--I-- Bullet-proof checks
  if not keyword_set(val) then begin
    message, /IOERROR, 'Syntax: value  = MAD(val)'
    return, -1
  endif

 ;--II-- Singular array
  nbVal = n_elements(val)
  if nbVAL eq 1 then return, val

 ;--III-- Compute the Median
  med = median(val)

 ;--IV-- Compute the MAD
  mad = median( abs(val-med) )

 ;--V-- Return the MAD
  return, mad

end