oneworld.WebMap.add_choropleth

WebMap.add_choropleth(json_file, geoid, color, data=None, json_key='GEOID', palette='Spectral', n_colors=5, cap_min=False, cap_max=False, layer='map', style={'fillOpacity': 0.6, 'opacity': 1.0}, style_mouseover=None, info_mouseover=None, legend_pos='bottomright', legend_ndec=2)

Add a choropleth.

Given a GeoJSON file, color each of its features according to some value provided in the color parameter. For each value in color there should be a value in geoid, which will be used to identidfy the corresponding feature in the file using the json_key parameter, which should be under the properties key of the feature.

Parameters:

  • json_file (str) – Full path name of the GeoJSON file.

  • geoid (list or tuple or str) – Sequence (list or tuple) or name of the column of the dataframe in data containing the string that will be used to identify each feature on the json_file.

  • color (list or tuple or str) – Sequence (list or tuple) or name of the column of the dataframe in data containing the values that will be used to determine the color of each feature. These values can be numeric (float or int) or categorical (str). Alternatively, color can be a hex color that will be applied to all features.

  • data (pandas DataFrame) – Dataframe containing one or more columns of values to use. Each row must contain the data for a feature, with columns as the data to be used (Default: None).

  • json_key (str) – Name of the property (under properties of each feature) that will be used to identify each feature (Default: “GEOID”).

  • palette (list or tuple or str) – Sequence of hex colors to be used to color the features according to their value provided in color. Alternatively, palette can be a string with the name of a seaborn color palette (Default: ‘Spectral’).

  • n_colors (int) – Number of colors in the specified seaborn palette (Default: 5).

  • cap_min (float or int) – If set, all features with a numerical value in color smaller than the value set in cap_min will be considered as having a value equal to cap_min for coloring purposes. The corresponding entry in the legend will display a ‘<’ sign (Default: False).

  • cap_max (float or int) – If set, all features with a numerical value in color greater than the value set in cap_max will be considered as having a value equal to cap_max for coloring purposes. The corresponding entry in the legend will display a ‘>’ sign (Default: False).

  • layer (str) – Name of the layer on which all features will be added. If the specified layer has not yet been created, oneworld will create an overlay with that name using the default settings (Default: “map”, which will add the choropleth directly to the map object).

  • style (dict) – Dictionary containing keywords and values defining common style values for all features. Note that the ‘color’ and ‘fillColor’ keywords defined in style will override those in the color parameters (Default: {‘opacity’:1.0, ‘fillOpacity’:0.6}).

  • style_mouseover (dict) – If set, style of the feature when the mouse is hovered over it (Default: None).

  • info_mouseover (list or tuple or str) – If set, sequence (list or tuple) or name of the column of the dataframe in data containing the information to be displayed on a pannel when the mouse is hovered over the feature. Accepts html format (Default: None).

  • legend_pos ({'topleft', 'topright', 'bottomleft', 'bottomright'}) – Position of the color legend, or None for no legend (Default: “bottomright”).

  • legend_ndec (int) – Number of decimal places to be displayed on the color legend (Default: 2).

See also

add_gejson

Notes

For available color palettes, see https://seaborn.pydata.org/tutorial/color_palettes.html

For a full listing of style options, see https://leafletjs.com/reference-1.6.0.html#path

Examples

A minimal example of how to plot a choropleth using the GeoJSON file “us_states.json” and the “farms” dataframe is:

>>> import oneworld as ow
>>> df = ow.load_dataset("farms")
>>> mymap = ow.WebMap(center = [39,-96.8], zoom = 4)
>>> mymap.add_choropleth(json_file = "us_states.json",
...                      geoid = "FIPS", color = "Region",
...                      data = df, json_key = "GEOID")

In this example, each feature on the file is matched with the row in the dataframe that has the same json_key value of the feature in the geoid column of the dataframe (e.g. the feature with a “GEOID” property of “34” will be associated to the row in df with a value of “34” in the column “FIPS”). Then that feature is colored according to the value of color in that row.

Note that in this case it was not necessary to define the json_key parameter as it uses the same value as its default value value in add_choropleth (“GEOID”), but is included in the example for clarity.