# appliedmechanics-eafit/urban_morphology architecture

> Architecture diagram of the GitHub repository appliedmechanics-eafit/urban_morphology, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/appliedmechanics-eafit/urban_morphology
- Repository: https://github.com/appliedmechanics-eafit/urban_morphology

## Overview

##### Project type and purpose
- This is a standalone geospatial data‑analysis pipeline (open‑source tool) for “urban_morphology.”
- It ingests shapefiles and Excel data (“Data_ABC”), fetches and caches street networks (via OSMnx), computes graph‑theoretic metrics (centralities, clustering), and emits cleaned data, metric tables, geojsons, and interactive HTML visualizations.

##### File structure
Top‑level “Code/” directory breaks down into:
- Data_ABC/ – raw Excel inputs and cleaned versions
- Poligonos_Medellin/ – input shapefiles, derived geojson, and all per‑polygon results (subfolders for static stats, disaggregated measures, clustering outputs)
- cache/ – JSON files caching OSMnx network responses
- Graphs_Cities/ – HTML outputs for each centrality measure by city
- Metrics_City/ – consolidated Excel sheets of computed metrics
- Cleaning & orchestration scripts:
– cleaning_DATA_ABC.py
– Poligonos_Medellin.py (loads shapefiles, drives spatial joins)
– network_Indicators.py (fetch + compute network metrics)
– Main.py (top‑level pipeline runner)
– Lecture.py (likely presentation‐style demo or plotting)

##### README insights
- Minimal—but name “urban_morphology” confirms tool’s focus on city form analysis.

##### Main components & interactions
1. Input Data Layer
– Excel reader (Data_ABC/*.xlsx)
– Shapefile reader (Poligonos_Medellin/*.shp → GeoDataFrame)
2. Preprocessing Module
– cleaning_DATA_ABC.py → cleans raw Excel → cleaned CSV/Excel
3. Network Engine
– network_Indicators.py
- Calls OSMnx to pull street network → caches JSON in Code/cache
- Uses networkx to compute centralities (degree, betweenness, closeness, pagerank, eigenvector, local scaling)
4. Polygon Processor
– Poligonos_Medellin.py
- Takes cleaned data + network metrics + geometry → spatial joins → per‐polygon stats
5. Orchestrator
– Main.py
- Invokes preproc → network engine → polygon processing → graph generator
6. Visualization Layer
– Generates HTML in Graphs_Cities/ and geojson in Poligonos_Medellin/Json_files
– Lecture.py for summary plots/tables
7. Output Stores
– Code/Resultados (urban patterns cluster)
– Poligonos_Medellin/Resultados (Excel, CSV, TXT, geojson)
– Metrics_City (Excel metrics)
– Graphs_Cities (interactive HTML)

– Raw Excel → Preprocessing → cleaned CSV/Excel
– Cleaned CSV + Shapefile → Polygon Processor
– Polygon Processor requests street network → Network Engine → OSM API (external)
– Network Engine caches API responses → Code/cache
– Network metrics → back to Polygon Processor → per‐polygon tables
– Outputs → Visualization Layer → HTML & geojson → Output Stores

C. Architectural patterns & principles
– Separation of concerns: each script/module has a single responsibility
– Caching layer: prevents redundant API calls (idempotent fetch)
– Modular I/O: data stores (Excel, shapefiles, JSON caches, HTML, geojson) treated as isolated components

D. Key technologies & libraries
– Python
– pandas, geopandas for data load/clean
– OSMnx + networkx for network fetch & metrics
– matplotlib/folium or built‑in OSMnx HTML export for visualizations
– shapely for geometry ops
– standard I/O: CSV, XLSX, geojson, HTML

- Blue rectangles for code modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Data Layer
    subgraph "Input Data Layer"
        ExcelFile["DATOS_THE_ABC.xlsx"]:::dataStore
        Shapefiles["Shapefiles (.shp, .dbf, .prj)"]:::dataStore
    end

    %% Preprocessing Module
    Cleaner["cleaning_DATA_ABC.py"]:::module
    CleanedExcel["Data_The_ABC_cleaned.xlsx"]:::dataStore

    %% Orchestrator
    Orchestrator["Main.py"]:::module

    %% Network Engine
    subgraph "Network Engine"
        NetworkEngine["network_Indicators.py"]:::module
        Cache["Cache (JSON)"]:::dataStore
        OSMAPI["OSM API"]:::external
    end

    %% Polygon Processor
    subgraph "Polygon Processor"
        PolygonProcessor["Poligonos_Medellin.py"]:::module
        JSONExports["GeoJSON Files"]:::dataStore
        PolygonResults["Resultados (per-polygon)"]:::dataStore
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        Graphs["Interactive HTML Visualizations"]:::dataStore
        Lecture["Lecture.py"]:::module
    end

    %% Output Stores
    subgraph "Output Stores"
        MetricsStore["Centralidades_Pasto, Colombia.xlsx"]:::dataStore
        OutputCluster["urbano_pattern_cluster"]:::dataStore
    end

    %% Data Flows
    ExcelFile --> Cleaner
    Cleaner --> CleanedExcel
    CleanedExcel --> PolygonProcessor
    Shapefiles --> PolygonProcessor

    Orchestrator --> Cleaner
    Orchestrator --> NetworkEngine
    Orchestrator --> PolygonProcessor
    Orchestrator --> Lecture

    NetworkEngine -->|"fetch"| OSMAPI
    OSMAPI -->|"response"| NetworkEngine
    NetworkEngine -->|"cache JSON"| Cache
    NetworkEngine -->|"metrics"| PolygonProcessor

    PolygonProcessor --> JSONExports
    PolygonProcessor --> PolygonResults
    PolygonProcessor --> MetricsStore
    PolygonProcessor --> OutputCluster
    PolygonProcessor --> Graphs

    %% Click Events
    click ExcelFile "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Data_ABC/DATOS_THE_ABC.xlsx"
    click Cleaner "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/cleaning_DATA_ABC.py"
    click CleanedExcel "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Data_ABC/Data_The_ABC_cleaned.xlsx"
    click Orchestrator "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Main.py"
    click NetworkEngine "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/network_Indicators.py"
    click Cache "https://github.com/appliedmechanics-eafit/urban_morphology/tree/main/Code/cache/"
    click PolygonProcessor "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Poligonos_Medellin.py"
    click JSONExports "https://github.com/appliedmechanics-eafit/urban_morphology/tree/main/Code/Poligonos_Medellin/Json_files/"
    click PolygonResults "https://github.com/appliedmechanics-eafit/urban_morphology/tree/main/Code/Poligonos_Medellin/Resultados/"
    click Graphs "https://github.com/appliedmechanics-eafit/urban_morphology/tree/main/Code/Graphs_Cities/"
    click Lecture "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Lecture.py"
    click MetricsStore "https://github.com/appliedmechanics-eafit/urban_morphology/blob/main/Code/Metrics_City/Centralidades_Pasto, Colombia.xlsx"
    click OutputCluster "https://github.com/appliedmechanics-eafit/urban_morphology/tree/main/Code/Resultados/urbano_pattern_cluster/"

    %% Styles
    classDef module fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef dataStore fill:#ABEBC6,stroke:#1D8348,color:#1B2631;
    classDef external fill:#F9E79F,stroke:#B7950B,color:#1B2631,stroke-dasharray: 5 5;
```
