This repository contains a Python-based automation tool for generating monthly groundwater compliance reports using a structured Excel input file and a Microsoft Word (.docx) report template.
The tool replaces predefined placeholders in a DOCX template with updated values supplied via Excel and applies conditional logic to generate standardized regulatory narrative (e.g., groundwater flow direction statements, sampling dates, non-detect summaries, and SSI determinations).
This workflow is intended to reduce manual editing, improve consistency across reporting periods, and support defensible, auditable compliance reporting.
- Template-driven report generation using Microsoft Word (
.docx) - Human-readable placeholders (e.g.,
{{GW_FLOW_DIRECTION}}) - Excel-based control file for all variable report content
- Conditional logic for regulatory statements (e.g., SSI presence)
- Placeholder replacement across paragraphs, tables, headers, and footers
- Deterministic, repeatable outputs suitable for regulatory submission
groundwater-report-generator/
├── templates/
│ └── GW_Report_Template.docx
├── inputs/
│ └── report_inputs.xlsx
├── outputs/
│ └── GW_Report_Final.docx
├── scripts/
│ └── generate_gw_report.py
├── README.md
└── requirements.txt
- Python 3.9 or newer
- Microsoft Word–compatible
.docxfiles
- pandas
- python-docx
- openpyxl
Install dependencies using:
pip install -r requirements.txt
The report template must use double-curly-brace placeholders:
{{PLACEHOLDER_NAME}}
Example placeholders:
{{GW_FLOW_DIRECTION}}
{{GW_SAMPLE_DATES}}
{{NEXT_SAMPLING_EVENT}}
{{ND_PARAMETERS}}
{{SSI_STATEMENT}}
The Excel input file serves as a control table with the following required columns:
| Column Name | Description |
|---|---|
| Field_Name | Placeholder key |
| Value | Replacement value |
python scripts/generate_gw_report.py
The finalized report will be written to the outputs/ directory.
Add a license file as appropriate for your organization or distribution needs.