Skip to main content

Maps

Choropleth maps​

A choropleth map is a color-coded map that assigns values as a function of location. Typically, the map is drawn along well-known political/administrative boundaries; hence, you don't have to create the maps yourself. A sliding scale of color helps you to quickly locate hot spots, where the value of interest may be lower or higher than other places on the map.

To create a choropleth map for your data, you need two things:

  1. Map data. Via its Highcharts back end, Altair AI Cloud provides:

    • a world map, partitioned into countries,
    • maps of each continent, partitioned into countries, and
    • country maps, partitioned into lower-level administrative units (US States / German Länder / French Régions).

  2. An identifier (e.g. a country name) that connects your data to the map. In principle, the ISO-3166 standard permits alpha or numeric codes as identifiers; in practice, Altair AI Cloud uses the country name or name of the lower-level administrative unit.

Read more:

Highcharts GeoJSON​

Map data​

The map data provided by Altair AI Cloud began its life on the Natural Earth website, and was converted to GeoJSON format by Highcharts.

GeoJSON is a special JSON format that describes shapes (such as the boundaries of a country) and associates properties to those shapes (such as name and ISO-3166 codes). For example, the GeoJSON Feature that describes the United States of America has the following form:

{ 
    "type": "Feature", 
    "id": "US", 
    "properties": { 
        "hc-group": "admin0", 
        "hc-middle-x": 0.68, 
        "hc-middle-y": 0.68, 
        "hc-key": "us", 
        "hc-a2": "US", 
        "name": "United States of America", 
        "labelrank": "2", 
        "country-abbrev": "U.S.A.", 
        "subregion": "Northern America", 
        "region-wb": "North America", 
        "iso-a3": "USA", 
        "iso-a2": "US", 
        "woe-id": "23424977", 
        "continent": "North America" 
    }, 
    "geometry": { 
        "type": "MultiPolygon", 
        "coordinates": [ 
            [ 
                [ 
                    [ 
                        261, 
                        8307 
                    ],
                    [
                        etc.
                    ],
                    [ 
                        308, 
                        8292 
                    ] 
                ] 
            ] 
        ] 
    } 
},

Identifier​

An important point to observe is that the country name in the Highcharts GeoJSON file is not necessarily the same as the English short name given by ISO-3166. To use the maps provided by Altair AI Cloud / Highcharts, you must use the name given in the Highcharts GeoJSON file.

ISO-3166 nameHighcharts name
United States of America (the)United States of America

For a complete list of ISO-3166 country names and codes, together with their Highcharts equivalents, see the appendix.

Note however that you can infer the Highcharts GeoJSON country name without ever opening a GeoJSON file, simply by:

  • creating the map in Altair AI Cloud and
  • hovering the country with the mouse, until the country name appears.

Read more:

Example: Gapminder​

Gapminder is an independent educational non-profit fighting global misconceptions.

The Gapminder Foundation collects and disseminates information about living standards in all parts of the world, to demonstrate how quickly and remarkably the global standard of living has increased, and to promote sustainable development.

The Gapminder website includes a variety of global data.

GDP per capita in constant PPP dollars​

For our example, we will plot the increase in GDP per capita in constant PPP dollars, from the year 2000 to the year 2020, using a modified version of a Gapminder data set.

The following modifications:

  • Delete GDP per capita growth (%).
  • Restrict the time data to the years 2000 and 2020.
  • Based on the year, rewrite Income per person as Income 2000 and Income 2020. Delete time.
  • Take the ratio Income ratio = Income 2020 / Income 2000.
  • Take the natural log: Log ratio = ln (Income ratio)
  • Rewrite country name as Highcharts name.

produce a table of this form:

geonameGDP totalIncome 2000Income 2020Income ratioLog ratioHighcharts name
afgAfghanistan74652032324578.01918.03.31833910034602081.199464386771006Afghanistan
albAlbania381736255535912.013265.02.24374154262516920.8081448039438024Albania
dzaAlgeria4658900551338710.010624.01.2197474167623420.1986438018696666Algeria
andAndorra475987600035399.061605.01.74030339840108470.5540594649234722Andorra

Download gapminder-20-years.rmhdf5table

Create a map​

Note that an app lives within a project. We have created a project called gapminder. To create a map based on the above data table, take the following steps.

  1. From within the project, under the Data tab, click Add Data, and upload gapminder-20-years.rmhdf5table.
  2. From the Content tab, select Create App and name the app gapminder-progress.
  3. Click Add Widget, and Edit the widget.
  4. In the dropdown, select the widget type Data.
  5. In the Data Set dropdown, select gapminder-20-years.
  6. Visualize the data as a Map.

