Initial commit: Set up Territory Analysis Tool

README.md

@@ -0,0 +1,93 @@
+# Territory Analysis Tool
+
+## Overview
+
+This tool provides a complete pipeline for processing and analyzing territory data. It takes raw address and boundary data, combines them, and then generates analytical reports in markdown and interactive HTML map formats.
+
+The workflow is managed by a command-line script that gives the user fine-grained control over the execution process.
+
+## File Structure
+
+All necessary files are located in this directory.
+
+### Core Scripts
+
+- `run_all.py`: The main command-line script to run the workflow. **This is the recommended entry point.**
+- `process_territories.py`: (Step 1) Combines address and boundary data.
+- `analysis.py`: (Step 2) Performs general territory analysis and generates `map.html`.
+- `category_analysis.py`: (Step 2) Performs category-specific analysis and generates `category_map.html`.
+
+### Input Data Files
+
+- The tool is designed to work with any address and boundary CSV files.
+- The example files `Okinawa Territory Jan 2026 - Addresses.csv` and `Okinawa Territory Jan 2026 - Boundaries.csv` are provided.
+
+These two files can be found in NW Scheduler. Go to export -> Territories, and download them both from there.
+
+## Usage
+
+The entire workflow is managed through `run_all.py` using a command-line interface. You can see all available commands by running:
+
+```bash
+python run_all.py --help
+```
+
+### Full Pipeline Run
+
+To run the entire process from start to finish (process raw files and then analyze them), use the `full-run` command. This is the most common use case.
+
+**Command:**
+
+```bash
+python run_all.py full-run --addresses <path_to_addresses.csv> --boundaries <path_to_boundaries.csv>
+```
+
+**Example:**
+
+```bash
+python run_all.py full-run --addresses "Okinawa Territory Jan 2026 - Addresses.csv" --boundaries "Okinawa Territory Jan 2026 - Boundaries.csv"
+```
+
+### Running Steps Individually
+
+You can also run each step of the pipeline separately.
+
+#### Step 1: Process Raw Files
+
+To combine the address and boundary files into a single "Final" CSV, use the `process` command.
+
+**Command:**
+
+```bash
+python run_all.py process --addresses <path_to_addresses.csv> --boundaries <path_to_boundaries.csv>
+```
+
+This will generate a new file named `Okinawa Territory <Mon Year> - Final.csv`.
+
+#### Step 2: Analyze a Processed File
+
+To run the analysis and generate maps from a "Final" CSV file, use the `analyze` command.
+
+**Command:**
+
+```bash
+python run_all.py analyze --input <path_to_final_file.csv>
+```
+
+**Example:**
+
+```bash
+python run_all.py analyze --input "Okinawa Territory Dec 2025 - Final.csv"
+```
+
+## Workflow Details
+
+1.  **Data Processing:** The `process_territories.py` script reads the `Addresses.csv` to count addresses per `TerritoryID` and merges this count into the `Boundaries.csv` file. It outputs a new CSV file named in the format `Okinawa Territory Mon Year - Final.csv`.
+2.  **Data Analysis:** The `analysis.py` and `category_analysis.py` scripts take the `Final.csv` file as input to generate reports and interactive maps.
+
+## Output Files
+
+- `Okinawa Territory <Mon Year> - Final.csv`: The consolidated data file.
+- `analysis.md`: A markdown summary of the general territory analysis.
+- `map.html`: An interactive map visualizing territories colored by address count.
+- `category_map.html`: An interactive map visualizing territories colored by their category's total address count.