;+
; Laboratory for Atmospheric and Space Physics
; University of Colorado, Boulder, Colorado, USA
;
; FILENAME:
;   read_cips_ncdf1.pro
;
; AUTHOR:
;   Jim Craft
;
; DATE:    April 2, 2012
; 
; MODIFIED:
;   Cora Randall, 13 May 2012
;   Cora Randall, 25 Feb 2023
;
; PURPOSE:
;   This function accesses CIPS data stored in NetCDF Files and returns the data
;   in a structure.
;   
; KEYWORDS:
;   verbose - used for diagnostic purposes.  Using this keyword will provide user
;             with information about the file and the fields within the file.
;
; CALL:
;   data = read_cips_ncdf1(filename [, /verbose])
;      "data" is the name for the returned data structure.
;      "filename" must include the path and filename of the CIPS ncdf file.
;      "/verbose" is optional
;
; DIFFERENCES BETWEEN READ_CIPS_NCDF1.PRO AND READ_CIPS_NCDF2.PRO:
;   read_cips_ncdf1.pro is a function. It returns all variables in a structure. 
;   The path and filename are included in the call statement.
;    
;   read_cips_ncdf2.pro is a program. It reads all variables individually into the main level.
;   The path and filename are included in the first two statements in the code.
;   
; NOTES:
;    To get the CIPS PMC level 3a longitude/latitude grid, download the ncdf 
;    or IDL save file from https://lasp.colorado.edu/aim/download/pmc/l3a.
;    
;    Some of the strings were mistakenly written out as bytes in the CIPS ncdf files.
;    This code includes a fix for this, but it does not always work properly.
;    See data documentation.

function read_cips_ncdf1, filename, verbose=verbose

  if ~ncdf_exists() then begin
    print, 'NetCDF Library is not available!'
    exit
  endif
  ; make sure the file exists
  if file_test( filename ) then begin
    if keyword_set( verbose ) then $
      print, 'Opening ', filename
    ; open it
    ncdfId = ncdf_open( filename )
    if keyword_set( verbose ) then $
      print, 'NetCDF ID = ', ncdfId
    ; grab the basic netCDF structure
    ncdfStruct = ncdf_inquire( ncdfId )
    if keyword_set( verbose ) then begin
      print
      print, 'The NetCDF Structure returned from the file has the following:'
      print, 'Ndims = ', ncdfStruct.Ndims
      print, 'Nvars = ', ncdfStruct.Nvars
      print, 'Ngatts = ', ncdfStruct.Ngatts
      print, 'RecDim = ', ncdfStruct.RecDim
      print
    endif
    
    ;loop through the structure and grab the tag names and associated data
    for index = 0, ncdfStruct.Nvars - 1 do begin
      ; inquire on the netCDF file variables
      zed = ncdf_varinq( ncdfId, index )
      if keyword_set( verbose ) then $
        print, 'NetCDF Structure Tag Name: ', zed.name
      ; get the variable id
      varId = ncdf_varid( ncdfId, zed.name )
      ; get the data
      ncdf_varget, ncdfId, varId, varData
      ; invoke some magic to check for string data
      ; masquerading as byte data, but don't convert
      ; byte data blindly, ie quality_flags is a 2-dimensional
      ; array of byte data.
      if ( ( size( varData, /n_dimensions )  EQ 1 ) && $
           ( size( varData, /type ) EQ 1 ) ) then $
        varData = string( varData )
      if keyword_set( verbose ) then $
        help, varData
      ; build the structure to return
      if ( index EQ 0 ) then begin
        ncdfDataStruct = create_struct( zed.name, varData )
      endif else begin
        ncdfDataStruct = create_struct( ncdfDataStruct, zed.name, varData )
      endelse
    endfor
    ; close the netCDF file
    ncdf_close, ncdfId
  endif else $  
    return, -1
  
  return, ncdfDataStruct
end