From 405e02d14c77e2c7e07e2b301e4739497a8f8835 Mon Sep 17 00:00:00 2001 From: nick Date: Tue, 19 May 2026 11:39:59 -0400 Subject: [PATCH] Update README.md --- README.md | 171 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 117 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index c2321f6..7810ee5 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,139 @@ + # Tree Planting Data Validator 🌳 -A lightweight Python script that validates tree planting records stored in Excel files. It reads the data, cleans trailing blank rows, counts records, and produces a clear validation report. +**A robust Python script to validate Excel-based tree planting records.** -Perfect for NGOs, reforestation projects, environmental organizations, or anyone managing large-scale tree planting data. +This tool ensures that tree planting data submissions meet quality standards before being imported into databases or mapping systems. It performs comprehensive checks on participant types, planting dates, geographic coordinates, and tree sources. -## Features +--- -- Reads Excel files with customizable header row -- Automatically cleans trailing/empty rows -- Reports total records processed -- Extensible validation framework (ready for additional checks) -- Command-line interface with useful options -- Optional CSV error report export +## ✨ Features -## Requirements +- **Flexible column matching**: Automatically detects common column name variations +- **Data cleaning**: Removes blank rows and normalizes input +- **Comprehensive validation**: + - Required fields check + - Participant type validation + - Date range and format validation (no future dates, no pre-2024 planting) + - Geographic boundary validation (Northeast US focus) + - Tree source categorization +- **Clear, human-readable error reports** grouped by Excel row +- **Command-line interface** with optional CSV error export +- **Debug mode** for troubleshooting -- Python 3.8+ -- pandas -- openpyxl (for `.xlsx` support) +--- -## Installation +## 📋 Validation Rules +| Field | Requirements | +|--------------------|--------------| +| **Participant Type** | Must be one of: `landowner`, `community`, `professional`, `municipality`, `agency` | +| **Plant Start** | Required, valid date, on or after Jan 1, 2024, not in the future | +| **Plant End** | Required, valid date, not in the future | +| **Latitude** | Required, numeric, between **40.4774** and **45.01585** | +| **Longitude** | Required, numeric, between **-79.5** and **-71.1** | +| **Tree Source** | Required, one of: `local`, `regional`, `national`, `plant_sale`, `self`, `other` | + +--- + +## 🚀 Installation + + + +1. Clone the repository: + ```bash + git clone + cd tree-planting-validator + + ``` + +2. (Optional but recommended) Create a virtual environment: + ```bash + python -m venv venv + source venv/bin/activate # Linux/Mac + # venv\Scripts\activate # Windows + ``` + +3. Install dependencies: + ```bash + pip install pandas openpyxl + ``` + +--- + +## 📖 Usage + +### Basic usage ```bash -git clone https://your-gitea-instance.com/yourusername/tree-planting-data-validator.git -cd tree-planting-data-validator +python validate_tree_planting_data.py "path/to/your/data.xlsx" +``` -# Recommended: use a virtual environment -python -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate +### With options +```bash +python validate_tree_planting_data.py "data.xlsx" \ + --header-row 2 \ + --debug \ + --output errors_report.csv +``` -pip install pandas openpyxl -Usagebash +--- -python validate_tree_planting_data.py "path/to/your_data.xlsx" +## Command Line Arguments -OptionsArgument -Description -Default -excel_file_path -Path to the Excel file -- ---header-row -Row number containing headers -1 ---debug -Show debug information -False ---output -Save errors to CSV file -- +| Argument | Description | Default | +|-------------------|--------------------------------------------------|------------| +| `excel_file_path` | Path to the Excel file (required) | - | +| `--header-row` | Row number containing column headers | `1` | +| `--debug` | Enable debug output | `False` | +| `--output` | Save validation errors to a CSV file | None | -Example:bash +--- -# Basic usage -python validate_tree_planting_data.py planting_data_2025.xlsx +## Example Output -# With custom header and output report -python validate_tree_planting_data.py data.xlsx --header-row 2 --output errors.csv --debug +**Success:** +``` +========================================================================================== +✅ VALIDATION SUCCESSFUL +Processed 245 records +========================================================================================== +``` -Project Structure +**With Errors:** +``` +❌ VALIDATION REPORT +Total records processed : 245 +Total errors found : 12 -tree-planting-data-validator/ -├── validate_tree_planting_data.py # Main script -├── README.md -├── LICENSE -└── examples/ # (optional) sample Excel files +📍 Excel Row 47 +----------------------------------------------------------------- + • Plant Start..................... Future date + • Longitude....................... Out of range +``` -Roadmap / Future EnhancementsField-level validation (dates, coordinates, species names, etc.) -Duplicate detection -Summary statistics (trees per species, region, etc.) -Web interface / CLI dashboard -Support for CSV input +--- -LicenseMIT License — feel free to use and adapt for your tree-planting projects. +## File Requirements +- Excel file (`.xlsx` or `.xls`) +- Header row with recognizable column names (case-insensitive) +- At minimum: `Participant Type`, `Plant Start`, `Plant End`, `Latitude`, `Longitude`, `Tree Source` + +--- + +## Contributing + +Contributions are welcome! Feel free to submit issues or pull requests for: +- Additional validation rules +- Support for more file formats +- Enhanced reporting features + +--- + +## License + +This project is open source. Feel free to use and modify as needed. + +--- + +**Made for tree planting initiatives** 🌱