IDL user manual
===============
:toc:
== Open/close a CEF file
=== cef_read (<filename>) -> integer
Reads a CEF file, loads all data and metadata in memory.
Returns the number of records in the file
.Example
------------------------------------------------------------------------------
IDL> n = CEF_READ("C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef")
% Loaded DLM: CEF.
1 : CEF.Open_CEF_file :
C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef
1 : CEF.Read_CEF_header : 2167422 records found in 3.48 seconds
1 : CEF.Read_CEF_header : 11 values per record
1 : CEF.Display_variables : 7 variables + 0 constants
1 : CEF.Read_CEF_file : 2167422 records physically read in 2.74
seconds
1 : CEF.Read_CEF_file : STATUS = 0 : OK : Terminaison correcte
------------------------------------------------------------------------------
=== cef_close
Will release all memory used to handle the file and its data
=== cef_verbosity, <level>
will change the verbosity level of the CEFLIB, which can be usefull to debug
problems while reading CEF files
Defaut <level> is 1, and can be increased up to 5
== Global metadata
=== cef_metanames () -> array of stings
Returns the list of metadata sections
------------------------------------------------------------
IDL> print, CEF_METANAMES()
MISSION MISSION_TIME_SPAN MISSION_AGENCY MISSION_DESCRIPTION
MISSION_KEY_PERSONNEL MISSION_REFERENCES MISSION_REGION MISSION_CAVEATS
OBSERVATORY OBSERVATORY_CAVEATS OBSERVATORY_DESCRIPTION OBSERVATORY_TIME_SPAN
OBSERVATORY_REGION EXPERIMENT EXPERIMENT_DESCRIPTION INVESTIGATOR_COORDINATES
EXPERIMENT_REFERENCES EXPERIMENT_KEY_PERSONNEL EXPERIMENT_CAVEATS
INSTRUMENT_NAME INSTRUMENT_DESCRIPTION INSTRUMENT_TYPE MEASUREMENT_TYPE
INSTRUMENT_CAVEATS DATASET_ID DATA_TYPE DATASET_TITLE DATASET_DESCRIPTION
CONTACT_COORDINATES TIME_RESOLUTION MIN_TIME_RESOLUTION MAX_TIME_RESOLUTION
PROCESSING_LEVEL ACKNOWLEDGEMENT DATASET_CAVEATS LOGICAL_FILE_ID
VERSION_NUMBER DATASET_VERSION FILE_CAVEATS FILE_TYPE METADATA_TYPE
METADATA_VERSION FILE_TIME_SPAN GENERATION_DATE
------------------------------------------------------------
=== cef_meta (<section>) -> array of strings
Returns the list of string entries for this metadata section
------------------------------------------------------------
IDL> print, CEF_META("DATASET_DESCRIPTION")
This dataset contains full resolution measurements of the magnetic field
vector from the FGM experiment on the Cluster C1 spacecraft
------------------------------------------------------------
=== cef_gattributes () -> array of strings
Returns the list of global attributes names
------------------------------------------------------------
IDL> print, CEF_GATTRIBUTES()
FILE_NAME FILE_FORMAT_VERSION END_OF_RECORD_MARKER DATA_UNTIL
------------------------------------------------------------
=== cef_gattr (<attribute>) -> string or array of strings
Returns value of a global attribute:
- result should be a string if the attribute has an unique value
- or a list of strings for multi-valued attributes
------------------------------------------------------------
IDL> print, CEF_GATTR("FILE_NAME")
C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef
------------------------------------------------------------
== CEF variables
=== cef_varnames () -> array
Return the list of CEF variables found in the file
------------------------------------------------------------
IDL> print, CEF_VARNAMES()
time_tags half_interval B_vec_xyz_gse B_mag sc_pos_xyz_gse range tm
------------------------------------------------------------
=== cef_var (<var-name>) -> IDL array
Creates an IDL variable, with the content of a given CEF-variable.
It should be an array of 1 to 6 dimensions of string, integer, float,
depending on type of the CEF variable.
.Exemple
----
filename = "C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef"
n = CEF_READ (filename)
t = CEF_VAR ("time_tags")
b = CEF_VAR ("b_vec_xyz_gse")
----
=== cef_vattributes (<cef-varname>) -> array of strings
Returns the list of attributes names for a given variable
------------------------------------------------------------
IDL> print, CEF_VATTRIBUTES("B_vec_xyz_gse")
PARAMETER_TYPE ENTITY PROPERTY FLUCTUATIONS CATDESC UNITS SI_CONVERSION
TENSOR_ORDER COORDINATE_SYSTEM REPRESENTATION_1 SIZES VALUE_TYPE
SIGNIFICANT_DIGITS FILLVAL QUALITY FIELDNAM LABLAXIS DEPEND_0 LABEL_1
------------------------------------------------------------
=== cef_vattr (<cef-varname>, <attribute>) -> string ot array of strings
Returns attribute value for a given CEF variable attribute:
- result should be a string if the attribute has an unique value
- or a list of strings for multi-valued attributes
------------------------------------------------------------
IDL> print, CEF_VATTR("B_vec_xyz_gse", "SI_CONVERSION")
1.0E-9>T
------------------------------------------------------------
=== cef_depends (<cef-varname>) -> array of strings
Returns a list of DEPEND_i variables names for a given CEF variable
The first one corresponds to the DEPEND_0, then DEPEND_1, DEPEND_2, ...
Values can be empty strings if DEPEND_i attribute is not set.
------------------------------------------------------------
IDL> print, CEF_DEPENDS("B_vec_xyz_gse")
time_tags
------------------------------------------------------------
== Time-tags functions
=== milli_to_julian (<time-tag-variable>) -> array of double
CEFLIB time-tags are coded internally in milli-seconds from 1958
This function converts these time-tags into corresponding Julian days
Input can be a scalar or an array, of ISO_TIME or ISO_TIME_RANGE data
=== milli_to_epoch (<time-tag-variable>) -> array of double
CEFLIB time-tags are coded internally in milli-seconds from 1958
This function converts these time-tags into corresponding CEF Epoch time
Input can be a scalar or an array, of ISO_TIME or ISO_TIME_RANGE data
=== milli_to_isotime (<time-tag-variable>,<number-of-digits>) -> array of strings
This function will convert internal time-tags in ISOTIME strings.
The first argument could be an ISO_TIME or ISO_TIME_RANGE CEF variable
The second arguments give the number of digits expected for fractional seconds:
(0: seconds, 3: milli-seconds, 6: micro-seconds)
.Exemple
How to open a CEF file and print time-tags with micro-seconds resolution :
nrec = CEF_READ ("some-cef-file.cef")
print, MILLI_TO_ISOTIME (CEF_VAR ("time_tags"), 6)
== Examples of use
------------------------------------------------------------------------------------
PRO fgm
filename = "C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef"
n = CEF_READ (filename)
t = CEF_VAR ("time_tags")
b = CEF_VAR ("b_vec_xyz_gse")
tt = MILLI_TO_JULIAN (t)
bx = b [0,*]
by = b [1,*]
bz = b [2,*]
temp = LABEL_DATE (date_format = "%H:%I")
PLOT, tt, bx, COLOR = 'ff0000'x, $
TITLE = "FGM DATA", $
xtickformat = "LABEL_DATE", $
BACKGROUND = 'ffffff'x
OPLOT, tt, by, COLOR = '00ff00'x
OPLOT, tt, bz, COLOR = '0000ff'x
END
------------------------------------------------------------------------------------
