This page was created by the IDL library routine `mk_html_help2`.

Last modified: Sat Jul 26 18:17:38 2025.

# Directory Listing of Routines

# general/CDF

- CDF2IDLTYPE
  Return an IDL type number given a CDF data type
- CDF2TPLOT
- CDF_DEFAULT_CDFI_STRUCTURE
  Number of functions that generate default structures for CDF files
- CDF_INFO
  Returns a structure with useful information about a CDF file.
- CDF_INFO_TO_TPLOT
- CDF_LOAD_VARS
- CDF_SAVE_VARS
- CDF_SET_CDF27
  Call CDF_SET_CDF27_BACKWARD_COMPATIBLE but don't bomb unnecessarily when
- CDF_VAR_ATTS
  Returns a structure that contains all the attributes of a variable within
- IDL2CDFTYPE
  Given an IDL variable, return the appropriate CDF type code
- MAG_STS_TO_CDF
  Convert magnetometer .sts to .cdf.
- MAKE_CDF_INDEX
  Creates an index file for CDF files.
- PRINT_CDF_INFO
- SPD_CDF2TPLOT
- SPD_CDF_INFO_TO_TPLOT
- SPD_MMS_CDF_LOAD_VARS
- SPD_UNH_MMS_FILE_FILTER
- TPLOT2CDF
  Save tplot variables into cdf file
- TPLOT2CDF_SAVE_VARS
  To dump data and metadata from an IDL structure into a CDF file.
- TPLOT_ADD_CDF_STRUCTURE
  In order to be saved in CDF file using TPLOT2CDF, tplot variable must have CDF

# Routine Descriptions

## CDF2IDLTYPE

[Next Routine] [List of Routines]

    NAME:
     cdf2idltype
    PURPOSE:
     Return an IDL type number given a CDF data type
    CALLING SEQUENCE:
     idl_type = cdf2idltype(code)
    INPUT:
     code = the CDF data type code for that variable
    OUTPUT:
     idl_type = the type number for the appropriate IDL variable
     CDF_TYPE      IDL_TYPE
    'CDF_UINT1'    1 (byte)
    'CDF_UCHAR'    1 (byte)
    'CDF_BYTE'     2 (int)
    'CDF_INT1'     2 (int)
    'CDF_INT2'     2 (int)
    'CDF_INT4'     3 (long)
    'CDF_FLOAT'    4 (float)
    'CDF_REAL4'    4 (float)
    'CDF_DOUBLE'   5 (double)
    'CDF_REAL8'    5 (double)
    'CDF_CHAR'     7 (string)
    'CDF_UINT2'    12 (unsigned int)
    'CDF_UINT4'    13 (unsigned long)
    'CDF_INT8'     14 (long64)
    'CDF_UINT8'    15 (unsigned long64)
     There are some CDF types that have no corresponding IDL type,
     e.g., CDF_BYTE and CDF_INT1 are signed bytes, here we return a type
     code of 2 (signed integer), The EPOCH and TT2000 are not handled
     here, and will return a code of 0
    HISTORY:
     26-nov-2013, jmm, jimm@ssl.berkeley.edu
     30-apr-2019, jmm, Added comment to test SVN updates
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-04-30 15:30:35 -0700 (Tue, 30 Apr 2019) $
     $LastChangedRevision: 27152 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf2idltype.pro $

(See general/CDF/cdf2idltype.pro)

## CDF2TPLOT

[Previous Routine] [Next Routine] [List of Routines]

    CDF2TPLOT ,files,varformat=varformat

    Keywords:

     VARFORMAT = PATTERN  ; PATTERN should be a string (wildcards accepted) that will match the CDF variable that should be made into tplot variables
     PREFIX = STRING      ; String that will be pre-pended to all tplot variable names.
     SUFFIX = STRING      ; String appended to end of each tplot variable name
     MIDFIX = STRING      ; String in the middle of each tplot variable name
     MIDPOS = STRING/NUMBER ; A position for the midfix, either a string
                              to be replaced by the midfix, or a position
                              at which the midfix is inserted
     VARNAMES = named variable ; CDF variable names are returned in this variable
     /GET_SUPPORT_DATA    ; Often required to get support data if the CDF file does not have all the needed depend attributes

     record=record if only one record and not full cdf-file is requested
     /ALL ; Retrun all variables
     /CONVERT_INT1_TO_INT2 ; Set this keyword to convert signed one byte to signed 2 byte integers.
                             This is useful because IDL does not have the equivalent of INT1   (bytes are unsigned)
     TPLOTNAMES = STRING   ; The names of the tplot variables (not the
                             CDF variables, which are returned in varnames)
     load_labels=load_labels ;copy labels from labl_ptr_1 in attributes into dlimits
             resolve labels implemented as keyword to preserve backwards
             compatibility.
     smex_epoch=if set, interpret variables called "epoch" or "time" as seconds
                from 1968-05-24, rather than the CDF EPoch variable or Unix time,
                needed to read CDF files created by SDT
    NOTES:
     CDF attributes are obtained from the first file in the array of files input.
     To load attributes from a separate SPDF-style mastercdf, prepend the
     files input with the name of the mastercdf, full-path please.

    Author: Davin Larson -  20th century

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2025-06-12 05:10:17 -0700 (Thu, 12 Jun 2025) $
     $LastChangedRevision: 33384 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf2tplot.pro $
     $ID: $

(See general/CDF/cdf2tplot.pro)

