Add readme files (#3)

* Added export scripts (CSV, Excel, DAT) and their documentation in PDF format

* Added README files for previously added scripts

Author: parsaabadi

ompp_export_csv.md

@@ -0,0 +1,54 @@
+# ompp_export_csv.py
+
+## Introduction
+`ompp_export_csv.py` is a Python script designed to export all output tables from an OpenM++ SQLite scenario database into a series of CSV files. This allows users to analyze or share the scenario data in a common, lightweight format outside the SQLite environment.
+
+## Features
+- Reads all output tables from a given SQLite database.
+- Exports the contents of each table into a corresponding CSV file.
+- Ensures a clean, textual representation of model output data, making it easy to integrate with spreadsheets or other analysis tools.
+
+## Prerequisites
+To use `ompp_export_csv.py`, you need:
+- A valid SQLite database file produced by an OpenM++ model run.
+- Python 3.x installed on your system.
+- The `common.py` module and any other dependencies located in the same directory as `ompp_export_csv.py`.
+
+## Usage
+Run the script from the command line as follows:
+
+```bash
+python ompp_export_csv.py <source-sqlite> <destination-folder>
+```
+
+### Arguments
+- `<source-sqlite>`: The path to the SQLite database file containing the scenario's model outputs.
+- `<destination-folder>`: The path to a directory where the CSV files will be created.
+
+### Notes on the Destination Folder
+**Important:** The output directory you provide must not already exist.
+
+The script requires a non-existing directory so it can create a fresh location where CSV files are placed. If the directory already exists, the script will refuse to run to prevent accidental overwriting of existing files.
+
+## Examples
+
+### Example 1
+Suppose you have a scenario database named `Scenario.sqlite` and you want to export the tables into a new directory called `results`. Run:
+
+```bash
+python ompp_export_csv.py Scenario.sqlite results
+```
+
+If `results` does not exist yet, the script will create it and place all extracted CSV files inside.
+
+### Example 2
+If the directory `results` already exists, you will see an error message:
+
+```plaintext
+ERROR =====> ompp_export_csv: Output directory for csv files 'results' must not already exist
+```
+
+In this case, choose a different directory name or remove/rename the existing one.
+
+## Error Handling
+If the script cannot find the specified SQLite database, or if the database is empty, it will log an error and exit. Similarly, if the output directory already exists, it will not proceed, helping to ensure that no existing data is accidentally overwritten.

ompp_export_dat.md

@@ -0,0 +1,62 @@
+# ompp_export_dat.py
+
+## Introduction
+`ompp_export_dat.py` is a Python utility script to export model output data from an OMPP-compatible SQLite database into `.dat` files.
+
+By processing the contents of a given SQLite database, `ompp_export_dat.py` creates a series of `.dat` files, one for each table found in the database.
+
+## Usage
+To run the script, invoke the Python interpreter with `ompp_export_dat.py`, followed by two arguments: the input SQLite database file and the output directory where the `.dat` files will be generated.
+
+### Example Syntax
+```bash
+python ompp_export_dat.py <input-sqlite-file> <output-directory>
+```
+
+### Arguments
+- `<input-sqlite-file>`: The path to the SQLite database that contains OMPP model output tables.
+- `<output-directory>`: The path to the directory where the script will write the generated `.dat` files.
+
+## Example
+Below is an example invocation of the script on a Windows system. This example uses the RiskPaths model output database and exports data to the user's desktop folder `ompp_exportDAT`.
+
+```bash
+C:\OpenM\openm\libopenm\common> python ompp_export_dat.py C:\OpenM\models\RiskPaths\ompp\bin\RiskPaths.sqlite C:\Users\parsaba\Desktop\ompp_exportDAT
+```
+
+As the script runs, it displays informational messages for each processed table and confirms where the `.dat` file is written:
+
+```plaintext
+ompp_export_dat: Processing table 'T01_LifeExpectancy'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T01_LifeExpectancy.dat'
+
+ompp_export_dat: Processing table 'T02_TotalPopulationByYear'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T02_TotalPopulationByYear.dat'
+
+ompp_export_dat: Processing table 'T03_FertilityByAge'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T03_FertilityByAge.dat'
+
+ompp_export_dat: Processing table 'T04_FertilityRatesByAgeGroup'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T04_FertilityRatesByAgeGroup.dat'
+
+ompp_export_dat: Processing table 'T05_CohortFertility'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T05_CohortFertility.dat'
+
+ompp_export_dat: Processing table 'T06_BirthsByUnion'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T06_BirthsByUnion.dat'
+
+ompp_export_dat: Processing table 'T07_FirstUnionFormation'
+write_to_dat_file: Data written to 'C:\Users\parsaba\Desktop\ompp_exportDAT\T07_FirstUnionFormation.dat'
+
+ompp_export_dat: Successfully exported 'C:\OpenM\models\RiskPaths\ompp\bin\RiskPaths.sqlite' to 'C:\Users\parsaba\Desktop\ompp_exportDAT'
+
+ompp_export_dat: Database connection closed.
+```
+
+This output confirms that each table has been processed and that the corresponding `.dat` files have been created successfully.
+
+## File Contents
+Within each generated `.dat` file, the script includes a header line with the table name and columns, followed by rows of data. These rows are space-separated by default.
+
+## Error Handling
+If the input database does not exist or the output directory is invalid, the script logs an error message and stops. Database connectivity issues or unexpected runtime errors are also reported to help you diagnose and fix problems quickly.

ompp_export_excel.md

@@ -0,0 +1,54 @@
+# ompp_export_excel.py
+
+## Introduction
+`ompp_export_excel.py` is a Python utility script to export model output data from an OMPP-compatible SQLite database into Excel files.
+
+By processing the contents of a given SQLite database, `ompp_export_excel.py` creates either a single Excel file with all tables as sheets or multiple Excel files, one for each table, based on the output settings.
+
+## Usage
+To run the script, invoke the Python interpreter with `ompp_export_excel.py`, followed by two arguments: the input SQLite database file and the output path where the Excel files will be generated.
+
+### Example Syntax
+```bash
+python ompp_export_excel.py <input-sqlite-file> <output-path>
+```
+
+### Arguments
+- `<input-sqlite-file>`: The path to the SQLite database that contains OMPP model output tables.
+- `<output-path>`: The path to the directory or file where the script will write the Excel output. If a directory is provided, multiple Excel files are generated (one per table). If a file path is provided, a single Excel file with multiple sheets is created.
+
+## Example
+Below is an example of the script run. This example uses the RiskPaths model output database and exports data to the user's desktop folder `excelFiles`.
+
+```bash
+C:\OpenM\openm\libopenm\common> python ompp_export_excel.py C:\OpenM\models\RiskPaths\ompp\bin\RiskPaths.sqlite C:\Users\parsaba\Desktop\excelFiles\
+```
+
+As the script runs, it displays informational messages for each processed table and confirms where the Excel files are written:
+
+```plaintext
+ompp_export_excel: Processing table 'T01_LifeExpectancy'
+write_to_excel_file: Data written to 'C:\Users\parsaba\Desktop\excelFiles\T01_LifeExpectancy.xlsx'
+
+ompp_export_excel: Processing table 'T02_TotalPopulationByYear'
+write_to_excel_file: Data written to 'C:\Users\parsaba\Desktop\excelFiles\T02_TotalPopulationByYear.xlsx'
+
+ompp_export_excel: Successfully exported 'C:\OpenM\models\RiskPaths\ompp\bin\RiskPaths.sqlite' to 'C:\Users\parsaba\Desktop\excelFiles\'
+
+ompp_export_excel: Database connection closed.
+```
+
+This output confirms that each table has been processed and that the corresponding Excel files have been created successfully.
+
+## File Contents
+Each generated Excel file contains the full contents of a single table from the SQLite database. If exporting to a single Excel file, each table is written to a separate sheet, with sheet names truncated to 31 characters if necessary.
+
+## Error Handling
+If the input database does not exist or the output path is invalid, the script logs an error message and stops. Common errors include:
+
+- **Database file not found**: The specified SQLite database file does not exist.
+- **Permission denied**: The script lacks write permissions for the output path.
+- **Unexpected runtime errors**: These are logged to help diagnose and fix problems quickly.
+
+## Warnings
+When exporting tables with long names, a warning is logged if the sheet name exceeds 31 characters. This limitation is due to Excel's constraints on sheet names.