CARTOframes

A Python package for integrating CARTO maps, analysis, and data services into data science workflows.

Legends

In this guide, we explore the different types of legends available for your CARTOframes visualizations.

Legend Types

When we set the legend, we have to indicate the type of the legend to use. This will be defined by the type of data (number, category) and visualization method (color,size) you use to represent the information.

Current types are:

  • Color
    • color-category
    • color-bins
    • color-continuous
  • Size
    • size-category
    • size-bins
    • size-continuous

Classified by styling property

The list of legend types above are broken into two groupls: color and size.

  • Color types represent color style properties: color and strokeColor.
  • Size types represent size style properties: width and strokeWidth.

Classified by data type

Each color and size legend types have three options: category, bins, and continuous.

  • Category legends: for use with categorical data.
  • Bins legends: for use with numeric data.
  • Continuous legends: for use with numeric data.

By default, each legend type detects the geometry of a layer. However, we explicitly set the geometry, which is very useful when using several legend types on one map.

Default Legend

1
2
3
4
Map(
    Layer('populated_places'),
    default_legend=True
)

Add information

1
2
3
4
5
6
7
8
9
10
Map(
    Layer(
        'populated_places',
        legend={
            'title': 'Populated Places',
            'description': 'This is a common dataset.',
            'footer': 'Source: CARTO'
        }
    )
)

Add title, description and footer to the Legend

Color Category

  • color-category-point
  • color-category-line
  • color-category-polygon

Example:

1
2
3
4
5
6
7
8
9
Map(
    Layer(
        'populated_places',
        'color: ramp(top($adm0name, 5), bold)',
        legend=Legend({
            'type': 'color-category-point'
        })
    )
)

color-category legend

Color Bins

  • color-bins-point
  • color-bins-line
  • color-bins-polygon

Example:

1
2
3
4
5
6
7
8
9
Map(
    Layer(
        'sfcta_congestion_roads',
        'color: ramp(globalEqIntervals($auto_speed, 5), purpor)',
        legend={
            'type': 'color-bins-line'
        }
    )
)

color-bins legend

Color Continuous

  • color-continuous-point
  • color-continuous-line
  • color-continuous-polygon

Example:

1
2
3
4
5
6
7
8
9
10
Map(
    Layer(
        'sf_neighborhoods',
        'color: ramp(linear($cartodb_id), sunset)',
        legend={
            'type': 'color-continuous-polygon',
            'prop': 'color'
        }
    )
)

color-continuous legend

Size Category

  • size-category-point
  • size-category-line

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
Map(
    Layer(
        'populated_places',
        '''
        width: ramp(buckets($adm_0_cap_name, ["Capital", "City"]), [25, 5])
        strokeWidth: 1
        strokeColor: white
        ''',
        legend={
            'type': 'size-category-point'
        }
    )
)

size-category legend

Size Bins

  • size-bins-point
  • size-bins-line

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Map(
    Layer(
        'sfcta_congestion_roads',
        '''
        width: ramp(globalEqIntervals($auto_speed, 5), [1, 10])
        color: opacity(turquoise, 0.8)
        strokeWidth: 0.5
        strokeColor: opacity(blue,0.2)
        ''',
        legend={
            'type': 'size-bins-line'
        }
    )
)

size-bins legend

Size Continuous

  • size-continuous-point
  • size-continuous-line

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Map(
    Layer(
        'county_points_with_population',
        '''
        width: ramp(linear($estimate_total), [1, 80])
        color: opacity(turquoise, 0.8)
        strokeWidth: 0.5
        strokeColor: opacity(blue,0.4)
        order: asc(width())
        ''',
        legend={
            'type': 'size-continuous-point',
            'title':'Population by County'
        }
    )
)

size-continuous legend

Multiple Legends

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Map([
    Layer(
        'maximum_heat_index',
        'color: ramp(linear($value), purpor)',
        legend={
            'type': 'color-continuous-point',
            'title': 'Heat Index Values'
        }
    ),
    Layer(
        'county_points_with_population',
        '''
        width: ramp(globalEqIntervals($estimate_total,5), [2, 40])
        color: opacity(turquoise, 0.8)
        strokeWidth: 0.5
        strokeColor: opacity(blue,0.2)
        ''',
        legend={
            'type': 'size-continuous-point',
            'title': 'Population by Counti'
        }
    )
])

Multiple legends