Metadata-Version: 2.4
Name: odt2csv
Version: 0.1
Summary: Converts an OOMMF data table (ODT) file generated by OOMMF simulations into a CSV data file for better compatibility with modern applications
Home-page: https://github.com/groaking/odt2csv
Author: Samarthya Lykamanuella
Author-email: lykamanuella@outlook.com
Maintainer: Samarthya Lykamanuella
Maintainer-email: lykamanuella@outlook.com
License: GNU General Public License v3.0 or later
Project-URL: Bug Reports, https://github.com/groaking/odt2csv/issues
Project-URL: GitHub, https://github.com/groaking/odt2csv
Project-URL: Home Page, https://github.com/groaking/odt2csv
Project-URL: Change Log, https://github.com/groaking/odt2csv/blob/main/CHANGELOG.md
Keywords: oommf,odt,csv,conversion,tools,datatable,simulation,micromagnetic,nanomagnetic,physics,magnetism
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# 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):

```sh
pip install odt2csv
```

## Usage

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

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

Glob pattern and multiple file arguments are also supported:

```sh
#!/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):

```python
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:

```sh
#!/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:

```python
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:

```sh
#!/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.
```

```python
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](https://github.com/groaking/odt2csv).

You can also contribute by [opening an issue](https://github.com/groaking/odt2csv/issues), proposing a new feature, and [creating a new pull request](https://github.com/groaking/odt2csv/pulls) 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](https://github.com/Spiros94/ODT2Excel) by [Spiros94](https://github.com/Spiros94).
