;+
; This procedure adds a data container to the accum buffer, in
; preparation for averaging.  The PDC (!g.s[0]) is used by default
; but an alternate data container can be specified using the 'dc' keyword.
; 
; <p>The first data container accum'ed in each buffer is used as a template
; for that buffer and subsequent data containers accum'ed to that buffer
; must match in number of channels and frequency range.
;
; <p> There are four accum buffers available to that the user can
; average polarizations simultaneously, but separately, if it is
; desired to do so.
;
; <p><strong>See: <a href="../../pro/guide/accum.pro">accum.pro</a></strong>
;
; @param accumnum {in}{optional}{type=integer}{default=0} accum buffer.  
; Defaults to the primary buffer (accumnum = 0).  There are 4 buffers 
; total so this value must be between 0 and 3, inclusive.
;
; @keyword weight {in}{optional}{type=float} The weight to use for 
; averaging this data.  If not set, a weight of exposure/Tsys^2 is used.
;
; @keyword dc {in}{optional}{type=spectrum or integer} The data container to
; accum.  If not supplied, use !g.s[0].  If this is an integer, then
; use the data container at that index number in !g.s.
;
; @examples
;    A simple averaging operation:
; <pre>
;   sclear
;   getrec,1
;   accum
;   getrec,2
;   accum
;   ave
; </pre>
; <p> Average two polarizations separately for some position switched scans
; <pre>
;   sclear                  ; clears accum buffer 0
;   sclear, 1               ; clears accum buffers 1
;   getps,32,plnum=0
;   accum, 0
;   getps,32,plnum=1
;   accum, 1
;   getps,34,plnum=0
;   accum, 0
;   getps,34,plnum=1
;   accum, 1
;   ave,1                   ; Average plnum=1 data and store
;                           ;  the result in the PDC
;   copy,0,1                ; Copy the result to DC 1
;   ave, 0                  ; Average plnum=0 data
;   oshow, 1                ; Overplot the plnum=1 average
; </pre>
;
; @uses <a href="../toolbox/dcaccum.html">dcaccum</a>
;
; <DT CLASS="attribute">Code
; <DD CLASS="attribute_item">
;  <a href="../../pro/guide/accum.pro">accum.pro</a>
; </DD></DT>
;
; @version $Id: accum.pro,v 1.16 2005/06/02 17:09:44 bgarwood Exp $
;-
pro accum, accumnum, weight=weight, dc=dc
    compile_opt idl2

    on_error, 2

    if n_elements(accumnum) eq 0 then accumnum = 0

    if (accumnum lt 0 or accumnum gt 3) then begin
        message,'accumnum must be in the range 0 to 3',/info
        return
    endif

    accumbuf = !g.accumbuf[accumnum]

    if n_elements(dc) eq 0 then begin
        thisdc = !g.s[0]
    endif else begin
        thisdc = dc
    endelse

    if size(thisdc,/type) ne 8 then begin
        ; interpret it as an index
        if thisdc lt 0 or thisdc ge n_elements(!g.s) then begin
            message,string(n_elements(!g.s),format='("dc index must be between 0 and ",i2)'),/info
            return
        endif
        thisdc = !g.s[thisdc]
    endif
    dataOk = data_valid(thisdc,name=name)
    if dataOk le 0 then begin
        message,'No valid data found to accum',/info
        return
    endif
    if name ne 'SPECTRUM' then begin
        message,'data container is not a SPECTRUM',/info
        return
    endif

    dcaccum, accumbuf, thisdc, weight=weight

    !g.accumbuf[accumnum] = accumbuf

end