Maps (datascience.maps)

Draw maps using folium.

class datascience.maps.Circle(lat, lon, popup='', color='blue', area=314.1592653589793, **kwargs)

A marker displayed with either Folium’s circle_marker or circle methods.

The circle_marker method draws circles that stay the same size regardless of map zoom, whereas the circle method draws circles that have a fixed radius in meters. To toggle between them, use the radius_in_meters flag in the draw_on function.

popup – text that pops up when marker is clicked color – fill color area – pixel-squared area of the circle

Defaults from Folium:

fill_opacity: float, default 0.6

Circle fill opacity

More options can be passed into kwargs by following the attributes listed in https://leafletjs.com/reference-1.4.0.html#circlemarker or https://leafletjs.com/reference-1.4.0.html#circle.

For example, to draw three circles with circle_marker:

t = Table().with_columns([
        'lat', [37.8, 38, 37.9],
        'lon', [-122, -122.1, -121.9],
        'label', ['one', 'two', 'three'],
        'color', ['red', 'green', 'blue'],
        'area', [3000, 4000, 5000],
    ])
Circle.map_table(t)

To draw three circles with the circle methods, replace the last line with:

Circle.map_table(t, radius_in_meters=True)

draw_on(folium_map, radius_in_meters=False)

Add feature to Folium map object.

class datascience.maps.Map(features=(), ids=(), width=960, height=500, **kwargs)

A map from IDs to features. Keyword args are forwarded to folium.

color(values, ids=(), key_on='feature.id', palette='YlOrBr', **kwargs)

Color map features by binning values.

values – a sequence of values or a table of keys and values ids – an ID for each value; if none are provided, indices are used key_on – attribute of each feature to match to ids palette – one of the following color brewer palettes:

‘BuGn’, ‘BuPu’, ‘GnBu’, ‘OrRd’, ‘PuBu’, ‘PuBuGn’, ‘PuRd’, ‘RdPu’, ‘YlGn’, ‘YlGnBu’, ‘YlOrBr’, and ‘YlOrRd’.

Defaults from Folium:

threshold_scale: list, default None

Data range for D3 threshold scale. Defaults to the following range of quantiles: [0, 0.5, 0.75, 0.85, 0.9], rounded to the nearest order-of-magnitude integer. Ex: 270 rounds to 200, 5600 to 6000.

fill_opacity: float, default 0.6

Area fill opacity, range 0-1.

line_color: string, default ‘black’

GeoJSON geopath line color.

line_weight: int, default 1

GeoJSON geopath line weight.

line_opacity: float, default 1

GeoJSON geopath line opacity, range 0-1.

legend_name: string, default None

Title for data legend. If not passed, defaults to columns[1].

copy()

Copies the current Map into a new one and returns it. Note: This only copies rendering attributes. The underlying map is NOT deep-copied. This is as a result of no functionality in Folium. Ref: https://github.com/python-visualization/folium/issues/1207

property features

format(**kwargs)

Apply formatting.

geojson()

Render features as a FeatureCollection.

overlay(feature, color='Blue', opacity=0.6)

Overlays feature on the map. Returns a new Map.

Args:

feature: a Table of map features, a list of map features,

a Map, a Region, or a circle marker map table. The features will be overlayed on the Map with specified color.

color (str): Color of feature. Defaults to ‘Blue’

opacity (float): Opacity of overlain feature. Defaults to

0.6.

Returns:

A new Map with the overlain feature.

classmethod read_geojson(path_or_json_or_string_or_url)

Read a geoJSON string, object, file, or URL. Return a dict of features keyed by ID.

class datascience.maps.Marker(lat, lon, popup='', color='blue', **kwargs)

A marker displayed with Folium’s simple_marker method.

