94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
# 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.
|