Territory-Analysis---Mapper/README.md

Territory Analysis Tool v1.2.0

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.

Installation

This tool requires Python 3 and has a few dependencies.

1. Install dependencies: Navigate to this directory in your terminal and run the following command to install the required Python libraries:

   pip install -r requirements.txt
   

File Structure

All necessary files are located in this directory.

• run_all.py: The main command-line script to run the workflow.
• process_territories.py: A module that combines address and boundary data.
• analysis.py: A module that performs general territory analysis.
• category_analysis.py: A module that performs category-specific analysis.
• requirements.txt: A list of Python dependencies.

Input Data Files

The tool requires two CSV files: an "addresses" file and a "boundaries" file. These can be exported directly from NW Scheduler.

Usage

The entire workflow is managed through run_all.py. You can see all commands by running:

python run_all.py --help

Full Pipeline Run

To run the entire process from start to finish in memory, use the full-run command.

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

Step 1: Process Raw Files

To combine the address and boundary files and save the result to a CSV, use the process command.

Command:

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

Step 2: Analyze a Processed File

To run analysis from a "Final" CSV file, use the analyze command.

Command:

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

Changelog

v1.2.0 (Current)

• Refactored the tool from a collection of separate scripts into a single, integrated Python application.
• Replaced subprocess calls with direct function imports for improved performance and reliability.
• Integrated the pandas library for more efficient in-memory data processing.
• The full-run command now processes data in memory without writing an intermediate CSV file.
• Added a requirements.txt file for easier dependency management.

v1.1.0

• Introduced a command-line interface with argparse to replace the interactive menu.
• Added process, analyze, and full-run commands.
• Allowed for dynamic input file paths via command-line arguments.

v1.0.0

• Initial release with separate scripts for processing and analysis.
• Workflow managed by an interactive run_all.py script.
• Project structure consolidated into a single directory.
• Git repository initialized.