## CDF_DEFAULT_CDFI_STRUCTURE

[Previous Routine] [Next Routine] [List of Routines]

    PURPOSE:
     Number of functions that generate default structures for CDF files
     This file is designed for developers

     Please use TPLOT_ADD_CDF_STRUCTURE instead

    CREATED BY:
      Alexander Drozdov

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-02-12 12:13:23 -0800 (Mon, 12 Feb 2018) $
     $LastChangedRevision: 24690 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_default_cdfi_structure.pro $

(See general/CDF/cdf_default_cdfi_structure.pro)

## CDF_INFO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:  cdf_info
    FUNCTION:   cdf_info(id)
    PURPOSE:
      Returns a structure with useful information about a CDF file.
      In particular the number of file records is returned in this structure.
    INPUT:
       id:   CDF file ID.
    CREATED BY:    Davin Larson
     $LastChangedBy: ali $
     $LastChangedDate: 2020-03-04 13:03:28 -0800 (Wed, 04 Mar 2020) $
     $LastChangedRevision: 28371 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_info.pro $

(See general/CDF/cdf_info.pro)

## CDF_INFO_TO_TPLOT

[Previous Routine] [Next Routine] [List of Routines]

     This is a new routine that needs further testing, development, and enhancements.
     PROCEDURE:  cdf2tplot, cdfi
     Purpose:  Creates TPLOT variables from a CDF structure (obtained from "CDF_LOAD_VAR")
     This routine will only work well if the underlying CDF file follows the SPDF standard.

     Written by Davin Larson

     $LastChangedBy: jimm $
     $LastChangedDate: 2024-07-09 11:03:46 -0700 (Tue, 09 Jul 2024) $
     $LastChangedRevision: 32730 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_info_to_tplot.pro $

(See general/CDF/cdf_info_to_tplot.pro)

