Widget Tricks - ods-color-gradient + ods-map : a choropleth alternative

This map rendering technique allows to display on a map colored shaped based on the aggregation of a different dataset.

One dataset contains the data to make some statistical computation (Avg, sum, counting of numerical fields) and one dataset contains geographical information (geo shapes).

The technique is very similar to a join at processing time, to enrich statistical data with geographical data. The only prerequisit is, like for a regular join, having a shared key between datasets to make the numerical aggregation match its geo shape.

Big advantages are mainly to not overweight the statistical dataset by a processing join and storing multiple times the same geo shape in the data. and secondly to choose the geographical granularity or administrative level only when you render the map. A same statistical dataset can now be rendered with several geographical referentials as long as it contains all the needed keys, codes or names to match the geographical shapes.

For example: inhabitant dataset of a country can be rendered by region, departement, cities and so on as long as you have the geographical dataset of each administrative layers.

How it works: the technique is to aggregate the data with the ods-color-gradient to obtain the color gradient as a color object. Then feed an ods-map with this color object.

More technical and mathematical information on ods-color-gradient algorithm here

Simple usage with legend on top of the map

Fields in use in : departements-et-collectivites-doutre-mer-france (See it on userclub domain)

dep_code
74
01
44
46

Fields in use in : base-nationale-des-lieux-de-covoiturage-en-france (See it on userclub domain)

dep_code
74
01
44
46

<!-- "dep" context is the official geo-referential from Opendatasoft Data Network -->
<ods-dataset-context context="dep,carpool"
                     dep-dataset="departements-et-collectivites-doutre-mer-france"
                     dep-domain="userclub"
                     carpool-dataset="base-nationale-des-lieux-de-covoiturage-en-france"
                     carpool-domain="userclub">

    <div ods-color-gradient="colorgradient"
         ods-color-gradient-context="carpool"
         ods-color-gradient-x="dep_code"
         ods-color-gradient-serie="COUNT()"
         ods-color-gradient-high="rgb(20, 33, 96)"
         ods-color-gradient-low="rgb(180, 197, 241)">

        <h2>Color departments by number of carpool location</h2>
        <div class="map-container">
            <ods-map>
                <ods-map-layer context="dep"
                               color-categories="colorgradient['colors']"
                               color-by-field="dep_code"
                               color-categories-other="lightgrey"
                               display="categories"
                               shape-opacity="0.95"
                               title="# of carpool parking">
                </ods-map-layer>
            </ods-map>

            <ods-legend title="# of carpool parking"
                        color-gradient="colorgradient"
                        display="linear"
                        no-value-color="lightgrey"
                        decimal-precision="0"></ods-legend>
            </div>
        </div>
    </div>
</ods-dataset-context>

.map-container {
    position: relative;
}

.odswidget.odswidget-legend {
    position: absolute;
    top: 20px;
    left: 57px;
}

ods-color-gradient: Power exponent

The power exponent is used to create a power based scale. The transform applied to value is of the type y = x^k where k, the exponent, can be any real number.

For k = 0.3 : it approximates log scale.
For k = 1 : it is a linear scale.
For k >= 2 : it approximates square scale.

ods-color-gradient-pow-exponent optional parameter defines the scale. If not defined, it will be set to 1 that correspond to a linear scale.

Fields in use in : departements-et-collectivites-doutre-mer-france (See it on userclub domain)

dep_code
74
01
44
46

Fields in use in : base-nationale-des-lieux-de-covoiturage-en-france (See it on userclub domain)

dep_code
74
01
44
46

