From 3393454d6830fd6357765018959435b001cf92c1 Mon Sep 17 00:00:00 2001 From: Jesse Yang Date: Fri, 9 Apr 2021 15:15:17 -0700 Subject: [PATCH] docs: update outdated country map tools instructions (#14027) also add actionable error for country map vis --- docs/.nvmrc | 1 + docs/src/pages/docs/Miscellaneous/index.mdx | 98 +++++++-------------- superset/viz.py | 12 ++- 3 files changed, 44 insertions(+), 67 deletions(-) create mode 100644 docs/.nvmrc diff --git a/docs/.nvmrc b/docs/.nvmrc new file mode 100644 index 0000000000000..dae199aecb180 --- /dev/null +++ b/docs/.nvmrc @@ -0,0 +1 @@ +v12 diff --git a/docs/src/pages/docs/Miscellaneous/index.mdx b/docs/src/pages/docs/Miscellaneous/index.mdx index 10a6f00087224..8b67947f65350 100644 --- a/docs/src/pages/docs/Miscellaneous/index.mdx +++ b/docs/src/pages/docs/Miscellaneous/index.mdx @@ -6,89 +6,57 @@ index: 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 -your countries. So, if you want to use tools, you need ISO 3166-2 code of region, province or -department. +The Country Map visualization allows you to plot lightweight choropleth maps of +your countries by province, states, or other subdivision types. It does not rely +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 -Standardization (ISO), and defines codes for identifying the principal subdivisions (e.g., provinces -or states) of all countries coded in ISO 3166-1 +## Included Maps -The purpose of ISO 3166-2 is to establish an international standard of short and unique alphanumeric -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: +The Country Maps visualization already ships with the maps for the following countries: - Belgium +- Brazil +- Bulgaria +- Canada - China - Egypt - France - Germany +- India +- Iran +- Italy - Japan +- Korea - Liechtenstein - Morocco +- Myanmar +- Netherlands +- Portugal - Russia - Singapore - Spain - Switzerland -- United Kingdom +- Syria +- Thailand +- Timorleste +- UK - Ukraine +- Uruguay - USA +- Zambia -### Adding New Countries - -To add a new country in country map tools, you need to follow the following steps: +## Adding a New Country -- You need shapefiles which contain data of your map. You can get this file on this site: - https://www.diva-gis.org/gdata -- You need to add ISO 3166-2 with column name ISO for all record in your file. It’s important - because it’s a norm for mapping your data with geojson file -- You need to convert shapefile to geojson file. This action can make with ogr2ogr tools: - 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: +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). -``` - 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', -}, -``` +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). +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). +3. Ping one of the Superset committers to get the `@superset-ui/legacy-plugin-chart-country-map` package published, or + publish it under another name yourself. +4. Update npm dependencies in `superset-frontend/package.json` to install the updated plugin package. diff --git a/superset/viz.py b/superset/viz.py index 3f20bb3b1ca43..8063a9f8525cc 100644 --- a/superset/viz.py +++ b/superset/viz.py @@ -1951,8 +1951,16 @@ class CountryMapViz(BaseViz): def query_obj(self) -> QueryObjectDict: qry = super().query_obj() - qry["metrics"] = [self.form_data["metric"]] - qry["groupby"] = [self.form_data["entity"]] + metric = self.form_data.get("metric") + 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 def get_data(self, df: pd.DataFrame) -> VizData: