ODS support for Octave

Copyright © 2009 - 2011 Philip Nienhuis <prnienhuis at users.sf.net>

This version February 16, 2011

(ODS = Open Document Format spreadsheet data format, used by e.g., OpenOffice.org.)

Files content

odsread.m
No-hassle read script for reading from an ODS file and parsing the numeric and text data into separate arrays.

odswrite.m
No-hassle write script for writing to an ODS file.

odsopen.m 
Get a file pointer to an ODS spreadsheet file.

ods2oct.m
Read raw data from an ODS spreadsheet file using the file pointer handed by odsopen.

oct2ods.m
Write data to an ODS spreadsheet file using the file pointer handed by odsopen.

odsclose.m
Close file handle made by odsopen and -if data have been transfered to a spreadsheet- save data.

odsfinfo.m
Explore sheet names and optionally estimated data size of ods files with unknown content.

calccelladdress.m
Utility function needed for jOpenDocument class.

parsecell.m
(contained in Excel xlsread scripts, but works also for ods support) parse raw data (cell array) into separate numeric array and text (cell) array.)

spsh_chkrange.m
spsh_prstype.m
getusedrange.m
calccelladdress.m
parse_sp_range.m
Support files called by the scripts and not meant for direct invocation by users.

REQUIRED SUPPORT SOFTWARE

For Windows (MingW):

For Linux:

For ODS access, you'll need to choose at least one of the following java class files collections:


and/or

These must be referenced with full pathnames in your javaclasspath. Hint: add it in ./share/octave/<version>/m/startup/octaverc using appropriate javaaddpath statements


USAGE

(see “help ods<function_filename>” in octave terminal.)

odsread is a sort of analog to xlsread and works more or less the same. odsread is a mere wrapper for the functions odsopen, ods2oct, and odsclose that do file access and the actual reading, plus parsecell for post-processing.

odswrite works similar to xlswrite. It too is a wrapper for scripts which do the actual work and invoke other scripts, a.o. oct2ods.

odsfinfo can be used to explore odsfiles with unknown content for sheet names and to get an impression of the data content sizes.

When you need data from just one sheet, odsread is for you. But when you need data from multiple sheets in the same spreadsheet file, or if you want to process spreadsheet data by limited-size chunks at a time, odsopen / ods2oct [/parsecell] / … / odsclose sequences provides for much more speed and flexibility as the spreadsheet needs to be read just once rather than repeatedly for each call to odsread.

Same reasoning goes for odswrite.

Also, if you use odsopen / …../, you can process multiple spreadsheets simultaneously – just use odsopen repeatedly to get multiple spreadsheet file pointers.

Moreover, after adding data to an existing spreadsheet file, you can fiddle with the filename in the ods file pointer struct to save the data into another, possibly new spreadsheet file.

If you use odsopen / ods2oct / … / oct2ods / …. / odsclose, DO NOT FORGET to invoke odsclose in the end. The file pointers can contain an enormous amount of data and may needlessly keep precious memory allocated.


SPREADSHEET FORMULA SUPPORT

When using the OTK interface you can:
In short, you can enter spreadsheet formulas and in a later stage read them back, change them and re-enter them in the worksheet. The behaviour is controlled by an option structure options (as last argument to oct2ods.m and ods2oct.m) which for now has only one (logical) field:
Be aware that there's no formula evaluator in ODS java, not even a formula validator. So if you create formulas in your spreadsheet using oct2ods or odswrite, do not expect meaningful results when reading those files later on unless you open them in OpenOffice.org Calc and write them back to disk.
You can write all kind of junk as a formula into a spreadsheet cell. There's not much validity checking built into odfdom.jar. I didn't bother to try OpenOffice.org Calc to read such faulty spreadsheets, so I don't know what will happen with spreadsheets containing invalid formulas. But using the above options, you can at least repair them using octave....

GOTCHAS

I know of one big gotcha: i.e. reading dates (& time). A less obvious one is Java memory pool allocation size.

Date and time in ODS