## CDF_LOAD_VARS

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION cdfi = cdf_load_vars(file)
     INPUT:
       file = CDF filename(s)
     OUTPUT:
       CDFI = A structure containing pointers to the data and attributes
              for the files, with tags:
       CDFI.FILENAME = The filename(s)

       CDFI.INQ = A structure with information about the file:
       CDFI.INQ.NDIMS = CDF Dims attribute, for rVariables typically 0
                      (rVariables are rarely used anymore See http://cdf.gsfc.nasa.gov/html/FAQ.html#intro)
       CDFI.INQ.DECODING = 'HOST_DECODING' (can be network or host)
       CDFI.INQ.ENCODING = 'NETWORK_ENCODING' (can be network or host)
       CDFI.INQ.MAJORITY = 'ROW_MAJOR' (can be row or column)
       CDFI.INQ.MAXREC = Max number of records (Default is -1)
       CDFI.INQ.NVARS =  number of rVariables, usually 0
       CDFI.INQ.NZVARS = number of zVariables, usually all of them
       CDFI.INQ.NATTS = number of variable attributes
       CDFI.INQ.DIM = dimensions of rVariables

       CDFI.g_atttributes = CDF global attributes, structure varies
       Here is a sample from THEMIS EFI:

       PROJECT         STRING    'THEMIS'
       SOURCE_NAME     STRING    'THA>Themis Probe A'
       DISCIPLINE      STRING    'Space Physics>Magnetospheric Science'
       DATA_TYPE       STRING    'EFI'
       DESCRIPTOR      STRING    'L2>L2 DATA'
       DATA_VERSION    STRING    '1'
       PI_NAME         STRING    'V. Angelopoulos, J. Bonnell & F. Mozer'
       PI_AFFILIATION  STRING    'UCB, NASA NAS5-02099'
       TITLE           STRING    'Electric Field Instrument (EFI) Measurements'
       TEXT            STRING    'THEMIS-A: Electric Field Instrument (EFI) Electric field measurements. The L2 product is a 3D estimate of'...
       INSTRUMENT_TYPE STRING    'Electric Fields (space)'
       MISSION_GROUP   STRING    'THEMIS'
       LOGICAL_SOURCE  STRING    'tha_l2_efi'
       LOGICAL_FILE_ID STRING    'tha_l2_efi_20131001_v01'
       LOGICAL_SOURCE_DESCRIPTION
                       STRING    'Spacecraft-collected (EFI) Electric field'
       TIME_RESOLUTION STRING    '3-1/8s'
       RULES_OF_USE    STRING    'Open Data for Scientific Use'
       GENERATED_BY    STRING    'THEMIS SOC'
       GENERATION_DATE STRING    'Sun Oct  6 03:11:38 2013'
       ACKNOWLEDGEMENT STRING    'NASA Contract NAS5-02099'
       MODS            STRING    'Rev- 2009-09-16'
       ADID_REF        STRING    'NSSD0110'
       LINK_TEXT       STRING    Array[3]
       LINK_TITLE      STRING    Array[3]
       HTTP_LINK       STRING    Array[3]
       FILE_NAMING_CONVENTION
                       STRING    'source_descriptor_datatype'
       CAVEATS         STRING    'See THEMIS website for caveats'
       VALIDITY        STRING    'to be validated'
       VALIDATOR       STRING    'tbd'
       VALIDATE        STRING    'Compatible with the ISTP CDF Standards'
       INST_MOD        STRING    'THM>xxxx'
       PARENTS         STRING    'xxxx'
       INST_SETTINGS   STRING    'Not used'
       SOFTWARE_VERSION
                       STRING    '13273'

      CDFI.NV = Number of variables

      CDFI.VARS = AN array of CDFI.NV structures, one for each zvariable:
      CDFI.VARS.NAME = The variable name
      CDFI.VARS.NUM  = The index of the given variable in the cdfi.vars array
      CDFI.VARS.IS_ZVAR = 1 for a zVariable
      CDFI.VARS.DATATYPE = The data type, e.g.'CDF_FLOAT'
      CDFI.VARS.TYPE = The nummerical IDL data type (float is 4, etc...)
      CDFI.VARS.NUMATTR = -1,  Not sure about this one, returned from CDF_VARGET
      CDFI.VARS.NUMELEM = Number of elements in a record, returned from CDF_VARGET
      CDFI.VARS.RECVARY = Set to 1 if variable varies from record to record
      CDFI.VARS.NUMREC = the number of records input.
      CDFI.VARS.NDIMEN = the number dimensions in the data
      CDFI.VARS.D = A six-element array with the number of dimensions for
                    each index
      CDFI.VARS.DATAPTR = A pointer to the data array:
      CDFI.VARS.ATTRPTR  = A pointer to the variable attributes
                           structure for each variable. Content varies,
                           here is a sample from THEMIS EFI Electric
                           field data:
       CATDESC         STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FIELDNAM        STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FILLVAL         FLOAT               NaN
       VALIDMIN        FLOAT     Array[3]
       VALIDMAX        FLOAT     Array[3]
       VAR_TYPE        STRING    'data'
       DISPLAY_TYPE    STRING    'time_series'
       FORMAT          STRING    'E13.6'
       LABL_PTR_1      STRING    'tha_eff_dot0_gsm_labl'
       UNITS           STRING    'mV/m'
       DEPEND_TIME     STRING    'tha_eff_dot0_time'
       DEPEND_EPOCH0   STRING    'tha_eff_dot0_epoch0'
       DEPEND_0        STRING    'tha_eff_dot0_epoch'
       DEPEND_1        STRING    'tha_eff_dot0_gsm_compno'
       VAR_NOTES       STRING    'Units are in mV/m'
       COORDINATE_SYSTEM
                       STRING    'GSM'
       REPRESENTATION_1
                       STRING    'Rep_xyz_gsm'
       TENSOR_ORDER    STRING    '1'
       AVG_TYPE        STRING    'standard'
       PROPERTY        STRING    'vector'
       SC_ID           STRING    'a'
       SCALE_TYP       STRING    'linear'
       DICT_KEY        STRING    'electric_field>vector_GSM'
       SI_CONVERSION   STRING    '1e-3>V/m'
       LABEL_1         STRING    'tha_eff_dot0_gsm_labl'

     Each variable may have a different set of attributes, but this
     example is a minimal structure that will be ISTP compliant.

     KEYWORDS:
       VARFORMAT = string or string array:  a string or string array (which may contain wildcard
                             characters) that specifies the CDF variable names to load.  Use
                              'VARFORMAT='*' to load all variables. NOTE
                              THAT VARFORMAT MUST BE SET IF YOU ACTUALLY
                              WANT TO READ DATA.
       VARNAMES = named variable   ;output variable for variable names that were loaded.
       SPDF_DEPENDENCIES :   Set to 1 to have SPDF defined dependent variables also loaded.
       VAR_TYPE = string or string array;  Variables that have a VAR_TYPE matching these strings will
                             be loaded.
       CONVERT_INT1_TO_INT2  Set this keyword to convert signed one byte to signed 2 byte integers.
                             This is useful because IDL does not have the equivalent of INT1   (bytes are unsigned)
       RECORD: Specify the record index where you want to start reading.  By default, this option will read one record.
       NUMBER_RECORDS: Specify the number of records that you want to read.  By default, this option will begin at record zero.

     Note: Record & Number_Records can be used together to specify a range of records to be read.

     Author: Davin Larson - 2006

     Side Effects:
       Data is returned in pointer variables. Calling routine is responsible for freeing up heap memory - otherwise a memory leak will occur.

     $LastChangedBy: ali $
     $LastChangedDate: 2021-05-30 19:45:35 -0700 (Sun, 30 May 2021) $
     $LastChangedRevision: 30010 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_load_vars.pro $
     $ID: $

(See general/CDF/cdf_load_vars.pro)

## CDF_SAVE_VARS

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION: dummy = cdf_save_vars(cdf_structure,new_cdf_name)
     PURPOSE:  To dump data and metadata from an IDL structure into a CDF file.
    		The structure format is the structure produced by cdf_load_vars.pro
     INPUTS:   cdf_structure : IDL structure defined by cdf_load_vars.pro
    	    new_cdf_name  : a string to name the new CDF file with

    	    compress_cdf: if this is set, the produced cdf is compressed
    	    cdfconvert: (optional) location of cdfconvert utility (eg. /usr/local/pkg/cdf-3.6.1_CentOS-6.6/bin/cdfconvert)
    	    cdfparams: (optional) cdf compression parameters
    	    cdf_compress_error: (optional) return string for compression errors
    	    cdf_tmp_dir: (optional) compression uses this directory for temporary files

     OUTPUTS:  CDF file named by the new_cdf_name input
     EXAMPLE:  dummy = cdf_save_vars(cdfi,'newcdf.cdf')

     Written by: Matt Davis

    Note: To use this routine you must have the CDF_EPOCH/CDF_EPOCH16 bug patch on your IDL6.3
    and if you are using Solaris you need to be in 32-bit mode NOT 64-bit (ie, idl -32)

(See general/CDF/cdf_save_vars.pro)

## CDF_SET_CDF27

[Previous Routine] [Next Routine] [List of Routines]

     NAME: cdf_set_cdf27
     SYNTAX:
       cdf_set_cdf27 [, /yes | /no]
     PURPOSE:
       Call CDF_SET_CDF27_BACKWARD_COMPATIBLE but don't bomb unnecessarily when
       run on an (unpatched) pre-IDL 6.3, pre-CDF 3.1 installation of IDL.
     VERSION:
       $LastChangedBy: adrozdov $
       $LastChangedDate: 2018-01-23 20:38:14 -0800 (Tue, 23 Jan 2018) $
       $LastChangedRevision: 24575 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_set_cdf27.pro $

(See general/CDF/cdf_set_cdf27.pro)

## CDF_VAR_ATTS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:  cdf_var_atts
    FUNCTION:   cdf_var_atts(id [,var[,attname]])
    PURPOSE:
      Returns a structure that contains all the attributes of a variable within
      a CDF file. If attname is provided then it returns the value of only that attribute.
    KEYWORDS:
      DEFAULT: The default value of the attribute.
      ATTRIBUTES=att  A named variable that returns an array of structures containing attribute info
                      if this variable is passed in on subsequent calls to cdf_var_atts it can significantly
                      improve performance.   OBSOLETE!!!
    USAGE:
       atts = cdf_var_atts(file)  ; returns structure containing all global attributes
       atts = cdf_var_atts(file
    INPUT:
       id:         CDF file ID or filename.
       var;        CDF variable name or number
       attname:    CDF attribute name

    CREATED BY:    Davin Larson
     $LastChangedBy: crussell $
     $LastChangedDate: 2025-02-25 05:06:52 -0800 (Tue, 25 Feb 2025) $
     $LastChangedRevision: 33149 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/cdf_var_atts.pro $

(See general/CDF/cdf_var_atts.pro)

## IDL2CDFTYPE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     idl2cdftype
    PURPOSE:
     Given an IDL variable, return the appropriate CDF type code
    CALLING SEQUENCE:
     code = idl2cdftype(var, format_out=format_out,
            fillval_out=fillval_out, validmin_out=validmin_out,
            validmax_out=validmax_out)
    INPUT:
     var = an IDL variable
    OUTPUT:
     code = the CDF data type code for that variable, if applicable, for
            objects, complex,  and similar vars a null string is returned.
        IDL_TYPE             CDF_TYPE
        1 (byte)             'CDF_UINT1'
        2 (int)              'CDF_INT2'
        3 (long)             'CDF_INT4'
        4 (float)            'CDF_FLOAT'
        5 (double)           'CDF_DOUBLE'
        7 (string)           'CDF_CHAR'
        12 (unsigned int)    'CDF_UINT2'
        13 (unsigned long)   'CDF_UINT4'
        14 (long64)          'CDF_INT8'
        15 (unsigned long64) 'CDF_UINT8'
    KEYWORDS:
     format_out = return a format code for the data type
        1 (byte)             'I4'
        2 (int)              'I6'
        3 (long)             'I10'
        4 (float)            'E13.6'
        5 (double)           'E20.12'
        7 (string)           strlen(value)
        12 (unsigned int)    'I6'
        13 (unsigned long)   'I10'
        14 (long64)          'I20'
        15 (unsigned long64) 'I20'
     fillval_out = a fill value
        1 (byte)             255
        2 (int)              -32768
        3 (long)             -2147483648
        4 (float)            !values.f_nan
        5 (double)           !values.d_nan
        7 (string)           ''
        12 (unsigned int)    65535
        13 (unsigned long)   4294967295
        14 (long64)          -9223372036854775808
        15 (unsigned long64) 18446744073709551615
     validmin_out = a min value
        1 (byte)             0
        2 (int)              -32768
        3 (long)             -2147483648
        4 (float)            -1.0e38
        5 (double)           -1.0e308
        7 (string)           'NA'
        12 (unsigned int)    0
        13 (unsigned long)   0
        14 (long64)          -9223372036854775808
        15 (unsigned long64) 0
     validmax_out = a max value
        1 (byte)             255
        2 (int)              32767
        3 (long)             2147483647
        4 (float)            1.0e38
        5 (double)           1.0e308
        7 (string)           'NA'
        12 (unsigned int)    65535
        13 (unsigned long)   4294967295
        14 (long64)          -9223372036854775808
        15 (unsigned long64) 18446744073709551615
    HISTORY:
     26-nov-2013, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-03-07 15:07:03 -0800 (Tue, 07 Mar 2023) $
     $LastChangedRevision: 31598 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/idl2cdftype.pro $

(See general/CDF/idl2cdftype.pro)

## MAG_STS_TO_CDF

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
    	MAG_STS_TO_CDF

     PURPOSE:
    	Convert magnetometer .sts to .cdf.

     AUTHOR:
    	Roberto Livi (rlilvi@ssl.Berkeley.edu)

     CALLING SEQUENCE:
    	MAG_STS_TO_CDF,FILENAME=FILENAME

     KEYWORDS:
    	FILENAME: String containing .sts filename to be loaded

     NOTES:
          Uses append_array.pro

     EXAMPLE:
            IDL> dir='/directory-to-mag-files/'
            IDL> file='mvn_mag_l2_2014d106pl_20140416_v00_r00.sts'
            IDL> mag_sts_to_cdf, dir+file

     HISTORY:

     VERSION:
       $LastChangedBy: nikos $
       $LastChangedDate: 2014-10-03 15:10:00 -0500 (Fri, 03 Otc 2014)$
       $LastChangedRevision: 2014-10-03 15:10:00 -0500 (Fri, 03 Otc 2014)$
       $URL:svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/projects/general/CDF/mag_sts_to_cdf.pro$

(See general/CDF/mag_sts_to_cdf.pro)

## MAKE_CDF_INDEX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      make_cdf_index
    PROCEDURE:
      make_cdf_index,  [pattern]
    PURPOSE:
      Creates an index file for CDF files.
      The index file will have one line for each CDF file found.
      Each line contains the start time, end time and filename
      with the following format:
    YYYY-MM-DD/hh:mm:ss  YYYY-MM-DD/hh:mm:ss   fullpathname.cdf
      CDF files may be distributed over many directories or disks.

    INPUT:
      pattern:  (string) file pattern, default is:  '*.cdf'
    KEYWORDS:
      DATA_DIREC  (string) data directory(s)
      INDEX_FILENAME:  (string) Name of index file to be created.
      NO_DUPLICATES:   Set to 1 if duplicate days are to be ignored.
    SEE ALSO:
      "makecdf","loadcdf","loadcdfstr","loadallcdf",
    CREATED BY:
      Davin Larson,  August 1996
    VERSION:
      02/04/17  make_cdf_index.pro  1.5

(See general/CDF/make_cdf_index.pro)

## PRINT_CDF_INFO

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:     print_cdf_info
    PURPOSE:   prints information about a specified cdf file
    INPUT:
       filename: The name of the file for which info is desired.
    KEYWORDS:
       none

    CREATED BY:    D. Larson
     $LastChangedBy: ali $
     $LastChangedDate: 2021-05-30 19:45:35 -0700 (Sun, 30 May 2021) $
     $LastChangedRevision: 30010 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/print_cdf_info.pro $

(See general/CDF/print_cdf_info.pro)

## SPD_CDF2TPLOT

[Previous Routine] [Next Routine] [List of Routines]

    spd_cdf2tplot ,files,varformat=varformat

    Keywords:

     VARFORMAT = PATTERN  ; PATTERN should be a string (wildcards accepted) that will match the CDF variable that should be made into tplot variables
     PREFIX = STRING      ; String that will be pre-pended to all tplot variable names.
     SUFFIX = STRING      ; String appended to end of each tplot variable created.
     VARNAMES = named variable ; CDF variable names are returned in this variable
     /GET_SUPPORT_DATA    ; Often required to get support data if the CDF file does not have all the needed depend attributes
     /TT2000              ; Keep TT200 time in unsigned long format

     record=record if only one record and not full cdf-file is requested

    load_labels=load_labels ;copy labels from labl_ptr_1 in attributes into dlimits
             resolve labels implemented as keyword to preserve backwards compatibility

     NOTE:
       The used function spd_cdf_info_to_tplot rely on the order of the variables
       in the cdf file. According to ISTP/IACG guidelines "Epoch" should be the
       first variable in each CDF data set.
       https://spdf.gsfc.nasa.gov/istp_guide/variables.html#Epoch

     Author: Davin Larson -  20th century
       Forked from MMS, 04/09/2018, adrozdov

     $LastChangedBy: nikos $
     $LastChangedDate: 2021-06-10 14:39:13 -0700 (Thu, 10 Jun 2021) $
     $LastChangedRevision: 30039 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/spd_cdf2tplot.pro $

(See general/CDF/spd_cdf2tplot.pro)

## SPD_CDF_INFO_TO_TPLOT

[Previous Routine] [Next Routine] [List of Routines]

     This is a new routine that needs further testing, development, and enhancements.
     PROCEDURE:  spd_cdf_info_to_tplot, cdfi
     Purpose:  Creates TPLOT variables from a CDF structure (obtained from "CDF_LOAD_VAR")
     This routine will only work well if the underlying CDF file follows the SPDF standard.

    Keywords:
       /TT2000              ; Keep TT200 time in unsigned long format

     Written by Davin Larson
       Forked from MMS, 04/09/2018, adrozdov
       According to ISTP/IACG guidelines "Epoch" should be the first variable in each CDF data set.
       https://spdf.gsfc.nasa.gov/istp_guide/variables.html#Epoch

     $LastChangedBy: jwl $
     $LastChangedDate: 2023-08-14 17:59:53 -0700 (Mon, 14 Aug 2023) $
     $LastChangedRevision: 32000 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/spd_cdf_info_to_tplot.pro $

(See general/CDF/spd_cdf_info_to_tplot.pro)

## SPD_MMS_CDF_LOAD_VARS

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION cdfi = spd_mms_cdf_load_vars(file)
     INPUT:
       file = CDF filename(s)
     OUTPUT:
       CDFI = A structure containing pointers to the data and attributes
              for the files, with tags:
       CDFI.FILENAME = The filename(s)

       CDFI.INQ = A structure with information about the file:
       CDFI.INQ.NDIMS = CDF Dims attribute, for rVariables typically 0
                      (rVariables are rarely used anymore See http://cdf.gsfc.nasa.gov/html/FAQ.html#intro)
       CDFI.INQ.DECODING = 'HOST_DECODING' (can be network or host)
       CDFI.INQ.ENCODING = 'NETWORK_ENCODING' (can be network or host)
       CDFI.INQ.MAJORITY = 'ROW_MAJOR' (can be row or column)
       CDFI.INQ.MAXREC = Max number of records (Default is -1)
       CDFI.INQ.NVARS =  number of rVariables, usually 0
       CDFI.INQ.NZVARS = number of zVariables, usually all of them
       CDFI.INQ.NATTS = number of variable attributes
       CDFI.INQ.DIM = dimensions of rVariables

       CDFI.g_atttributes = CDF global attributes, structure varies
       Here is a sample from THEMIS EFI:

       PROJECT         STRING    'THEMIS'
       SOURCE_NAME     STRING    'THA>Themis Probe A'
       DISCIPLINE      STRING    'Space Physics>Magnetospheric Science'
       DATA_TYPE       STRING    'EFI'
       DESCRIPTOR      STRING    'L2>L2 DATA'
       DATA_VERSION    STRING    '1'
       PI_NAME         STRING    'V. Angelopoulos, J. Bonnell & F. Mozer'
       PI_AFFILIATION  STRING    'UCB, NASA NAS5-02099'
       TITLE           STRING    'Electric Field Instrument (EFI) Measurements'
       TEXT            STRING    'THEMIS-A: Electric Field Instrument (EFI) Electric field measurements. The L2 product is a 3D estimate of'...
       INSTRUMENT_TYPE STRING    'Electric Fields (space)'
       MISSION_GROUP   STRING    'THEMIS'
       LOGICAL_SOURCE  STRING    'tha_l2_efi'
       LOGICAL_FILE_ID STRING    'tha_l2_efi_20131001_v01'
       LOGICAL_SOURCE_DESCRIPTION
                       STRING    'Spacecraft-collected (EFI) Electric field'
       TIME_RESOLUTION STRING    '3-1/8s'
       RULES_OF_USE    STRING    'Open Data for Scientific Use'
       GENERATED_BY    STRING    'THEMIS SOC'
       GENERATION_DATE STRING    'Sun Oct  6 03:11:38 2013'
       ACKNOWLEDGEMENT STRING    'NASA Contract NAS5-02099'
       MODS            STRING    'Rev- 2009-09-16'
       ADID_REF        STRING    'NSSD0110'
       LINK_TEXT       STRING    Array[3]
       LINK_TITLE      STRING    Array[3]
       HTTP_LINK       STRING    Array[3]
       FILE_NAMING_CONVENTION
                       STRING    'source_descriptor_datatype'
       CAVEATS         STRING    'See THEMIS website for caveats'
       VALIDITY        STRING    'to be validated'
       VALIDATOR       STRING    'tbd'
       VALIDATE        STRING    'Compatible with the ISTP CDF Standards'
       INST_MOD        STRING    'THM>xxxx'
       PARENTS         STRING    'xxxx'
       INST_SETTINGS   STRING    'Not used'
       SOFTWARE_VERSION
                       STRING    '13273'

      CDFI.NV = Number of variables

      CDFI.VARS = AN array of CDFI.NV structures, one for each zvariable:
      CDFI.VARS.NAME = The variable name
      CDFI.VARS.NUM  = The index of the given variable in the cdfi.vars array
      CDFI.VARS.IS_ZVAR = 1 for a zVariable
      CDFI.VARS.DATATYPE = The data type, e.g.'CDF_FLOAT'
      CDFI.VARS.TYPE = The numerical IDL data type (float is 4, etc...)
      CDFI.VARS.NUMATTR = -1,  Not sure about this one, returned from CDF_VARGET
      CDFI.VARS.NUMELEM = Number of elements in a record, returned from CDF_VARGET
      CDFI.VARS.RECVARY = Set to 1 if variable varies from record to record
      CDFI.VARS.NUMREC = the number of records input.
      CDFI.VARS.NDIMEN = the number dimensions in the data
      CDFI.VARS.D = A six-element array with the number of dimensions for
                    each index
      CDFI.VARS.DATAPTR = A pointer to the data array:
      CDFI.VARS.ATTRPTR  = A pointer to the variable attributes
                           structure for each variable. Content varies,
                           here is a sample from THEMIS EFI Electric
                           field data:
       CATDESC         STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FIELDNAM        STRING    'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
       FILLVAL         FLOAT               NaN
       VALIDMIN        FLOAT     Array[3]
       VALIDMAX        FLOAT     Array[3]
       VAR_TYPE        STRING    'data'
       DISPLAY_TYPE    STRING    'time_series'
       FORMAT          STRING    'E13.6'
       LABL_PTR_1      STRING    'tha_eff_dot0_gsm_labl'
       UNITS           STRING    'mV/m'
       DEPEND_TIME     STRING    'tha_eff_dot0_time'
       DEPEND_EPOCH0   STRING    'tha_eff_dot0_epoch0'
       DEPEND_0        STRING    'tha_eff_dot0_epoch'
       DEPEND_1        STRING    'tha_eff_dot0_gsm_compno'
       VAR_NOTES       STRING    'Units are in mV/m'
       COORDINATE_SYSTEM
                       STRING    'GSM'
       REPRESENTATION_1
                       STRING    'Rep_xyz_gsm'
       TENSOR_ORDER    STRING    '1'
       AVG_TYPE        STRING    'standard'
       PROPERTY        STRING    'vector'
       SC_ID           STRING    'a'
       SCALE_TYP       STRING    'linear'
       DICT_KEY        STRING    'electric_field>vector_GSM'
       SI_CONVERSION   STRING    '1e-3>V/m'
       LABEL_1         STRING    'tha_eff_dot0_gsm_labl'

     Each variable may have a different set of attributes, but this
     example is a minimal structure that will be ISTP compliant.

     KEYWORDS:
       VARFORMAT = string or string array:  a string or string array (which may contain wildcard
                             characters) that specifies the CDF variable names to load.  Use
                              'VARFORMAT='*' to load all variables. NOTE
                              THAT VARFORMAT MUST BE SET IF YOU ACTUALLY
                              WANT TO READ DATA.
       VARNAMES = named variable   ;output variable for variable names that were loaded.
       SPDF_DEPENDENCIES :   Set to 1 to have SPDF defined dependent variables also loaded.
       VAR_TYPE = string or string array;  Variables that have a VAR_TYPE matching these strings will
                             be loaded.
       CONVERT_INT1_TO_INT2  Set this keyword to convert signed one byte to signed 2 byte integers.
                             This is useful because IDL does not have the equivalent of INT1   (bytes are unsigned)
       RECORD: Specify the record index where you want to start reading.  By default, this option will read one record.
       NUMBER_RECORDS: Specify the number of records that you want to read.  By default, this option will begin at record zero.

     Note: Record & Number_Records can be used together to specify a range of records to be read.

     Author: Davin Larson - 2006
     Forked for MMS, 10/22/2015, egrimes@igpp
     Forked and renamed for SPEDAS general (to keep general self-contained), jwl@ssl

     Side Effects:
       Data is returned in pointer variables. Calling routine is responsible for freeing up heap memory - otherwise a memory leak will occur.

     $LastChangedBy: jwl $
     $LastChangedDate: 2023-08-04 11:32:16 -0700 (Fri, 04 Aug 2023) $
     $LastChangedRevision: 31982 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/spd_mms_cdf_load_vars.pro $

(See general/CDF/spd_mms_cdf_load_vars.pro)

## SPD_UNH_MMS_FILE_FILTER

[Previous Routine] [Next Routine] [List of Routines]

       Filter MMS file names by time and version. File names are assumed to be identical
       except in the TSTART and VERSION fields.

     :Params:
           FILENAMES:      in, required, type=string/strarr
                           Names of files to be filtered.

     :Keywords:
           COUNT:          out, optional, type=integer
                           Number of output files that passed filter.
           TRANGE:         in, optional, type=strarr(2), default=time_string(timerange())
                           Time interval over which to select files.
           MAJOR_VERSION:  in, optional, type=boolean, default=0
                           If set, only the latest major version of each file is returned. Cannot
                               be used with `MIN_VERSION`, LATEST_VERSION or `VERSION`
           LATEST_VERSION: in, optional, type=boolean, default=0
                           If set, only the latest version of each file is returned. Cannot
                               be used with `MIN_VERSION` or `VERSION`
           MIN_VERSION:    in, optional, type=string
                           Minimum file version to accept, formatted as 'X.Y.Z', where
                               X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
                               or `VERSION`.
           VERSION:        in, optional, type=string
                           Version of files to accept, formatted as 'X.Y.Z', where
                               X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
                               or `MIN_VERSION`.

     :Returns:
           FILES_OUT:      Those files within `FILENAMES` that pass the filter criterion.

           LOADED_VERSIONS: The CDF version #s

      Forked and renamed from MMS for SPEDAS general (to keep general self-contained) -- jwl@ssl

     $LastChangedBy: jwl $
     $LastChangedDate: 2019-04-26 16:14:42 -0700 (Fri, 26 Apr 2019) $
     $LastChangedRevision: 27107 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/spd_unh_mms_file_filter.pro $

(See general/CDF/spd_unh_mms_file_filter.pro)

## TPLOT2CDF

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      TPLOT2CDF, ...

    PURPOSE:
      Save tplot variables into cdf file
      tplot variable must have appropriate CDF structure as the option (limits) (see TPLOT_ADD_CDF_STRUCTURE, OPTIONS)
      Time (x variable of tplot) must be in SPEDAS (unix) format if TT2000 keyword is not specified, (see TIME_DOUBLE)

    KEYWORDS:
       FILENAME: (string) Name of the cdf file to be saved. .cdf extension can be omitted.
       TVARS: (string or array of strings) Tplot variable name, or list of the tplot variables to be saved
       DEFAULT_CDF_STRUCTURE: (flag) Create default CDF structure in tplot variables
       COMPRESS_CDF: (int) Compress CDF file. See CDF_COMPRESSION
       G_ATTRIBUTES: (struct) Global attributes of CDF file
       TT2000: (flag) Indicates that time is in TT2000 format.

      Additional keywords:
       INQ: (struct) Structure of CDF file parameters, see TPLOT2CDF_SAVE_VARS code

    EXAMPLES:
       store_date, 'example_tplot',data={x:time_double('2001-01-01')+[1, 2, 3],y:[10, 20, 30]}
       tplot2cdf, filename='example_cdf_file', tvars='example_plot', /default

       store_date, 'example_tplot2',data={x:time_double('2001-01-02')+[1, 2],y:[10, 20]}
       tplot2cdf, filename='example_cdf_file2', tvars=['example_plot', 'example_tplot2'], /default

      See crib_tplot2cdf_basic for additional examples

    CREATED BY:
      Alexander Drozdov

     $LastChangedBy: haraday $
     $LastChangedDate: 2024-03-26 01:20:29 -0700 (Tue, 26 Mar 2024) $
     $LastChangedRevision: 32507 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/tplot2cdf.pro $

(See general/CDF/tplot2cdf.pro)

## TPLOT2CDF_SAVE_VARS

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
        tplot2cdf_save_vars(cdf_structure,new_cdf_name)
     PURPOSE:
        To dump data and metadata from an IDL structure into a CDF file.
    		 This is a fork of the cdf_load_vars.pro!

     INPUTS:
         cdf_structure : IDL structure defined by cdf_load_vars.pro
    	    new_cdf_name  : a string to name the new CDF file with

    	    compress_cdf: if this is set, the produced cdf is compressed
    	    cdfconvert: (optional) location of cdfconvert utility (eg. /usr/local/pkg/cdf-3.6.1_CentOS-6.6/bin/cdfconvert)
    	    cdfparams: (optional) cdf compression parameters
    	    cdf_compress_error: (optional) return string for compression errors
    	    cdf_tmp_dir: (optional) compression uses this directory for temporary files
     EXAMPLE:
         cdf_save_vars(cdfi,'newcdf.cdf')

    Note: To use this routine you must have the CDF_EPOCH/CDF_EPOCH16 bug patch on your IDL6.3
    and if you are using Solaris you need to be in 32-bit mode NOT 64-bit (ie, idl -32)

    CREATED BY:
      Alexander Drozdov

     $LastChangedBy: egrimes $
     $LastChangedDate: 2020-12-15 12:11:10 -0800 (Tue, 15 Dec 2020) $
     $LastChangedRevision: 29486 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/tplot2cdf_save_vars.pro $

(See general/CDF/tplot2cdf_save_vars.pro)

## TPLOT_ADD_CDF_STRUCTURE

[Previous Routine] [List of Routines]

    PROCEDURE:
      TPLOT_ADD_CDF_STRUCTURE, tplot_vars, ...

    PURPOSE:
      In order to be saved in CDF file using TPLOT2CDF, tplot variable must have CDF
      structure as a tplot option (see OPTIONS)
      The attributes of the tplot data (x, y or v) are stored in the CDF structure
      CDF.VARS     - structure of attributes that describe the data (tplot y variable)
      CDF.DEPEND_0 - structure of attributes that describe the time (tplot x variable)
      CDF.DEPEND_1 - structure of attributes that supporting data (tplot v or v1 variable)
      CDF.DEPEND_2 - structure of attributes that supporting data (tplot v2 variable)
      CDF.DEPEND_3 - structure of attributes that supporting data (tplot v3 variable)

      Each structure of attributes must have following fileds:
      CATDESC, DISPLAY_TYPE ,FIELDNAM, LABLAXIS, UNITS (automatically defined for time), VAR_TYPE
      FILLVAL, VALIDMIN, VALIDMAX, FORMAT defined based on the nature of the data

      If CDF structure already defined in the tplot variable the defined fields of
      the CDF strucutre will remane the same. This means, if there was any mistake
      (e.g. wrong Epoch format), then CDF structure must be recreated (for example, using /new keyword).

      TPLOT_ADD_CDF_STRUCTURE adds appropriate CDF structure and defines some of the attributes base on the tplot data
      This procedure must be called before tplot2cdf. Alternatively, keyword /default of tplto2cdf2 can be used.
      Most of the attributes are defined as 'undefined' ans should be specify.

      If tplot has 2d y, but variable v, that suppose to describe second dimension
      is absent, then v will be created as an index of the second dimension of y
      If "labels" field is found in metadata (dlimits.lables) of the tplot variable and if number of elements
      along second dimention of y is the same as number of labels, then v variable
      will be prepared to be LABL_PTR_1.
      TPLOT_ADD_CDF_STRUCTURE supports only LABL_PTR_1 (one label pointer) case.

      If tplot has n-d y but number of dimensions does not correspond to number or
      supporting variables (x, v or v1, v2 ...) then extra supporting variables (v1, v2 ...) will be removed.
      This behaivour ensures the saving of the tplot into CDF file.

      If tplot variable has only x, then data variable y = x will be created.

    INPUT:
       tplot_vars: (string or array of strings) Tplot variable name, or list of the tplot variables

    KEYWORDS:
       TT2000: (flag) Indicates that time should be included as TT2000
               If x type is double, x will be converted to LONG64 using CDF_PARSE_TT2000
       NEW: (flag) Create new CDF structure or ignore existing CDF structure

    EXAMPLES:
       store_date, 'example_tplot',data={x:time_double('2001-01-01')+[1, 2, 3],y:[10, 20, 30]}
       tplot_add_cdf_structure, 'example_plot'
       tplot2cdf, filename='example_cdf_file', tvars='example_plot'

      See crib_tplot2cdf_basic for additional examples

    CREATED BY:
      Alexander Drozdov

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2023-06-05 13:04:09 -0700 (Mon, 05 Jun 2023) $
     $LastChangedRevision: 31884 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/CDF/tplot_add_cdf_structure.pro $

(See general/CDF/tplot_add_cdf_structure.pro)