Python user manual
==================
== How to start
Import the library and call its methods with ceflib.method-name()
----
$ python
>>> import ceflib
>>> ceflib.read ("C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030927_V01.cef")
>>> print ceflib.varnames ()
----
Import all the methods of the library in current environment:
----
$ python
>>> from ceflib import *
>>> read ("C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030927_V01.cef")
>>> print varnames ()
----
== Librairie Reference
=== verbosity (level)
Set CEFLIB verbosity level (0..5) that can be useful to debug in case of problem.
You can set level to 0 to suppress unexpected CEFLIB messages.
=== read (filename) -> integer
Read CEF file content and load data in memory.
Return error code (0 if OK)
.Example
----
>>> status = read ("C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030927_V01.cef")
1 : CEF.Clear_descriptor : Release memory
1 : CEF.Open_CEF_file : C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030907_V09.cef.gz
1 : CEF.Read_CEF_header : 20206 records found in 0.03 seconds
1 : CEF.Read_CEF_header : 24 values per record
1 : CEF.Display_variables : 12 variables + 0 constants
1 : CEF.Read_CEF_file : 20206 records physically read in 0.06 seconds
1 : CEF.Read_CEF_file : STATUS = 0 : OK : Terminaison correcte
>>> print status == 0 and "OK" or "Error"
OK
----
NOTE: You can open a regular .cef file or a compressed .cef.gz file
=== read_metadata (filename) -> integer
New method (added in v1.8.0) that parse the metadata content of a given CEF header,
without reading data records to improve performance.
Any metadata queries will be available, but the content of variables is undefined.
----
>>> status = read_metadata ("C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030927_V01.cef")
1 : CEF.Clear_descriptor : Release memory
1 : CEF.Open_CEF_file : C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030907_V09.cef.gz
1 : CEF.Read_CEF_header : 24 values per record
1 : CEF.Display_variables : 12 variables + 0 constants
1 : CEF.Read_CEF_metadata : STATUS = 0 : OK : Terminaison correcte
----
=== close ()
Release allocated ressources.
=== records () -> integer
Return the number of records in the current CEF file.
----
>>> print records ()
20206
----
NOTE: Is the file has been opened with read_metadata(), the records() function will return 1,
instead of the number of records in the file.
=== gattributes () -> list of strings
Return the list of CEF global attributes
----
>>> print gattibutes ()
['FILE_NAME', 'FILE_FORMAT_VERSION', 'END_OF_RECORD_MARKER', 'DATA_UNTIL']
----
=== gattr (attribute-name) -> string
Return value of a global attribute.
----
>>> print gattr ("FILE_NAME")
C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030907_V09.cef
----
=== metanames () -> list of strings
Return list of metadata sections names.
----
>>> print metanames ()[:5]
['Logical_file_ID', 'Generation_date', 'File_time_span', 'Version_number', 'MISSION']
----
=== meta (metadata) -> list of string
Return values for a given metadata section
----
>> for m in metanames (): print m, meta (m)
Logical_file_ID ['C1_CP_CIS-HIA_ONBOARD_MOMENTS__20030907_V09']
Generation_date ['2013-09-09T18:01:52Z']
File_time_span ['2003-09-07T00:00:00.000Z/2003-09-07T23:59:59.999Z']
Version_number ['09']
MISSION ['Cluster']
MISSION_TIME_SPAN ['2000-08-16T12:39:00Z/2030-12-31T23:59:59Z']
MISSION_AGENCY ['ESA']
...
----
NOTE: this function returns allways a list of strings, even there is only one value.
=== varnames () -> list of strings
Return the list of CEF variables defined in the current file
----
>>> print "\n".join (varnames ())
time_tags
delta_time
sensitivity
cis_mode
density
velocity_isr2
velocity_gse
temperature
temp_par
temp_perp
pressure
pressure_tensor
----
=== var (varname) -> numpy array of variable data type
Return data content for the specified variable name
----
>>> print var ("density")
[ 0.01923148 0.03846296 0.01035187 ..., 0.01831131 0.01923148
0.02668483]
>>> print var ("time_tags")
[ 1.44158400e+12 1.44158401e+12 1.44158401e+12 ..., 1.44167035e+12
1.44167036e+12 1.44167036e+12]
----
=== vattributes (varname) -> list of strings
Return list of attibutes for a given variable
----
>>> vattributes ("density")
['CATDESC', 'FIELDNAM', 'PARAMETER_TYPE', 'VALUE_TYPE', 'ENTITY', 'PROPERTY',
'UNITS', 'SI_CONVERSION', 'DEPEND_0', 'QUALITY', 'SIGNIFICANT_DIGITS',
'FILLVAL']
----
=== vattr (varname, attribute) -> string
Get attribute value for a given variable
----
>>> vattr ("density", "UNITS")
'particles cm^-3'
>>> for a in vattributes ("density"):
print "%s = %s" % (a, vattr("density", a))
CATDESC = Density (in cm^-3)
FIELDNAM = Density
PARAMETER_TYPE = Data
VALUE_TYPE = FLOAT
ENTITY = Ion
PROPERTY = Mass_Density
UNITS = particles cm^-3
SI_CONVERSION = 1e6>(particles) m^-3
DEPEND_0 = time_tags
QUALITY = 3
SIGNIFICANT_DIGITS = 6
FILLVAL = -1e31
----
=== isotime_to_milli (string) -> double
Converts ISOTIME string to internal time-tags
----
>>> t = isotime _to_milli ("2003-09-07T00:00:03Z")
----
=== milli_to_isotime (double, integer) -> string
Converts internal time-tags to ISOTIME strings.
The first arguments must be the content of an ISOTIME CEF variable.
The precision represents the number of digits after the dot:
* 0 for plain seconds
* 3 for milli-seconds
* 6 for micro-seconds
----
>>> t = var("time_tags") [0]
>>> t
1.4415840031e+12
>>> print milli_to_isotime (t, 0)
2003-09-07T00:00:03Z
>>> print milli_to_isotime (t, 3)
2003-09-07T00:00:03.103Z
----
