;+
;Procedure: THM_LOAD_FGM
;
;Purpose:  Loads THEMIS fluxgate magnetometer data
;
;keywords:
;  probe = Probe name. The default is 'all', i.e., load all available probes.
;          This can be an array of strings, e.g., ['a', 'b'] or a
;          single string delimited by spaces, e.g., 'a b'
;  datatype = The type of data to be loaded, 'fge', 'fgh', or 'fgl'.  'all'
;          can be passed in also, to get all variables.
;  TRANGE= (Optional) Time range of interest  (2 element array), if
;          this is not set, the default is to prompt the user. Note
;          that if the input time range is not a full day, a full
;          day's data is loaded
;  level = the level of the data to read, the default is 'l1', or level-1
;          data. A string (e.g., 'l2') or an integer can be used. 'all'
;          can be passed in also, to get all levels.
;  type=   'raw' or 'calibrated'. default is calibrated.
;  coord=  coordinate system of output.  default is 'ssl'
;  suffix= suffix to add to output data quantity (not added to support data)
;  CDF_DATA: named variable in which to return cdf data structure: only works
;          for a single spacecraft and datafile name.
;  VARNAMES: names of variables to load from cdf: default is all.
;  /GET_SUPPORT_DATA: load support_data variables as well as data variables
;          into tplot variables.
;  /DOWNLOADONLY: download file but don't read it.
;  /no_download: use only files which are online locally.
;  relpathnames_all: named variable in which to return all files that are
;          required for specified timespan, probe, datatype, and level.
;          If present, no files will be downloaded, and no data will be loaded.
;  /valid_names, if set, then this routine will return the valid probe, datatype
;          and/or level options in named variables supplied as
;          arguments to the corresponding keywords.
;  files   named varible for output of pathnames of local files.
;  /VERBOSE  set to output some useful info, set to 0 to or 1 to reduce output.
;Example:
;   thg_load_fgm,probe=['a','b']
;Notes:
;  This routine is (should be) platform independent.
;
; $LastChangedBy: kenb-mac $
; $LastChangedDate: 2007-07-12 12:09:54 -0700 (Thu, 12 Jul 2007) $
; $LastChangedRevision: 1084 $
; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_2_02/idl/themis/spacecraft/fields/thm_load_fgm.pro $
;-

; fgm-specific helper function
; to return relative path names to files in the data tree.
; this routine maps datatypes to file type.
function thm_load_fgm_relpath, sname=probe, filetype=ft, $
                               level=lvl, trange=trange, $
                               addmaster=addmaster, _extra=_extra

  relpath = 'th'+probe+'/'+lvl+'/'+ ft+'/'
  prefix = 'th'+probe+'_'+lvl+'_'+ft+'_'
  dir = 'YYYY/'

;     The following was a temporary cluge to get to tmserver1 data
;     I am leaving it in place as an example of how to call
;     file_dailynames with an alternative directory structure.
  if strcmp(!themis.remote_data_dir, 'http://themis-tmserver1',18) eq 1 $
  then begin
;    pathformat = 'L1CDF/th'+sc+'/YYYY/MM/DD/th'+sc+'_l1_fgm_YYYYMMDD_v01.cdf'
     relpath = 'L1CDF/th'+probe+'/'
     dir = 'YYYY/MM/DD/'
  endif
  ending = '_v01.cdf'

  return, file_dailynames(relpath, prefix, ending, dir=dir, $
                          trange = trange,addmaster=addmaster)
end

