Serveur documentation

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

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

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']
...

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

Python user manual