Shape Scaler¶
Simple Example¶
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
- original_df (GeoPandas DataFrame) – GeoPandas Dataframe previously passed to
-
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
-