To configure the map, make the following selections:

  • Map Type: Regions
  • Map: All countries
  • Regions: name, the country name given by Gapminder
  • Value: Income ratio, the ratio between Income 2020 and Income 2000
  • Aggregation: No Aggregation

Increase in GDP/capita (2000-2020)

The resulting map has at least two flaws that can be corrected:

  • The data for some countries, such as the United States and a few African countries, are not displayed on the map.
  • Since most countries have an Income ratio approximately equal to 1.0, the map is drowning in a sea of purple.

Improve the map​

Correct identifiers​

Regarding the missing countries, the issue can be resolved by taking note of the comment on identifiers made previously: the country name must be the same as the name in the Highcharts GeoJSON file.

Gapminder nameHighcharts name
Guinea-BissauGuinea Bissau
Cote d'IvoireIvory Coast
Congo, Rep.Republic of Congo
Congo, Dem. Rep.Democratic Republic of Congo
TanzaniaUnited Republic of Tanzania
United StatesUnited States of America

The data column Highcharts name makes the appropriate corrections.

Improve color coding​

Regarding the color coding, the Highcharts API for colorAxis has some useful comments:

Often times, the color axis needs to be adjusted to get the right color spread for the data. In addition to stops, consider using a logarithmic axis type, or setting min and max to avoid the colors being determined by outliers.

With this comment in mind, and taking into account the Highcharts name, we reconfigure the map, make the following selections:

  • Map Type: Regions
  • Map: All countries
  • Regions: Highcharts name, the country name given by Highcharts
  • Value: Log ratio, the natural logarithm of Income ratio
  • Aggregation: No Aggregation

Increase in GDP/capita (2000-2020)

On this second map, the hot spots stand out more clearly.

  • The countries where the economy has contracted are purple: Venezuela, Libya, South Sudan, Syria, and Yemen. Most of these countries have experienced armed conflict.
  • The countries where the economy has expanded are yellow or orange. China stands out especially, but there has been dramatic progress in most of Asia and also in Eastern Europe.

Advanced settings​

When you edit a map, clicking the button Advanced Settings gives you access to the Highcharts API. For maps, possible settings of interest include:

To change the configuration of the title, for example, enter a JSON snippet similar to the following into the form field:

{
    "title": {
        "text": "Log[ (Income 2020) / (Income 2000) ]",
        "align": "left",
        "x": 90,
        "y": 60,
        "style": {
            "color": "#772222"
        }
    }
}

Read more:

Appendix: conversion table​

The table below presents the ISO-3166-1 standard for country codes, and shows eventual differences between the English short name identified in ISO-3166-1 and the country names identified by Highcharts. To get your data on the map, you need to use the Highcharts name.

Download the conversion table

