A Cartogram object acts as a generator on a specific dataset, through which generation algorithms can be run.

Parameters

• gdf : geopandas.GeoDataFrame - The dataset that you want to apply cartogram techniques to
• value_field : String - Field in the dataset to apply cartogram techniques to; the values themselves should be integer or float values
• id_field : String - Field of the identifier for each region in the dataset; the id values should be unique so that the generated cartograms can be linked back to original data
• geometry_field : String, optional, default 'geometry' - Field containing the geometries of each region

Example

from pycart import cartogram
import geopandas as gpd

my_geodf = gpd.read_file("path/to/dataset.csv")

cart = cartogram.Cartogram(my_geodf, value_field='Population', id_field='Name', geo_field='Geometry')

Calculates and returns a Non-Contiguous cartogram in the form of a GeoDataFrame.

A Non-Contiguous cartogram [1] is created by scaling each region in-place by a specific density (value field divided by geographical area), about an anchor region. The anchor region is usually the region with the highest density.

Suppose we have an anchor unit $H$ of area $A_H$ and value $V_H$ and a miscellaneous region $J$, with area $A_J$ and value $V_J$. The scaling value applied to $J$ is:

$(\sqrt{V_H / A_H})^{-1} \cdot \sqrt{V_J / A_J}$

Parameters

• size_value : int, optional, default 1.0 - A simple multiplier to scaling; larger values accentuate scaling.

Returns

• geopandas.GeoDataFrame - Scaled form of original dataset

Example

from pycart import cartogram
import matplotlib.pyplot as plt
import geopandas as gpd

# Load dataset into Cartogram generator
my_geodf = gpd.read_file("path/to/dataset.csv")
cart = cartogram.Cartogram(my_geodf, value_field='Population', id_field='Name', geo_field='Geometry')

# Create Non-Contiguous cartogram
non_con = cart.non_contiguous(size_value=1.0)

# Plot data
fig, ax = plt.subplots(1, figsize=(4, 4))
ax.axis('equal')
ax.axis('off')

my_geodf.plot(color='w', ax=ax, alpha=0.8, zorder=0,  edgecolor='0', linewidth=0.1, legend=False)
non_con.plot(color='r', ax=ax, edgecolor='0', linewidth=0.1, legend=False)

plt.show()

Runs the Dorling cartogram algorithm and returns the generated cartogram in the form of a GeoDataFrame.

A Dorling cartogram [2] represents each region as a circle, with the radius being proportional to the density of the given region. The regions are then moved via a gravity-like force model.

The radius of a given region $J$ is calculated over multiple steps, with Steps 1 and 2 being carried out by border_util.get_borders():

1. Use Queen contiguity to find all neighbours of a region $J$; Queen contiguity acts similarly to a Moore neighbourhood, where a neighbour is a region that shares an edge or a vertex.
2. Assign weights to each neighbour of $J$ based on the length of perimeter that the neighbour occupies.
3. Calculate the sum $D$, of the pairwise distance (see _paired_distance) from a region to all of its neighbours, for all regions.

4. Calculate the sum $R$, of radii as: $R = \sum (\sqrt{V_M / \pi} + \sqrt{V_N / \pi})$ for all $N$ neighbours and for all $M$ regions

5. Calculate the radius scaling coefficient $k$, as: $k = D / R$

6. Calculate the radius of region $J$: $r_J = k \sqrt{V_J / \pi}$

See the helper functions _attract() and _repel() for more details on how the forces are calculated.

Parameters

• iterations : int, default 100 - The number of iterations to run the Dorling algorithm for.
• ratio : float, optional, default 0.4 - Ratio of attractive force to repulsive force; the larger the ratio, the more attractive force is applied.
• friction : float, optional, default 0.25 - Determines the strength of $x$ and $y$ vectors; acts as a simple multiplier to $x$ and $y$ vectors.
• stop : int, optional, default None - A given iteration at which to halt computation and return the cartogram

Returns

• geopandas.GeoDataFrame - Scaled and Distributed circles based on original dataset

Example

from pycart import cartogram
import matplotlib.pyplot as plt
import geopandas as gpd

# Load dataset into Cartogram generator
my_geodf = gpd.read_file("path/to/dataset.csv")
cart = cartogram.Cartogram(my_geodf, value_field='Population', id_field='Name', geo_field='Geometry')

# Run Dorling algorithm for 100 iterations
dorling = cart.dorling(iterations=100, stop=None)

# Plot data
fig, ax = plt.subplots(1, figsize=(4, 4))
ax.axis('equal')
ax.axis('off')

my_geodf.plot(color='w', ax=ax, alpha=0.8, zorder=0,  edgecolor='0', linewidth=0.1, legend=False)
dorling.plot(color='w', ax=ax, alpha=0.8, zorder=0, edgecolor='0', linewidth=0.1, legend=False)

plt.show()