popup – text that pops up when marker is clicked color – The color of the marker. You can use: [‘red’, ‘blue’, ‘green’, ‘purple’, ‘orange’, ‘darkred’, ’lightred’, ‘beige’, ‘darkblue’, ‘darkgreen’, ‘cadetblue’, ‘darkpurple’, ‘white’, ‘pink’, ‘lightblue’, ‘lightgreen’, ‘gray’, ‘black’, ‘lightgray’] to use standard folium icons. If a hex color code is provided, (color must start with ‘#’), a folium.plugin.BeautifyIcon will be used instead.

Defaults from Folium:

marker_icon: string, default ‘info-sign’

icon from (http://getbootstrap.com/components/) you want on the marker

clustered_marker: boolean, default False

boolean of whether or not you want the marker clustered with other markers

icon_angle: int, default 0

angle of icon

popup_width: int, default 300

width of popup

The icon can be further customized by by passing in attributes into kwargs by using the attributes listed in https://python-visualization.github.io/folium/modules.html#folium.map.Icon.

copy()

Return a deep copy

draw_on(folium_map)

Add feature to Folium map object.

format(**kwargs)

Apply formatting.

geojson(feature_id)

GeoJSON representation of the marker as a point.

property lat_lons

Sequence of lat_lons that describe a map feature (for zooming).

classmethod map(latitudes, longitudes, labels=None, colors=None, areas=None, other_attrs=None, clustered_marker=False, **kwargs)

Return markers from columns of coordinates, labels, & colors.

The areas column is not applicable to markers, but sets circle areas.

Arguments: (TODO) document all options

index_map: list of integers, default None (when not applicable)

list of indices that maps each marker to a corresponding label at the index in cluster_labels (only applicable when multiple marker clusters are being used)

cluster_labels: list of strings, default None (when not applicable)

list of labels used for each cluster of markers (only applicable when multiple marker clusters are being used)

colorbar_scale: list of floats, default None (when not applicable)

list of cutoffs used to indicate where the bins are for each color (only applicable when colorscale gradient is being used)

include_color_scale_outliers: boolean, default None (when not applicable)

boolean of whether or not outliers are included in the colorscale gradient for markers (only applicable when colorscale gradient is being used)

radius_in_meters: boolean, default False

boolean of whether or not Circles should have their radii specified in meters, scales with map zoom

clustered_marker: boolean, default False

boolean of whether or not you want the marker clustered with other markers

other_attrs: dictionary of (key) property names to (value) property values, default None

A dictionary that list any other attributes that the class Marker/Circle should have

classmethod map_table(table, clustered_marker=False, include_color_scale_outliers=True, radius_in_meters=False, **kwargs)

Return markers from the columns of a table.

The first two columns of the table must be the latitudes and longitudes (in that order), followed by ‘labels’, ‘colors’, ‘color_scale’, ‘radius_scale’, ‘cluster_by’, ‘area_scale’, and/or ‘areas’ (if applicable) in any order with columns explicitly stating what property they are representing.

Args:

cls: Type of marker being drawn on the map {Marker, Circle}.

table: Table of data to be made into markers. The first two columns of the table must be the latitudes and longitudes (in that order), followed by ‘labels’, ‘colors’, ‘cluster_by’, ‘color_scale’, ‘radius_scale’, ‘area_scale’, and/or ‘areas’ (if applicable) in any order with columns explicitly stating what property they are representing. Additional columns for marker-specific attributes such as ‘marker_icon’ for the Marker class can be included as well.

clustered_marker: Boolean indicating if markers should be clustered with folium.plugins.MarkerCluster.

include_color_scale_outliers: Boolean indicating if outliers should be included in the color scale gradient or not.

radius_in_meters: Boolean indicating if circle markers should be drawn to map scale or zoom scale.

class datascience.maps.Region(geojson, **kwargs)

A GeoJSON feature displayed with Folium’s geo_json method.

copy()

Return a deep copy

draw_on(folium_map)

Add feature to Folium map object.

format(**kwargs)

Apply formatting.

geojson(feature_id)

Return GeoJSON with ID substituted.

property lat_lons

A flat list of (lat, lon) pairs.

property polygons

Return a list of polygons describing the region.

• Each polygon is a list of linear rings, where the first describes the exterior and the rest describe interior holes.

• Each linear ring is a list of positions where the last is a repeat of the first.

• Each position is a (lat, lon) pair.

property properties

property type

The GEOJSON type of the regions: Polygon or MultiPolygon.

datascience.maps.get_coordinates(table, replace_columns=False, remove_nans=False)

Adds latitude and longitude coordinates to table based on other location identifiers. Must be in the United States.

Takes table with columns “zip code” or “city” and/or “county” and “state” in column names and adds the columns “lat” and “lon”. If a county is not found inside the dataset, that row’s latitude and longitude coordinates are replaced with np.nans. The ‘replace_columns’ flag indicates if the “city”, “county”, “state”, and “zip code” columns should be removed afterwards. The ‘remove_nans’ flag indicates if rows with nan latitudes and longitudes should be removed. Robust to capitalization in city and county names. If a row’s location with multiple zip codes is specified, the latitude and longitude pair assigned to the row will correspond to the smallest zip code.

Dataset was acquired on July 2, 2020 from https://docs.gaslamp.media/download-zip-code-latitude-longitude-city-state-county-csv. Found in geocode_datasets/geocode_states.csv. Modified column names and made city/county columns all in lowercase.

Args:

table: A table with counties that need to mapped to coordinates replace_columns: A boolean that indicates if “county”, “city”, “state”, and “zip code” columns should be removed remove_nans: A boolean that indicates if columns with invalid longitudes and latitudes should be removed

Returns:

Table with latitude and longitude coordinates