Territory-Analysis---Mapper/README.md

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:

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:

python run_all.py full-run --addresses <path_to_addresses.csv> --boundaries <path_to_boundaries.csv>

Example:

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:

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:

python run_all.py analyze --input <path_to_final_file.csv>

Example:

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.