pro thm_load_fgm_post, sname=probe, datatype=dt, level=lvl, $
                       tplotnames=tplotnames, $
                       suffix=suffix, proc_type=proc_type, coord=coord, $
                       delete_support_data=delete_support_data, _extra=_extra


  ;; remove suffix from support data
  ;; and add DLIMIT tags to data quantities
  for l=0, n_elements(tplotnames)-1 do begin
     tplot_var = tplotnames[l]
     dtl = strmid(tplot_var, 4, 3)
     get_data, tplot_var, data=d_str, limit=l_str, dlimit=dl_str
     if data_type(dl_str) eq 8 && dl_str.cdf.vatt.var_type eq 'data' $
     then begin
        if strmatch(lvl, 'l1') then begin
           unit='ADC'
           data_att = { data_type:'raw', coord_sys:'fgm_sensor', $
                        units:unit}
           labels = [ 'b1', 'b2', 'b3']
        end else if strmatch(lvl, 'l2') then begin
           unit=dl_str.cdf.vatt.units
           coord_sys=strlowcase(strmid(dl_str.cdf.vatt.coordinate_system,0,3))
           data_att = { data_type:'calibrated', coord_sys:coord_sys, $
                        units:unit}
           labels = [ 'bx', 'by', 'bz']
        end
        str_element, dl_str, 'data_att', data_att, /add
        colors = [ 2, 4, 6]

        str_element, dl_str, 'colors', colors, /add
        str_element, dl_str, 'labels', labels, /add
        str_element, dl_str, 'labflag', 1, /add
        str_element, dl_str, 'ytitle', $
                     string( tplot_var, unit, format='(A,"!C!C[",A,"]")'), /add

        store_data, tplot_var, data=d_str, limit=l_str, dlimit=dl_str
     endif else begin
        ;; for support data,
        ;; rename original variable to exclude suffix
        if keyword_set(suffix) then begin
           tplot_var_root = strmid(tplot_var, 0, $
                                   strpos(tplot_var, suffix, /reverse_search))
           store_data, delete=tplot_var
           if tplot_var_root then begin
              store_data, tplot_var_root, data=d_str, limit=l_str, dlimit=dl_str
           endif
           tplot_var = tplot_var_root
        endif
        ;; save name of support tplot variable for possible deletion
        if tplot_var && keyword_set(delete_support_data) then begin
           if size(support_var_list,/type) eq 0 then $
              support_var_list = [tplot_var] $
           else $
              support_var_list = [support_var_list,tplot_var]
        endif

     endelse
  endfor

  ;; calibrate and transform coordinates, if this is L1
  if strmatch(lvl, 'l1') then begin
     if ~keyword_set(proc_type) || strmatch(proc_type, 'calibrated') then begin
        thm_cal_fgm, probe=probe, datatype=dt, coord=coord, $
                     in_suffix=suffix, out_suffix=suffix
        ;; delete support data
        if size(support_var_list, /type) ne 0 then $
           del_data, support_var_list

     endif

  endif
end


pro thm_load_fgm,probe=probe, datatype=datatype, trange=trange, $
                 level=level, verbose=verbose, downloadonly=downloadonly, $
                 relpathnames_all=relpathnames_all, no_download=no_download, $
                 cdf_data=cdf_data,get_support_data=get_support_data, $
                 varnames=varnames, valid_names = valid_names, files=files, $
                 suffix=suffix, type=type, coord=coord, varformat=varformat, $
                 progobj=progobj

  if arg_present(relpathnames_all) then begin
     downloadonly=1
     no_download=1
  end
  if not keyword_set(suffix) then suffix = ''
  if not keyword_set(coord) then coord='dsl'

  vlevels = 'l1 l2'
  deflevel = 'l2'
  lvl = thm_valid_input(level,'Level',vinputs=vlevels,definput=deflevel,$
                        format="('l', I1)", verbose=0)
  if lvl eq '' then return

  if lvl eq 'l2' and keyword_set(type) then begin
    print,"Type keyword not valid for level 2 data."
    return
  endif

  if lvl eq 'l1' then begin
     ;; default action for loading level 1 is to calibrate
     if ~keyword_set(type) || strmatch(type, 'calibrated') then begin
        ;; we're calibrating, so make sure we get support data
        if not keyword_set(get_support_data) then begin
           get_support_data = 1
           delete_support_data = 1
        endif
     endif
  endif

  thm_load_xxx,sname=probe, datatype=datatype, trange=trange, $
               level=level, verbose=verbose, downloadonly=downloadonly, $
               relpathnames_all=relpathnames_all, no_download=no_download, $
               cdf_data=cdf_data,get_cdf_data=arg_present(cdf_data), $
               get_support_data=get_support_data, $
               varnames=varnames, valid_names = valid_names, files=files, $
               vsnames = 'a b c d e', $
               type_sname = 'probe', $
               vdatatypes = 'fgl fgh fge', $
               file_vdatatypes = 'fgm', $
               vlevels = vlevels, $
               vL2datatypes = 'fgs fgl fgh fge', $
               vL2coord = 'ssl dsl gse gsm', $
               deflevel = deflevel, $
               version = 'v01', $
               relpath_funct = 'thm_load_fgm_relpath', $
               post_process_proc='thm_load_fgm_post', $
               delete_support_data=delete_support_data, $
               proc_type=type, coord=coord, suffix=suffix, $
               progobj=progobj,$
               varformat=varformat

end