English short nameAlpha-2 codeAlpha-3 codeNumericHighcharts name
AfghanistanAFAFG4Afghanistan
AlbaniaALALB8Albania
AlgeriaDZDZA12Algeria
American SamoaASASM16American Samoa
AndorraADAND20Andorra
AngolaAOAGO24Angola
AnguillaAIAIA660
AntarcticaAQATA10
Antigua and BarbudaAGATG28Antigua and Barbuda
ArgentinaARARG32Argentina
ArmeniaAMARM51Armenia
ArubaAWABW533
AustraliaAUAUS36Australia
AustriaATAUT40Austria
AzerbaijanAZAZE31Azerbaijan
Bahamas (the)BSBHS44The Bahamas
BahrainBHBHR48Bahrain
BangladeshBDBGD50Bangladesh
BarbadosBBBRB52Barbados
BelarusBYBLR112Belarus
BelgiumBEBEL56Belgium
BelizeBZBLZ84Belize
BeninBJBEN204Benin
BermudaBMBMU60
BhutanBTBTN64Bhutan
Bolivia (Plurinational State of)BOBOL68Bolivia
Bonaire, Sint Eustatius and SabaBQBES535
Bosnia and HerzegovinaBABIH70Bosnia and Herzegovina
BotswanaBWBWA72Botswana
Bouvet IslandBVBVT74
BrazilBRBRA76Brazil
British Indian Ocean Territory (the)IOIOT86
Brunei DarussalamBNBRN96Brunei
BulgariaBGBGR100Bulgaria
Burkina FasoBFBFA854Burkina Faso
BurundiBIBDI108Burundi
Cabo VerdeCVCPV132Cape Verde
CambodiaKHKHM116Cambodia
CameroonCMCMR120Cameroon
CanadaCACAN124Canada
Cayman Islands (the)KYCYM136
Central African Republic (the)CFCAF140Central African Republic
ChadTDTCD148Chad
ChileCLCHL152Chile
ChinaCNCHN156China
Christmas IslandCXCXR162
Cocos (Keeling) Islands (the)CCCCK166
ColombiaCOCOL170Colombia
Comoros (the)KMCOM174Comoros
Congo (the Democratic Republic of the)CDCOD180Democratic Republic of the Congo
Congo (the)CGCOG178Republic of Congo
Cook Islands (the)CKCOK184
Costa RicaCRCRI188Costa Rica
CroatiaHRHRV191Croatia
CubaCUCUB192Cuba
CuraçaoCWCUW531
CyprusCYCYP196Cyprus
CzechiaCZCZE203Czech Republic
Côte d'IvoireCICIV384Ivory Coast
DenmarkDKDNK208Denmark
DjiboutiDJDJI262Djibouti
DominicaDMDMA212Dominica
Dominican Republic (the)DODOM214Dominican Republic
EcuadorECECU218Ecuador
EgyptEGEGY818Egypt
El SalvadorSVSLV222El Salvador
Equatorial GuineaGQGNQ226Equatorial Guinea
EritreaERERI232Eritrea
EstoniaEEEST233Estonia
EswatiniSZSWZ748Swaziland
EthiopiaETETH231Ethiopia
Falkland Islands (the) [Malvinas]FKFLK238
Faroe Islands (the)FOFRO234Faroe Islands
FijiFJFJI242Fiji
FinlandFIFIN246Finland
FranceFRFRA250France
French GuianaGFGUF254
French PolynesiaPFPYF258
French Southern Territories (the)TFATF260
GabonGAGAB266Gabon
Gambia (the)GMGMB270Gambia
GeorgiaGEGEO268Georgia
GermanyDEDEU276Germany
GhanaGHGHA288Ghana
GibraltarGIGIB292
GreeceGRGRC300Greece
GreenlandGLGRL304Greenland
GrenadaGDGRD308Grenada
GuadeloupeGPGLP312
GuamGUGUM316Guam
GuatemalaGTGTM320Guatemala
GuernseyGGGGY831
GuineaGNGIN324Guinea
Guinea-BissauGWGNB624Guinea Bissau
GuyanaGYGUY328Guyana
HaitiHTHTI332Haiti
Heard Island and McDonald IslandsHMHMD334
Holy See (the)VAVAT336Vatican
HondurasHNHND340Honduras
Hong KongHKHKG344
HungaryHUHUN348Hungary
IcelandISISL352Iceland
IndiaININD356India
IndonesiaIDIDN360Indonesia
Iran (Islamic Republic of)IRIRN364Iran
IraqIQIRQ368Iraq
IrelandIEIRL372Ireland
Isle of ManIMIMN833
IsraelILISR376Israel
ItalyITITA380Italy
JamaicaJMJAM388Jamaica
JapanJPJPN392Japan
JerseyJEJEY832
JordanJOJOR400Jordan
KazakhstanKZKAZ398Kazakhstan
KenyaKEKEN404Kenya
KiribatiKIKIR296Kiribati
Korea (the Democratic People's Republic of)KPPRK408North Korea
Korea (the Republic of)KRKOR410South Korea
KuwaitKWKWT414Kuwait
KyrgyzstanKGKGZ417Kyrgyzstan
Lao People's Democratic Republic (the)LALAO418Laos
LatviaLVLVA428Latvia
LebanonLBLBN422Lebanon
LesothoLSLSO426Lesotho
LiberiaLRLBR430Liberia
LibyaLYLBY434Libya
LiechtensteinLILIE438Liechtenstein
LithuaniaLTLTU440Lithuania
LuxembourgLULUX442Luxembourg
MacaoMOMAC446
MadagascarMGMDG450Madagascar
MalawiMWMWI454Malawi
MalaysiaMYMYS458Malaysia
MaldivesMVMDV462Maldives
MaliMLMLI466Mali
MaltaMTMLT470Malta
Marshall Islands (the)MHMHL584Marshall Islands
MartiniqueMQMTQ474
MauritaniaMRMRT478Mauritania
MauritiusMUMUS480Mauritius
MayotteYTMYT175
MexicoMXMEX484Mexico
Micronesia (Federated States of)FMFSM583Federated States of Micronesia
Moldova (the Republic of)MDMDA498Moldova
MonacoMCMCO492Monaco
MongoliaMNMNG496Mongolia
MontenegroMEMNE499Montenegro
MontserratMSMSR500
MoroccoMAMAR504Morocco
MozambiqueMZMOZ508Mozambique
MyanmarMMMMR104Myanmar
NamibiaNAM516Namibia
NauruNRNRU520Nauru
NepalNPNPL524Nepal
Netherlands (the)NLNLD528Netherlands
New CaledoniaNCNCL540
New ZealandNZNZL554New Zealand
NicaraguaNINIC558Nicaragua
Niger (the)NENER562Niger
NigeriaNGNGA566Nigeria
NiueNUNIU570
Norfolk IslandNFNFK574
North MacedoniaMKMKD807Macedonia
Northern Mariana Islands (the)MPMNP580Northern Mariana Islands
NorwayNONOR578Norway
OmanOMOMN512Oman
PakistanPKPAK586Pakistan
PalauPWPLW585Palau
Palestine, State ofPSPSE275
PanamaPAPAN591Panama
Papua New GuineaPGPNG598Papua New Guinea
ParaguayPYPRY600Paraguay
PeruPEPER604Peru
Philippines (the)PHPHL608Philippines
PitcairnPNPCN612
PolandPLPOL616Poland
PortugalPTPRT620Portugal
Puerto RicoPRPRI630Puerto Rico
QatarQAQAT634Qatar
RomaniaROROU642Romania
Russian Federation (the)RURUS643Russia
RwandaRWRWA646Rwanda
RéunionREREU638
Saint BarthélemyBLBLM652
Saint Helena, Ascension and Tristan da CunhaSHSHN654
Saint Kitts and NevisKNKNA659Saint Kitts and Nevis
Saint LuciaLCLCA662Saint Lucia
Saint Martin (French part)MFMAF663
Saint Pierre and MiquelonPMSPM666
Saint Vincent and the GrenadinesVCVCT670Saint Vincent and the Grenadines
SamoaWSWSM882Samoa
San MarinoSMSMR674San Marino
Sao Tome and PrincipeSTSTP678Sao Tome and Principe
Saudi ArabiaSASAU682Saudi Arabia
SenegalSNSEN686Senegal
SerbiaRSSRB688Republic of Serbia
SeychellesSCSYC690Seychelles
Sierra LeoneSLSLE694Sierra Leone
SingaporeSGSGP702Singapore
Sint Maarten (Dutch part)SXSXM534
SlovakiaSKSVK703Slovakia
SloveniaSISVN705Slovenia
Solomon IslandsSBSLB90Solomon Islands
SomaliaSOSOM706Somalia
South AfricaZAZAF710South Africa
South Georgia and the South Sandwich IslandsGSSGS239
South SudanSSSSD728South Sudan
SpainESESP724Spain
Sri LankaLKLKA144Sri Lanka
Sudan (the)SDSDN729Sudan
SurinameSRSUR740Suriname
Svalbard and Jan MayenSJSJM744
SwedenSESWE752Sweden
SwitzerlandCHCHE756Switzerland
Syrian Arab Republic (the)SYSYR760Syria
Taiwan (Province of China)TWTWN158Taiwan
TajikistanTJTJK762Tajikistan
Tanzania, the United Republic ofTZTZA834United Republic of Tanzania
ThailandTHTHA764Thailand
Timor-LesteTLTLS626East Timor
TogoTGTGO768Togo
TokelauTKTKL772
TongaTOTON776Tonga
Trinidad and TobagoTTTTO780Trinidad and Tobago
TunisiaTNTUN788Tunisia
TurkeyTRTUR792Turkey
TurkmenistanTMTKM795Turkmenistan
Turks and Caicos Islands (the)TCTCA796
TuvaluTVTUV798Tuvalu
UgandaUGUGA800Uganda
UkraineUAUKR804Ukraine
United Arab Emirates (the)AEARE784United Arab Emirates
United Kingdom of Great Britain and Northern Ireland (the)GBGBR826United Kingdom
United States Minor Outlying Islands (the)UMUMI581United States Minor Outlying Islands
United States of America (the)USUSA840United States of America
UruguayUYURY858Uruguay
UzbekistanUZUZB860Uzbekistan
VanuatuVUVUT548Vanuatu
Venezuela (Bolivarian Republic of)VEVEN862Venezuela
Viet NamVNVNM704Vietnam
Virgin Islands (British)VGVGB92
Virgin Islands (U.S.)VIVIR850United States Virgin Islands
Wallis and FutunaWFWLF876
Western Sahara*EHESH732Western Sahara
YemenYEYEM887Yemen
ZambiaZMZMB894Zambia
ZimbabweZWZWE716Zimbabwe
Åland IslandsAXALA248