Shape Scaler

Simple Example

_images/ssdemo.png

NOTE: This example uses the variable df as seen in the example in Loading Common Maps.

import mapscaler as ms

ss = ms.ShapeScaler()
scaled_df = ss.scale_map(df, 'scaleby', map_vel=.001, group_vel=.15, verbose=True)

If verbose, scale_map() will print progress as it goes (truncated below):

Iteration 1
--73 overlapping groups remaining
Iteration 2
--79 overlapping groups remaining
...
[truncated]
...
Iteration 62
--2 overlapping groups remaining
Iteration 63
--1 overlapping groups remaining
Iteration 64
Separated in 64 iterations

Now, let’s visualize the output, scaled_df:

import matplotlib.pyplot as plt
import geoplot as gplt
import numpy as np

gplt.choropleth(
    df, hue=[np.log(x) for x in df.EST_POP_2019],
    projection=gplt.crs.AlbersEqualArea(), cmap='viridis',
    figsize=(15,8),
)
plt.title('BEFORE', fontsize=30, loc='left')
plt.show()

gplt.choropleth(
    scaled_df, hue=[np.log(x) for x in df.EST_POP_2019],
    projection=gplt.crs.AlbersEqualArea(), cmap='viridis',
    figsize=(15,8),
)
plt.title('AFTER', fontsize=30, loc='left')
plt.show()

Documentation

class mapscaler.ShapeScaler

Bases: mapscaler.mapscaler.BaseScaler

get_group_centroid(obj_list)

Calculate the geometric centroid of a group of objects.

Parameters:obj_list (list) – Iterable of Shapely objects (Polygon or MultiPolygon)
Returns:[x,y] coordinates of the entire group’s geometric centroid
Return type:list
get_group_members(original_df, property_col)

Returns the members of each group, given a column from the original dataframe to print. Useful for debugging / inspecting groups that are too slow to separate.

Parameters:
  • original_df (GeoPandas DataFrame) – GeoPandas Dataframe previously passed to scale_map() method
  • property_col (str) – String name of column in original_df that identifies each shape; Typically a name or ID
Returns:

key, value pairs where key is an arbitrary group number and value is a list of property_col values describing the group members

Return type:

dict

get_overlapping_groups(df, geo, buffer)

Return all groups of overlapping shapes in a map.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • geo (str) – string name of the geometry column in df
  • buffer (float) – Euclidean distance required between shapes before they are considered non-overlapping
Returns:

key, value pairs where key is is the group id and value is a list of shape ids.

Return type:

dict

index_geo_col(df, geo)

Returns a mapping of Shape IDs to their initial index in the dataframe.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • geo (str) – string name of the geometry column in df
Returns:

key, value pairs where key is is a shape id, and value is its row index in df

Return type:

dict

index_overlapping_groups()

Return a mapping of Shape IDs to their current overlapping groups; Inverse of get_overlapping_groups().

Returns:key, value pairs where key is a shape id, and value is a group id
Return type:dict
move_shape(shape, movement)

Move a Shapely Polygon by a given movement vector.

Parameters:
  • shape (Shapely Polygon) – Shape to be moved
  • movement (list or tuple) – vector [x,y] describing the movement
Returns:

Shape with updated coordinates

Return type:

Shapely Polygon

nudge_shapes(df, geo, map_vel, group_vel)

Nudge overlapping shapes away from group and map centroids.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • geo (str) – string name of the geometry column in df
  • map_vel (float) – Velocity at which each shape is nudged away from the centroid of the whole map
  • group_vel (float) – Velocity at which each shape is nudged away from the centroid of its respective group of overlapping shapes
Returns:

Dataframe with updated geometry column

Return type:

GeoPandas DataFrame

scale_map(df, scaleby, geo='geometry', map_vel=0.01, group_vel=0.1, buffer=0, max_iter=100, verbose=False)

Automatically scale the parts of any map by any variable, without any overlapping shapes and with minimal distortion.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • scaleby (str) – string name of the column in df with scalar values
  • geo (str) – Optional - string name of the geometry column in df; default is 'geometry'
  • map_vel (float) – Optional - Velocity at which each shape is nudged away from the centroid of the whole map; dfault is .01
  • group_vel (float) – Optional - Velocity at which each shape is nudged away from the centroid of its respective group of overlapping shapes; default is .1
  • buffer (float) – Optional - Euclidean distance required between shapes before they are considered non-overlapping; default is 0
  • max_iter (int) – Optional - Maximum number of attempts to nudge shapes away from each other; default is 100
  • verbose (boolean) – Optional - Whether to print progress as shapes are separated; default is False
Returns:

Dataframe with updated geometry column

Return type:

GeoPandas DataFrame

scale_shapes(df, scaleby, geo)

Scale the Coordinates of all map shapes by their respective scalars.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • scaleby (str) – string name of the column in df with scalar values
  • geo (str) – string name of the geometry column in df

Warning

This function scales by coordinates. Scaling coordinates by \(x\) will scale the area of the shape by \(x^2\). More info: Creating Shape Scalars from a Variable

separate_map(df, geo, map_vel, group_vel, buffer, max_iter, verbose)

Reposition shapes on a map so that none of them overlap.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • geo (str) – String name of the geometry column in df
  • map_vel (float) – Velocity at which each shape is nudged away from the centroid of the whole map
  • group_vel (float) – Velocity at which each shape is nudged away from the centroid of its respective group of overlapping shapes
  • buffer (float) – Euclidean distance required between shapes before they are considered non-overlapping
  • max_iter (int) – Maximum number of attempts to nudge shapes away from each other
  • verbose (boolean) – Whether to print progress as shapes are separated
Returns:

Dataframe with updated geometry column

Return type:

GeoPandas DataFrame

update_group_centroids(df, geo)

Calculate the geometric centroid of all overlapping groups.

Parameters:
  • df (GeoPandas DataFrame) – GeoPandas Dataframe
  • geo (str) – string name of the geometry column in df
Returns:

key, value pairs where key is the group id, and value is the group centroid

Return type:

dict