5.4. Handling Data Files

5.4.1. About ECD file

E-Cell SE uses ECD (E-Cell Data) file format to store simulation results. ECD is a plain text file, and easily handled by user-written and third-party data processing and plotting software such as gnuplot.

An ECD file can store a matrix of floating-point numbers.

ecell.ECDDataFile class can be used to save and load ECD files. A ECDDataFile object takes and returns a rank-2 array of Numeric Python. A 'rank-2' array is a matrix, which means that Numeric.rank( ARRAY ) and len( Numeric.shape( ARRAY ) ) returns '2'.

5.4.2. Importing ECDDataFile class

To import the ECDDataFile class, import the whole ecell module,

import ecell
or import ecell.ECDDataFile module selectively.
import ecell.ECDDataFile

5.4.3. Saving and loading data

To save data to an ECD file, say, datafile.ecd, instantiate an ECDDataFile object and use save() method.

import ecell
aDataFile = ecell.ECDDataFile( DATA )
aDataFile.save( 'datafile.ecd' )

here DATA is a rank-2 array of Numeric Python or an equivalent object. The data can also be set by using setData() method after the instantiation. If the data is already set, it is replaced.

aDataFile.setData( DATA )

Loading the ECD file is also straightforward.

aDataFile = ecell.ECDDataFile()
aDataFile.load( 'datafile.ecd' )
DATA = aDataFile.getData()

The getData() method extracts the data from the ECDDataFile object as an array.

5.4.4. ECD header information

In addition to the data itself, an ECD file can hold some information in its header.

The header information is stored in the file like this.


#DATA:
#SIZE: 5 1010
#LABEL: t       value   avg     min     max
#NOTE:
#
#----------------------
0 0.1 0.1 0.1 0.1
...
Each line of the header is headed by a sharp (#) character. The '#SIZE:' line is automatically set when saved to show size of the data. This field is ignored in loading. The header ends with '#----...'.

5.4.5. Using ECD outside E-Cell SE

For most cases Numeric Python will offer any necessary functionality for scientific data processing. However, using some external software can enhance the usability.

ECD files can be used as input to any software which supports white space-separated text format, and treats lines with heading sharps (#) as comments.

GNU gnuplot is a scientific presentation-quality plotting software with a sophisticated interactive command system. To plot an ECD file from gnuplot, just use plot command. For example, this draws a time-value 2D-graph:

gnuplot> plot 'datafile.ecd' with lines

Use using modifier to specify which column to use for the plotting. The following example makes a time-average 2D-plot.

gnuplot> plot 'datafile.ecd' using 1:3 with lines

Another OpenSource software useful for data processing is GNU Octave. Loading an ECD from Octave is also simplest.

octave:1> load datafile.ecd

Now the data is stored in a matrix variable with the same name as the file without the extension (datafile).

octave:2> mean(datafile)
ans =
 
   5.0663  51.7158  51.7158  51.2396  52.2386

5.4.6. Binary format

Currently loading and saving of the binary file format is not supported. However, Numeric Python has an efficient, platform-dependent way of exporting and importing array data. See the Numeric Python manual.