Octave (as does Matlab) stores dates as a number representing the number of days since January 1, 0 (and as an aside ignores a.o. Pope Gregorius' intervention in 1582 when 10 days were simply skipped).

OpenOffice.org stores dates as text strings like “yyyy-mm-dd”.

MS-Excel stores dates as a number representing the number of days since January 1, 1900 (and as an aside, erroneously assumes 1900 to be a leap year).

Now, converting OpenOffice.org date cell values (actually, character strings flagged by “date” attributes) into Octave looks pretty straightforward. But when the ODS spreadsheet was originally an Excel spreadsheet converted by OpenOffice.org, the date cells can either be OOo date values (i.e.,strings) OR old numerical values from the Excel spreadsheet.

So: you should carefully check what happens to date cells.

As octave has no ”date” or “time” data type, octave date values (usually numerical data) are simply transferred as “floats” to ODS spreadsheets. You'll have to convert the values into dates yourself from within OpenOffice.org.

While adding data and time values has been implemented in the write scripts, the wait is for clever solutions to distinguish dates from floats in octave cell arrays.

Java memory pool allocation size

The Java virtual machine (JVM) initializes one big chunk of your computer's RAM in which all Java classes and methods etc. are to be loaded: the Java memory pool. It does this because Java has a very sophisticated “garbage collection” system. At least on Windows, the initial size is 2MB and the maximum size is 64MB. On Linux this allocated size is much bigger. This part of memory is where the Java-based ODS octave routines (and the Java-based ods routines) live and keep their variables etc.

For transferring large pieces of information to and from spreadsheets you might hit the limits of this pool. E.g. to be able to handle I/O of an array of around 50,000 cells I needed a memory pool size of 512 MB.

The memory size can be increased by inserting a file called “java.opts” (without quotes) in the directory ./share/octave/packages/java-<version> (where the script file javaclasspath.m is located), containing just the following lines:

-Xms16m
-Xmx512m

(where 16 = initial size, 512 = maximum size (in this example), m stands for Megabyte. This number is system-dependent).

After processing a large chunk of spreadsheet information you might notice that octave's memory footprint does not shrink so it looks like Java's memory pool does not shrink back; but rest assured, the memory footprint is the allocated (reserved) memory size, not the actual used size. After the JVM has done its garbage collection, only the so-called “working set” of the memory allocation is really in use and that is a trimmed-down part of the memory allocation pool. On Windows systems it often suffices to minimize the octave terminal for a few seconds to get a more reasonable memory footprint.

Reading cells containing errors

Spreadsheet cells containing erroneous stuff are transferred to Octave as NaNs. But not all errors can be catched. Cells showing #Value# in OpenOffice.org Calc often contain invalid formulas but may have a 0 (null) value stored in the value fields. It is impossible to catch this as there is no run-time formula evaluator (yet) in ODF Toolkit nor jOpenDocument (like there is in Apache POI for Excel).

Smaller gotcha's (only with jOpenDocument 1.2b2, fixed in 1.2b3+ and 1.2 final):

NOT fixed in version 1.2 final:


MATLAB COMPATIBILITY

AFAIK there's no similar functionality in Matlab (yet?), only for reading and then very limited.
odsread is fairly function-compatible to xlsread, however.

Same goes for odswrite, odsfinfo and xlsfinfo – however odsfinfo has better functionality IMO.


COMPARISON OF INTERFACES

The ODFtoolkit is the one that gives the best (but slow) results at present. However, parsing xml trees into rectangular arrays is not quite straightforward and the other way round is a real nightmare; odftoolkit up til 0.7.5. did little to hide the gory details for the developers.

While reading ODS is still OK, writing implies checking whether cells already exist explicitly (in table:table-cells) or implicitly (in number-columns-repeated or number-rows-repeated nodes) or not at all yet in which case you'll need to add various types of parent nodes. Inserting new cells (“nodes”) or deleting nodes implies rebuilding possibly large parts of the tree in memory - nothing for the faint-of-heart. Only with ODFToolkit (odfdom) 0.8.6 things have been simplified for developers.

The jOpenDocument interface is the most promising, as it does shield the xml tree details and presents developers something which looks like a spreadsheet model.
However, unfortunately the developers decided to shield essential methods by making them 'protected' (e.g. the vital getCellType). JopenDocument does support writing. But OTOH many obvious methods are still lacking and formula support is absent.
And last (but not least) the jOpenDocument developers state that their development is primarily driven by requests from customers who pay for support. I do sympathize with this business model but for octave needs this may hamper progress for a while.

TROUBLESHOOTING

Some hints for troubleshooting ODS support are given here.

  1. Check if Java works. Do a pkg list and see

    a. If there's a Java package mentioned (then it's installed). If not, install it.

    b. If there's an asterisk on the java package line (then the package is loaded). If not, do a pkg rebuild-auto java

  1. Check Java memory settings. Try javamem

    a. If it works, check if it reports sufficiently large max memory (had better be 200 MiB, the bigger the better)

    b. If it doesn't work, do:

      rt = java_invoke ('java.lang.Runtime', 'getRuntime')

      rt.gc

      rt.maxMemory ().doubleValue () / 1024 / 1024

      The last command will show MaxMemory in MiB.

    c. In case you have insufficient memory, see in “GOTCHAS”, “Java memory pool allocation size”, how to increase java's memory pre-reservation.

  2. Check if all classes (.jarfiles) are in class path. Do a 'jcp = javaclasspath (-all)'  (under unix/linux, do 'jcp = javaclasspath; strsplit (jcp,”:”)' (w/o quotes). See above under “REQUIRED SUPPORT SOFTWARE” what classes should be mentioned.

    If classes (.jar files) are missing, download and put them somewhere and add them to the javaclass path with their fully qualified pathname (in quotes) using javaaddpath().

Once all classes are present and in the javaclasspath, the ods interfaces should just work. The only remaining showstoppers are insufficient write privileges for the working directory, a wrecked up octave or some other problems outside octave.

  1. Try opening an ods file:

    ods1 = odsopen ('test.ods', 1, 'otk'). If this works and ods1 is a struct with various fields containing objects, ODF toolkit interface (OTK) works. Do an ods1 = odsclose (ods1) to close the file.

    ods2 = odsopen ('test.ods', 1, 'jod'). If this works and ods2 is a struct with various fields containing objects, jOpenDocument interface (JOD) works as well. Do ods2 = odsclose (ods2) to close the file.


DEVELOPMENT

As with the Excel r/w stuff, adding new interfaces should be easy and straightforward. Add relevant stanzas in odsopen, odsclose, odsfinfo & getusedrange and add new subfunctions (for the real work) to getusedrange_<INTF>, oct2ods and ods2oct.

Suggestions for future development:

Some notes on the choice for Java:
  1. It saves a LOT of development time to use ready-baked Java classes rather than developing your own routines and thus effectively reinvent the wheel.
  2. A BIG advantage is that a Java-based solution is platform-independent (“portable”).
  3. But Java is known to be not very conservative with resources, especially not when processing XML-based formats.
So Java is a compromise between portability and rapid development time versus capacity (and speed).
But IMO data sets larger than 5.105 cells should not be kept in spreadsheets anyway. Use real databases for such data sets.

ODFDOM versions

I have tried various odfdom version. As to 0.8 & 0.8.5, while the API has been simplified enormously (finally one can address cells by spreadsheet address rather than find out yourself by parsing the table-column/-row/-cell structure), many irrecoverable bugs have been introduced :-((
In addition processing ODS files became significantly slower (up to 7 times!).

End of August 2010 I have implemented support for odfdom-0.8.6.jar – that version is at last sufficiently reliable to use. The few remaining bugs and limitations could easily be worked around by diving in the older TableTable API.
So at the moment (January 2011 = last I looked) only odfdom versions 0.7.5 and 0.8.6 are supported. Ihaven't tried the odfdom-0.8.7 snapshot.

If you want to experiment with odfdom 0.8 & 0.8.5, you can try:

Enjoy!

Philip Nienhuis, February 16, 2011