odt2csv

odt2csv

This Python script converts an OOMMF data table (ODT) file generated by OOMMF (http://math.nist.gov/oommf/) into a CSV data file for better compatibility with more modern applications.

Features

The script can detect data rows and column header in an ODT file, remove excessive space characters, and separate each data value with commas in no time. It has been tested to convert a 69.7 MiB ODT file into CSV in 1.9 second using home laptop (HP Laptop 14-bs0xx). This module can also be used to quickly compress ODT files to save disk space.

Installation

To run odt2csv, simply install the latest Python version from https://www.python.org/downloads and execute the following command to download odt2csv from Python Package Index (PyPI):

pip install odt2csv

Usage

To convert an OOMMF data table (ODT) file into CSV, execute the following from the command line/terminal:

#!/bin/bash
python -m odt2csv path/to/oommf/datatable.odt

Glob pattern and multiple file arguments are also supported:

#!/bin/bash
# Using the UNIX Glob pattern:
python -m odt2csv path/to/oommf/*.odt

# Specifying multiple ODT files:
python -m odt2csv data1.odt data2.odt data3.odt

You can also import the converter directly from a Python script and integrate it with your app (however, this method does not currently support glob pattern and multiple file conversion directly):

import odt2csv

# Simple expression:
odt2csv.convert('path/to/oommf/datatable.odt')

# More advanced user may use the following expression:
odt2csv.convert(
    odt_input='path/to/oommf/datatable.odt',
    csv_output='output/csv/file.csv',
    output_suffix='_csv_filename_suffix',
    keep_unit=False,
    parser_behavior='fail'
)

# To use Glob pattern, you can use an indirect method:
import glob
for path in glob.glob('path/to/oommf/*.odt'):
    odt2csv.convert(odt_input=path)

# Converting multiple ODT files indirectly is also straightforward:
for path in ['datatable1.odt', 'datatable2.odt', 'datatable3.odt']:
    odt2csv.convert(odt_input=path)

If the csv_output parameter is not specified, the program automatically outputs the CSV file into path/to/oommf/datatable.csv (i.e., same name and in the same directory as the original ODT file, but with ".csv" extension).

Argument: Keep Unit

You can specify whether the unit name of each column in the ODT file should be preserved. This can be achieved by accessing the keep_unit parameter in the converter. The default behavior is False (i.e., omitting the unit name altogether). If you set keep_unit to True, the second row of the output CSV file will keep the unit name information.

Examples on how to set the keep_unit parameter via the terminal:

#!/bin/bash
python -m odt2csv --k 1 oommf_data.odt
python -m odt2csv --keep-unit false oommf_data.odt
# "1" for "true", "0" for "false".

An example on how to set the keep_unit parameter by importing the Python module:

import odt2csv
odt2csv.convert(
    odt_input='path/to/oommf/datatable.odt',
    keep_unit=False
)

Argument: Parser Behavior

The default writing behavior of OOMMF data table is to append the simulation data to, if exists, an already existing ODT file. If several simulations that output to the same ODT path are executed, this may lead to confusion as there are now multiple data headers in a single ODT file.

When odt2csv is presented with such an ODT file, the default behavior is to return the following error (specified by parameter parser_behavior='fail'):

odt2csv.exceptions.MultipleTableStartsError: Cannot convert ODT file that has multiple (2) table starts.

To solve this problem, you may try setting the parser_behavior parameter to new, which informs the converter to only convert the newest data header in the ODT file. For instance:

#!/bin/bash
python -m odt2csv -p new oommf_data_1.odt
python -m odt2csv --parser new oommf_data_2.odt
# "-p" or "--parser" are just the same.

import odt2csv
odt2csv.convert(
    odt_input='path/to/oommf/datatable.odt',
    parser_behavior='new'
)
# The only possible values for "parser_behavior" are: 'new', 'fail' (default), and 'raw'.

Setting the parser behavior to parser_behavior='raw' may also work to prevent the error from popping up, but this could lead to CSV table inconsistencies since this argument ignores ODT data header discrepancies. The "raw" parser behavior uses the ODT header information from the oldest data while converting the rest of data entries as is, regardless of the number of features in each entry.

Contributing

If you find this library helpful, feel free to star the odt2csv repository on GitHub.

You can also contribute by opening an issue, proposing a new feature, and creating a new pull request in this repository.

License Notice

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with this program. If not, see <https://www.gnu.org/licenses/>. 

See also

For those who want to convert an ODT file directly into an excel file, check out: ODT2Excel by Spiros94.