# Urban Harmony

<details>

<summary>Definition</summary>

Urban Harmony (Shannon Entropy) measures the balance of diversity and order in a city’s layout, including street orientations and building patterns. An optimal level of harmony (around 0.5) reflects a well-balanced environment with enough variety to support mixed-use areas while maintaining efficient organization. This balance enhances livability by reducing commute times, increasing access to amenities, and fostering resilience through adaptable, flexible spaces.

</details>

<details>

<summary>Navigation</summary>

Urban Harmony is visualized as a heatmap, allowing users to explore entropy scores across the city.

* Blue areas represent optimal harmony (scores near 0.5), where structure and variation are in balance.
* Red areas indicate low harmony (either overly rigid or overly disordered).
* Clicking on a specific area reveals its Urban Harmony Score, from 0 (perfect rigidity) to 1 (complete disorder).
* Sidebar visualizations compare the selected area’s harmony level to others in the city.

</details>

<details>

<summary>Methodology</summary>

Urban Harmony is calculated using Shannon entropy, a method from information theory that measures the level of disorder in a system.

To compute this KPI:

* First, we break down the directions that streets run in into a number of angle “bins” (like slices of a pie).
* We calculate how many streets fall into each direction bin, both by count (unweighted) and by length (weighted).
* A city with streets evenly spread in every direction has high entropy (disorder).
* A city where streets follow just one or two main directions has low entropy (more order).
* We then compare the observed entropy to an idealized grid and to the maximum possible entropy to get a normalized score.
* The result is a value between 0 and 1, where 0 means totally perfectly grid-like, 1 means totally disorderly, and 0.5 is the ideal mix

</details>

<details>

<summary>Calculation</summary>

Unweighted Entropy:

$$H\_0 = -\sum\_{i=1}^{n} P(o\_i) \log\_e P(o\_i)$$

Where:

* $$P(o\_i)$$ = Proportion of streets in bin i (unweighted)
* $$n$$ = Total number of orientation bins

Weighted Entropy

$$H\_w = -\sum\_{i=1}^{n} P(w\_i) \log\_e P(w\_i)$$

Where:

* $$P(w\_i)$$ = Proportion of total street length in bin i

$$f(x) = x \* e^{2 pi i \xi x}$$$$\varphi = 1 - \left( \frac{H\_0 - H\_g}{H\_{\text{max}} - H\_g} \right)$$

Where:

* $$H\_0$$ = Observed unweighted entropy
* $$H\_g$$ = Entropy of an idealized four-way grid
* $$H\_{max}$$ = Maximum entropy (uniform distribution across bins)

</details>

<details>

<summary>Interpretation</summary>

* Scores near 0.5 signify optimal harmony: ideal balance of structure and diversity (shown in blue)
* Scores below 0.3 or above 0.7 are less harmonious: either too rigid or too chaotic (shown in red)
* Very low scores may signal overly rigid or repetitive layouts
* Very high scores may reflect fragmented, unplanned urban areas

Cities with optimal Urban Harmony tend to show:

* Efficient circulation and navigation
* Well-integrated land use patterns
* Spatial diversity without visual or functional chaos

</details>