Generate Contiguous Cartogram (Cartography)

Summary

Generates a cartogram by distorting the area of polygons to be proportional to each other based on a numeric field while preserving shared boundaries.

Illustration

Shared boundaries are maintained while the size and shape of input polygons are distorted so that the area of each feature represents the value of an attribute field, which in this case represents the total population of each feature.

Usage

• The output will be a new polygon feature layer with the polygons transformed so that the area of each feature is proportional to the value of a numeric field compared to the sum of that field across all features in the input.

• The input layer's attribute data will be transferred to the output. Symbology and labeling will be transferred when the input is a symbolized layer.

• The Method parameter has the following options:.

  • Flow-Based—This option is an evolution of the Diffusion method and is often faster. The shape of the output polygons may be different or contain slightly more distortion in comparison. This is the default.
  • Diffusion—This option may introduce slightly less distortion to the original shapes than the Flow-Based option while taking longer to complete.
  Each option will attempt to retain the general shape of individual polygons while maintaining shared edges.

• To decrease the processing time, you can run the Simplify Polygon tool on the input features before running this tool. This may result in some output polygons appearing oversimplified if they are distorted to be significantly larger.

• The input data or the active map displaying the data should use an equal area projection appropriate for that region. This is so the visible area of the input polygons will more accurately represent the actual area before being modified. Use the Cartographic Coordinate System environment if there is no active map and the data uses a nonequal area projection. Display the results in the same equal area projection for an accurate depiction of the adjusted feature areas.

• The field values in the Field Name parameter value should be positive numbers. Any features with negative or 0 values will not be present in the output.

• Additional resources:

  Gastner, Michael T. and M. E. J. Newman. 2004. "Diffusion-based method for producing density-equalizing maps." Proceedings of the National Academy of Sciences of the United States of America, 101(20): 7499–7504.

  Gastner, Michael T., Vivien Seguy, and Pratyush More. 2018. "Fast flow-based algorithm for creating density-equalizing map projections." Proceedings of the National Academy of Sciences of the United States of America, 115(10): E2156-E2164.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The input polygon features that will be used to generate the cartogram.	Feature Layer
Field Name	The numeric field containing the values that will determine the area of the polygon features in the output cartogram. Any features with a negative value or a value of 0 will be omitted from the output.	Field
Output Feature Class	The output polygons with the cartogram transformation applied.	Feature Layer
Method (Optional)	Specifies the method that will be used to transform the input and create the cartogram. Flow-based—An evolution of the diffusion method that is often faster will be used, which may increase distortion. This is the default. Diffusion—The diffusion method will be used, which may introduce less distortion than the flow-based method while taking longer to complete.	String

Python

arcpy.cartography.GenerateContiguousCartogram(in_features, field_name, out_features, {method})

Name	Explanation	Data Type
in_features	The input polygon features that will be used to generate the cartogram.	Feature Layer
field_name	The numeric field containing the values that will determine the area of the polygon features in the output cartogram. Any features with a negative value or a value of 0 will be omitted from the output.	Field
out_features	The output polygons with the cartogram transformation applied.	Feature Layer
method (Optional)	Specifies the method that will be used to transform the input and create the cartogram. FLOW-BASED—An evolution of the diffusion method that is often faster will be used, which may increase distortion. This is the default. DIFFUSION—The diffusion method will be used, which may introduce less distortion than the flow-based method while taking longer to complete.	String

Code sample

GenerateContiguousCartogram example (Python window)

The following Python window script demonstrates how to use the GenerateContiguousCartogram function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/admin.gdb"
arcpy.cartography.GenerateContiguousCartogram(
    "countries", 
    "population", 
    "countries_cartogram_population", 
    "FLOW-BASED")

GenerateContiguousCartogram example (stand-alone script)

The following stand-alone script demonstrates how to use the GenerateContiguousCartogram function.

# Name: GenerateContiguousCartogram_sample2.py
# Description: Output a contiguous cartogram of country polyons 
#              based on popuplation.

# Import System Modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data/admin.gdb"

# Set Local Variables
in_features = "countries"
value_field = "population"
out_cartogram = "countries_cartogram_population"
algorithm = "DIFFUSION"

# Execute Generate Contiguous Cartogram
arcpy.cartography.GenerateContiguousCartogram(
    in_features, 
    value_field, 
    out_cartogram, 
    algorithm)

Environments

Cartographic Coordinate System