<!-- "dep" context is the official geo-referential from Opendatasoft Data Network -->
<ods-dataset-context context="dep,carpool"
                     dep-dataset="departements-et-collectivites-doutre-mer-france"
                     dep-domain="userclub"
                     carpool-dataset="base-nationale-des-lieux-de-covoiturage-en-france"
                     carpool-domain="userclub">
    <div class="row">
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientsoften"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()"
                 ods-color-gradient-pow-exponent="0.3">

                <div class="map-container">
                    <h2>Power exponent at 0.3 : soften higher values</h2>
                    <h3>Equivalent to log scale</h3>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientsoften['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>
                </div>
            </div>
        </div>
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientemphasize"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()"
                 ods-color-gradient-pow-exponent="2">

                <div class="map-container">
                    <h2>Power exponent at 2 : emphasize higher values</h2>
                    <h3>Equivalent to square scale</h3>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientemphasize['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>
                </div>
            </div>
        </div>
    </div>
</ods-dataset-context>

ods-color-gradient: Number of classes

ods-color-gradient-nb-classes optional parameter defines the number of groups of values. If not defined, colors will then NOT be grouped, and the corresponding legend will be a linear gradient.

Note: without classes, it’s a simple linear or pow color gradient

Note 2: the more classes you have, the more it looks like a linear color gradient

Fields in use in : departements-et-collectivites-doutre-mer-france (See it on userclub domain)

dep_code
74
01
44
46

Fields in use in : base-nationale-des-lieux-de-covoiturage-en-france (See it on userclub domain)

dep_code
74
01
44
46

<!-- "dep" context is the official geo-referential from Opendatasoft Data Network -->
<ods-dataset-context context="dep,carpool"
                     dep-dataset="departements-et-collectivites-doutre-mer-france"
                     dep-domain="userclub"
                     carpool-dataset="base-nationale-des-lieux-de-covoiturage-en-france"
                     carpool-domain="userclub">
    <div class="row">
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientleft"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()"
                 ods-color-gradient-nb-classes="2">

                <div class="map-container">
                    <h2>Nb classes = 2</h2>
                    <h3>Split values into 2 groups, and therefore 2 colors</h3>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientleft['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>

                    <ods-legend title="# of carpool parking"
                                color-gradient="colorgradientleft"
                                display="steps"
                                no-value-color="lightgrey"
                                decimal-precision="0"></ods-legend>
                    
                </div>
            </div>
        </div>
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientright"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()"
                 ods-color-gradient-nb-classes="8">

                <div class="map-container">
                    <h2>Nb classes = 8</h2>
                    <h3>Split values into 8 groups, and therefore 8 colors</h3>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientright['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>


                    <ods-legend title="# of carpool parking"
                                color-gradient="colorgradientright"
                                display="steps"
                                no-value-color="lightgrey"
                                decimal-precision="0"></ods-legend>
                </div>
            </div>
        </div>
    </div>
</ods-dataset-context>

ods-legend: Display mode

display optional parameter can be linear or steps.

Note: ods-color-gradient-nb-classes parameter is mandatory in order to use ods-legend widget in steps mode

Fields in use in : departements-et-collectivites-doutre-mer-france (See it on userclub domain)

dep_code
74
01
44
46

Fields in use in : base-nationale-des-lieux-de-covoiturage-en-france (See it on userclub domain)

dep_code
74
01
44
46

<!-- "dep" context is the official geo-referential from Opendatasoft Data Network -->
<ods-dataset-context context="dep,carpool"
                     dep-dataset="departements-et-collectivites-doutre-mer-france"
                     dep-domain="userclub"
                     carpool-dataset="base-nationale-des-lieux-de-covoiturage-en-france"
                     carpool-domain="userclub">
    <div class="row">
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientleft"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()">

                <div class="map-container">
                    <h2>No class, linear scale</h2>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientleft['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>

                    <ods-legend title="display=linear (default value)"
                                color-gradient="colorgradientleft"
                                no-value-color="lightgrey"
                                decimal-precision="0"></ods-legend>
                    
                </div>
            </div>
        </div>
        <div class="col-sm-6">
            <div ods-color-gradient="colorgradientright"
                 ods-color-gradient-context="carpool"
                 ods-color-gradient-x="dep_code"
                 ods-color-gradient-serie="COUNT()"
                 ods-color-gradient-nb-classes="3">

                <div class="map-container">
                    <h2>3 classes, linear scale</h2>
                    <ods-map>
                        <ods-map-layer context="dep"
                                       color-categories="colorgradientright['colors']"
                                       color-by-field="dep_code"
                                       color-categories-other="lightgrey"
                                       display="categories"
                                       shape-opacity="0.95"
                                       title="# of carpool parking">
                        </ods-map-layer>
                    </ods-map>


                    <ods-legend title="display=steps"
                                color-gradient="colorgradientright"
                                display="steps"
                                no-value-color="lightgrey"
                                decimal-precision="0"></ods-legend>
                </div>
            </div>
        </div>
    </div>
</ods-dataset-context>

ods-legend: CSS tricks

With some CSS, ods-legend can be horizontal. It can also be positioned on top of the map, to save space.

Fields in use in departements-et-collectivites-doutre-mer-france (See it on userclub domain)

dep_code	geo_shape (geo_shape)
75	{“type”: “Polygon”, “coordinates”: [[…]]}
2B	{“type”: “Polygon”, “coordinates”: [[…]]}
61	{“type”: “Polygon”, “coordinates”: [[…]]}
29	{“type”: “Polygon”, “coordinates”: [[…]]}

Field in use in base-nationale-des-lieux-de-covoiturage-en-france (See it on userclub domain)

dep_code
75
2B
61
29

<!-- "dep" context is the official geo-referential from Opendatasoft Data Network -->
<ods-dataset-context context="dep,carpool"
                     dep-dataset="departements-et-collectivites-doutre-mer-france"
                     dep-domain="userclub"
                     carpool-dataset="base-nationale-des-lieux-de-covoiturage-en-france"
                     carpool-domain="userclub">

    <div ods-color-gradient="colorgradient"
         ods-color-gradient-context="carpool"
         ods-color-gradient-x="dep_code"
         ods-color-gradient-serie="COUNT()"
         ods-color-gradient-nb-classes="5"
         ods-color-gradient-pow-exponent="0.3"
         ods-color-gradient-high="rgb(20, 33, 96)"
         ods-color-gradient-low="rgb(180, 197, 241)">

        <h2>Nb classes : 5, pow scale (exponent = 0.3)</h2>

        <!-- map-container has a relative position, mandatory for absolute positioned legend -->
        <div class="map-container">
            <ods-map>
                <ods-map-layer context="dep"
                               color-categories="colorgradient['colors']"
                               color-by-field="dep_code"
                               color-categories-other="lightgrey"
                               display="categories"
                               shape-opacity="0.95"
                               title="# of carpool parking">
                </ods-map-layer>
            </ods-map>

            <!-- Absolute position, MUST be in the map-container -->
            <ods-legend class="legend-horizontal-absolute-pos"
                        title="width:fit, horizontal, position:absolute"
                        color-gradient="colorgradient"
                        display="steps"
                        no-value-color="lightgrey"
                        decimal-precision="0"></ods-legend>

            <!-- Absolute position, MUST be in the map-container -->
            <ods-legend class="legend-default-absolute-pos"
                        title="width:fit, position:absolute"
                        color-gradient="colorgradient"
                        display="steps"
                        no-value-color="lightgrey"
                        decimal-precision="0"></ods-legend>
        </div>

        <!-- Can be anywhere, no need to be inside the map-container -->
        <ods-legend class="legend-horizontal"
                    title="width:100%, horizontal"
                    color-gradient="colorgradient"
                    display="steps"
                    no-value-color="lightgrey"
                    decimal-precision="0"></ods-legend>
    </div>
</ods-dataset-context>

/* ODS LEGEND HORIZONTAL */
.legend-horizontal {
    width: 100%;
    border: 1px solid #cbd2db;
    border-radius: 6px;
    margin: 13px 0;
}

.legend-horizontal ul.odswidget-legend__indexes.odswidget-legend__steps_style {
    flex-direction: row;
    justify-content: space-between;
    flex-wrap: wrap;
}

.legend-horizontal .odswidget-legend__title {
    text-align: center;
}



/* ODS LEGEND / ABSOLUTE POSITION */
.map-container {
    position: relative;
}

.legend-default-absolute-pos {
    position: absolute;
    top: 20px;
    left: 57px;
    background-color: rgba(255,255,255,0.9);
}



/* ODS LEGEND HORIZONTAL / ABSOLUTE POSITION */
.map-container {
    position: relative;
}

.legend-horizontal-absolute-pos {
    position: absolute;
    /* change bottom to top to set the position relative to the top of the map-container instead of the bottom */
    bottom: 24px; /* value might change depending on the map size and specially if there is elements below the map, in the map-container */
    right: 10px; /* pulled to the right, can be changed to left, to pull the other side */
    background-color: rgba(255,255,255,0.9);
    margin-left: 20px; /* for small devices, keep a margin on the left if pulled right */
}

.legend-horizontal-absolute-pos ul.odswidget-legend__indexes.odswidget-legend__steps_style {
    flex-direction: row;
    justify-content: space-between;
    flex-wrap: wrap;
}

.legend-horizontal-absolute-pos .odswidget-legend__title {
    text-align: center;
}