mirror of https://github.com/apache/superset.git
docs: update outdated country map tools instructions (#14027)
also add actionable error for country map vis
This commit is contained in:
parent
66201e7c55
commit
fe08b698f5
|
@ -0,0 +1 @@
|
||||||
|
v12
|
|
@ -6,89 +6,57 @@ index: 1
|
||||||
version: 1
|
version: 1
|
||||||
---
|
---
|
||||||
|
|
||||||
## Country Map Tools
|
## The Country Map Visualization
|
||||||
|
|
||||||
This tool is used in slices for visualization number or string by region, province or department of
|
The Country Map visualization allows you to plot lightweight choropleth maps of
|
||||||
your countries. So, if you want to use tools, you need ISO 3166-2 code of region, province or
|
your countries by province, states, or other subdivision types. It does not rely
|
||||||
department.
|
on any third-party map services but would require you to provide the
|
||||||
|
[ISO-3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes of your country's
|
||||||
|
top-level subdivisions. Comparing to a province or state's full names, the ISO
|
||||||
|
code is less ambiguous and is unique to all regions in the world.
|
||||||
|
|
||||||
ISO 3166-2 is part of the ISO 3166 standard published by the International Organization for
|
## Included Maps
|
||||||
Standardization (ISO), and defines codes for identifying the principal subdivisions (e.g., provinces
|
|
||||||
or states) of all countries coded in ISO 3166-1
|
|
||||||
|
|
||||||
The purpose of ISO 3166-2 is to establish an international standard of short and unique alphanumeric
|
The Country Maps visualization already ships with the maps for the following countries:
|
||||||
codes to represent the relevant administrative divisions and dependent territories of all countries
|
|
||||||
in a more convenient and less ambiguous form than their full names. Each complete ISO 3166-2 code
|
|
||||||
consists of two parts, separated by a hyphen:
|
|
||||||
|
|
||||||
The first part is the ISO 3166-1 alpha-2 code of the country; The second part is a string of up to
|
|
||||||
three alphanumeric characters, which is usually obtained from national sources and stems from coding
|
|
||||||
systems already in use in the country concerned, but may also be developed by the ISO itself.
|
|
||||||
|
|
||||||
We can apply these concepts to specify the state of Texas in the country of United States:
|
|
||||||
|
|
||||||
```
|
|
||||||
US-TX
|
|
||||||
```
|
|
||||||
|
|
||||||
### Included Codes
|
|
||||||
|
|
||||||
The ISO codes for the following countries are included in Superset:
|
|
||||||
|
|
||||||
- Belgium
|
- Belgium
|
||||||
|
- Brazil
|
||||||
|
- Bulgaria
|
||||||
|
- Canada
|
||||||
- China
|
- China
|
||||||
- Egypt
|
- Egypt
|
||||||
- France
|
- France
|
||||||
- Germany
|
- Germany
|
||||||
|
- India
|
||||||
|
- Iran
|
||||||
|
- Italy
|
||||||
- Japan
|
- Japan
|
||||||
|
- Korea
|
||||||
- Liechtenstein
|
- Liechtenstein
|
||||||
- Morocco
|
- Morocco
|
||||||
|
- Myanmar
|
||||||
|
- Netherlands
|
||||||
|
- Portugal
|
||||||
- Russia
|
- Russia
|
||||||
- Singapore
|
- Singapore
|
||||||
- Spain
|
- Spain
|
||||||
- Switzerland
|
- Switzerland
|
||||||
- United Kingdom
|
- Syria
|
||||||
|
- Thailand
|
||||||
|
- Timorleste
|
||||||
|
- UK
|
||||||
- Ukraine
|
- Ukraine
|
||||||
|
- Uruguay
|
||||||
- USA
|
- USA
|
||||||
|
- Zambia
|
||||||
|
|
||||||
### Adding New Countries
|
## Adding a New Country
|
||||||
|
|
||||||
To add a new country in country map tools, you need to follow the following steps:
|
To add a new country to the list, you'd have to edit files in
|
||||||
|
[@superset-ui/legacy-plugin-chart-country-map](https://github.com/apache-superset/superset-ui/tree/master/plugins/legacy-plugin-chart-country-map).
|
||||||
|
|
||||||
- You need shapefiles which contain data of your map. You can get this file on this site:
|
1. Generate a new GeoJSON file for your country following the guide in [this Jupyter notebook](https://github.com/apache-superset/superset-ui/blob/master/plugins/legacy-plugin-chart-country-map/scripts/Country%20Map%20GeoJSON%20Generator.ipynb).
|
||||||
https://www.diva-gis.org/gdata
|
2. Edit the countries list in [legacy-plugin-chart-country-map/src/countries.js](https://github.com/apache-superset/superset-ui/blob/master/plugins/legacy-plugin-chart-country-map/src/countries.js).
|
||||||
- You need to add ISO 3166-2 with column name ISO for all record in your file. It’s important
|
3. Ping one of the Superset committers to get the `@superset-ui/legacy-plugin-chart-country-map` package published, or
|
||||||
because it’s a norm for mapping your data with geojson file
|
publish it under another name yourself.
|
||||||
- You need to convert shapefile to geojson file. This action can make with ogr2ogr tools:
|
4. Update npm dependencies in `superset-frontend/package.json` to install the updated plugin package.
|
||||||
https://www.gdal.org/ogr2ogr.html
|
|
||||||
- Put your geojson file in next folder : superset-frontend/src/visualizations/CountryMap/countries
|
|
||||||
with the next name : nameofyourcountries.geojson
|
|
||||||
- You can to reduce size of geojson file on this site: https://mapshaper.org/
|
|
||||||
- Go in file `superset-frontend/src/explore/controls.jsx`
|
|
||||||
- Add your country in component ‘select_country’. Here's an example:
|
|
||||||
|
|
||||||
```
|
|
||||||
type: 'SelectControl',
|
|
||||||
label: 'Country Name Type',
|
|
||||||
default: 'France',
|
|
||||||
choices: [
|
|
||||||
'Belgium',
|
|
||||||
'Brazil',
|
|
||||||
'China',
|
|
||||||
'Egypt',
|
|
||||||
'France',
|
|
||||||
'Germany',
|
|
||||||
'Italy',
|
|
||||||
'Japan',
|
|
||||||
'Korea',
|
|
||||||
'Morocco',
|
|
||||||
'Netherlands',
|
|
||||||
'Russia',
|
|
||||||
'Singapore',
|
|
||||||
'Spain',
|
|
||||||
'Uk',
|
|
||||||
'Usa',
|
|
||||||
].map(s => [s, s]),
|
|
||||||
description: 'The name of country that Superset should display',
|
|
||||||
},
|
|
||||||
```
|
|
||||||
|
|
|
@ -1951,8 +1951,16 @@ class CountryMapViz(BaseViz):
|
||||||
|
|
||||||
def query_obj(self) -> QueryObjectDict:
|
def query_obj(self) -> QueryObjectDict:
|
||||||
qry = super().query_obj()
|
qry = super().query_obj()
|
||||||
qry["metrics"] = [self.form_data["metric"]]
|
metric = self.form_data.get("metric")
|
||||||
qry["groupby"] = [self.form_data["entity"]]
|
entity = self.form_data.get("entity")
|
||||||
|
if not self.form_data.get("select_country"):
|
||||||
|
raise QueryObjectValidationError("Must specify a country")
|
||||||
|
if not metric:
|
||||||
|
raise QueryObjectValidationError("Must specify a metric")
|
||||||
|
if not entity:
|
||||||
|
raise QueryObjectValidationError("Must provide ISO codes")
|
||||||
|
qry["metrics"] = [metric]
|
||||||
|
qry["groupby"] = [entity]
|
||||||
return qry
|
return qry
|
||||||
|
|
||||||
def get_data(self, df: pd.DataFrame) -> VizData:
|
def get_data(self, df: pd.DataFrame) -> VizData:
|
||||||
|
|
Loading…
Reference in New Issue