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")
>>> 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")
>>> varnames ()
----
== New in 1.8.4
Previously, when accessing to CEF time variables, the values were expressed in internal timestamps.
These values were corresponding to milli-seconds since 1958-01-01T00:00:00, as a numpy array of double.
This is still the case if you are using the celib.var() function.
You will have then to convert these values to Unix timestamps or ISO 8601 strings,
using ceflib.milli_to_timestamp() or ceflib.milli_to_isotime()
----
>>> ceflib.verbosity(0)
>>> ceflib.read("../DATA/C1_CP_WHI_ELECTRON_DENSITY__20020105_000000_20020106_000000_V071001.cef")
>>> t = ceflib.var("time_tags")
>>> t[0]
1388880021529.0
>>> ceflib.milli_to_timestamp (t[0])
1010188821.529
>>> ceflib.milli_to_isotime (t[0],6)
'2002-01-05T00:00:21.529000Z
----
We have added 3 functions to manipulate time variables
=== timestamp (time-variable)
This function returns a numpy array of Unix timestamps.
The values are expressed in fractional number of seconds since 1070-01-01T00:00:00.
----
>>> t = ceflib.timestamp ("time_tags")
>>> t [0]
1010188821.529
>>> from datetime import datetime
>>> datetime.utcfromtimestamp (t[0])
datetime.datetime(2002, 1, 5, 0, 0, 21, 529000)
----
=== datetime (time-variable)
This function returns a numpy array of python datetime.datetime objects
You can then use the usual methods defined for datetime.datetime objects
----
>>> dt = ceflib.datetime ("time_tags")
>>> dt [0]
datetime.datetime(2002, 1, 5, 0, 0, 21, 529000)
>>> dt [-1].isoformat()
'2002-01-05T19:45:49.848000'
----
=== datetime64 (time-variable)
This function returns a numpy array of numpy.datetime64[ms]
----
>>> dt = ceflib.datetime64 ("time_tags")
>>> dt [0]
numpy.datetime64('2002-01-05T00:00:21.529')
>>> print (dt[-1])
2002-01-05T19:45:49.848
----
There are internally stored as npy_int64 integers, number of milli-seconds.
=== ISO_TIME_RANGE variables
When accessing to CEF variables with VALUE_TYPE = ISO_TIME_RANGE, you will get a numpy array of number-of-records x 2 values,
corresponding to the start and the end of each time interval.
----
>>> ceflib.read ("C1_CT_AUX_GRMB__20010101_000000_20020101_000000_V240620.cef")
>>> ceflib.vattr("time_tags", "VALUE_TYPE")
'ISO_TIME_RANGE'
>>> dt = ceflib.datetime64("time_tags")
>>> dt.shape
(2383,2)
>>> dt [0]
array(['2001-01-01T00:02:56.000', '2001-01-01T00:19:16.000'],
dtype='datetime64[ms]')
>>> str(dt[0])
"['2001-01-01T00:02:56.000' '2001-01-01T00:19:16.000']"
----
== 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
----
>>> gattributes ()
['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
----
