30:[{"id":"a549121234e63991794fc7f322d4ca4914cf2568889d08476a5ace7b4433331dca0ad6e05d2b72c10dfe1031693acfbadea2cccac96a0b08d9817bbbd1d7a28f","href":"https://static.observableusercontent.com/files/a549121234e63991794fc7f322d4ca4914cf2568889d08476a5ace7b4433331dca0ad6e05d2b72c10dfe1031693acfbadea2cccac96a0b08d9817bbbd1d7a28f","name":"Figure-2.08.png","type":"image/png","lastModified":1703087609798.081,"size":51016}] 2e:{"title":"Choropleth","cells":[{"id":0,"value":"# Choropleth","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"disclaimer","pinned":false,"hidden":false,"mode":"ojs"},{"id":694,"value":"In thematic cartography, according to the rules of graphic semiology, relative quantitative data (percentages, indices, ratios) must be represented using visual order variables. The most classic representation is the choropleth map.","pinned":false,"hidden":false,"mode":"md"},{"id":848,"value":"## The function","pinned":false,"hidden":false,"mode":"md"},{"id":854,"value":"The simplest way to create a chropleth map with the geoviz library is : ","pinned":false,"hidden":false,"mode":"md"},{"id":851,"value":"~~~js\nviz.plot({type: \"choro\", data: *a geoJSON*, var: *a field*})\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":941,"value":"Or","pinned":false,"hidden":false,"mode":"md"},{"id":937,"value":"~~~js\nviz.choro({data: *a geoJSON*, var: *a field*})\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":818,"value":"## Main parameters to use","pinned":false,"hidden":false,"mode":"md"},{"id":820,"value":"- `data` a geoJSON (compulsory)\n- `var` a variable name in a geoJSON (compulsory)\n- `nb` Number of breaks\n- `method` classification method ('quantile', 'q6', 'equal', 'jenks', 'msd', 'geometric', 'headtail', 'pretty', 'arithmetic' or 'nestedmeans'). By default, thee quantile method is used.\n- `colors` an array of colors or name of a color palette available in [dicopal](https://observablehq.com/@neocartocnrs/dicopal-library)","pinned":false,"hidden":false,"mode":"md"},{"id":783,"value":"## A simple example","pinned":false,"hidden":false,"mode":"md"},{"id":18,"value":"In `geoviz`, we can draw a choropleth map pith trhe plot function. The choro type lets you quickly create a choropleth map with a legend. Nothing could be easier. You need 2 parameters: data and var.","pinned":false,"hidden":false,"mode":"md"},{"id":789,"value":"viz.plot({\n type: \"choro\",\n data: world,\n var: \"gdppc\",\n legend: true\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":872,"value":"## More complex examples","pinned":false,"hidden":false,"mode":"md"},{"id":791,"value":"You can change the discretization parameters and colors. nb, method, colors... These are the same as in the `tool.choro()` function (see below). For the legends, you use the legend parameters `legend.choro_horizontal()` and `legend.choro_vertical()` with the prexix `leg_`. In addition, leg_type allows you to specify whether you want a \"horizontal\" or \"vertical\" display.","pinned":false,"hidden":false,"mode":"md"},{"id":794,"value":"viz.plot({\n type: \"choro\",\n colors: \"Reds\",\n method: \"geometric\",\n nb: 4,\n data: world,\n var: \"gdppc\",\n leg_type: \"horizontal\",\n leg_values_factor: 0.001,\n leg_values_round: 1,\n leg_pos: [400, 350],\n leg_missing: false,\n leg_missing_text: \"data not available\",\n leg_title: \"GDP per capita\",\n leg_subtitle: \"(in thousands)\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":796,"value":"It works also in a container.","pinned":false,"hidden":false,"mode":"md"},{"id":798,"value":"{\n let svg = viz.create({ projection: d3.geoNaturalEarth1(), width: 700 });\n svg.plot({ type: \"outline\" });\n svg.plot({\n type: \"graticule\",\n stroke: \"white\",\n step: 20,\n strokeDasharray: \"none\"\n });\n svg.plot({\n type: \"choro\",\n data: world,\n missing: \"#CCC\",\n leg_missing_text: \"no data\",\n colors: \"Temps\",\n var: \"gdppc\",\n breaks: [200, 1000, 5000, 10000, 50000, 200000],\n leg_values_round: 0,\n reverse: true,\n strokeWidth: 0.3,\n leg_title: \"GDP per capita\",\n tip: true\n });\n return svg.render();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":860,"value":"## Draw a choropleth map with lower level functions","pinned":false,"hidden":false,"mode":"md"},{"id":777,"value":"You can also use lower-level functions such as path(), tool.choro()and legend.choro_horizontal(). Let's see an example bellow.","pinned":false,"hidden":false,"mode":"md"},{"id":659,"value":"{\n // We create a container\n const svg = viz.create({ domain: world });\n\n // We choose breaks and colors\n const data = world.features.map((d) => d.properties.gdppc);\n const choro = viz.tool.choro(data, {\n method: \"quantile\",\n nb: 6,\n precision: 0,\n colors: \"PinkYl\"\n });\n\n // We display countries with colors\n svg.path({\n data: world,\n fill: (d) => choro.colorize(d.properties.gdppc),\n tip: \"$NAMEen\\n$gdppc\"\n });\n\n // We adda a legend\n svg.legend.choro_horizontal({\n pos: [400, 380],\n ...choro,\n title: \"GDP per Capita\"\n });\n\n // We render the SVG\n return svg.render();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":691,"value":"And below, some explanations.","pinned":false,"hidden":false,"mode":"md"},{"id":20,"value":"## Classification methods","pinned":false,"hidden":false,"mode":"md"},{"id":877,"value":"let's imagine the French départements. If we were to assign a color to each department, we wouldn't be able to differentiate one value from another. The eye can't distinguish 100 different variations of green. So we have to group them together. The challenge is to make these groupings meaningful. \n\n**Discretization** consists in dividing a series into value classes. This operation must respect various characteristics of the distribution. To classify a quantitative dataset, `geoviz` uses the [`statsbreaks`](https://github.com/riatelab/statsbreaks) library. Several methods are available in the tool.choro() function.","pinned":false,"hidden":false,"mode":"md"},{"id":141,"value":"Here are some data","pinned":false,"hidden":false,"mode":"md"},{"id":52,"value":"data = world.features.map((d) => d.properties.gdppc)","pinned":false,"hidden":false,"mode":"ojs"},{"id":264,"value":"And some methods.","pinned":false,"hidden":false,"mode":"md"},{"id":108,"value":"- The quantile method (or equal numbers) constructs classes in which there are the same number of statistical units. When there are 4 classes, the term used is quartiles (one quarter of the total number in each classes), when there are 10 classes, they are known as deciles, and for 100 classes, they will be centiles. You can set the number of classes with the nb attribute. The precision parameter is used to define the number of decimals.","pinned":false,"hidden":false,"mode":"md"},{"id":193,"value":"viewof nb1 = Inputs.range([2, 15], { label: \"nb\", step: 1 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":45,"value":"viz.tool.choro(data, { method: \"quantile\", nb: nb1, precision: 2 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":118,"value":"- The q6 method is a variation of the quantile method with **6 classes** and isolation of extremes classes (5%). The precision parameter is used to define the number of decimals.","pinned":false,"hidden":false,"mode":"md"},{"id":122,"value":"viz.tool.choro(data, { method: \"q6\", precision: 2 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":124,"value":"- The Jenks method is an automatic classification method based on the principle of resemblance or non-resemblance among values. The method works via iterations. It groups values that most resemble one another and those that least resemble one another. In statistical terms, the method aims to minimize intra-class variance and to maximize inter-class variance. You can set the number of classes with the nb attribute.","pinned":false,"hidden":false,"mode":"md"},{"id":126,"value":"viz.tool.choro(data, { method: \"jenks\", nb: 6 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":146,"value":"- The geometric progression is suited to highly skewed distributions. It consists in constructing classes whose extent increases with each class, which enables close follow-up of the statistical series. You can set the number of classes with the nb attribute. The precision parameter is used to define the number of decimals.","pinned":false,"hidden":false,"mode":"md"},{"id":198,"value":"viewof nb2 = Inputs.range([2, 15], { label: \"nb\", step: 1 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":152,"value":"viz.tool.choro(data, { method: \"geometric\", nb: nb2, precision: 2 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":163,"value":"- The arithmetic progression is suited to right-skewed distributions (i.e. with many low values and few high ones). It consists in constructing classes whose amplitude increases in an arithmetical progression. You can set the number of classes with the nb attribute. The precision parameter is used to define the number of decimals.","pinned":false,"hidden":false,"mode":"md"},{"id":202,"value":"viewof nb3 = Inputs.range([2, 15], { label: \"nb\", step: 1 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":165,"value":"viz.tool.choro(data, { method: \"arithmetic\", nb: nb3, precision: 2 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":175,"value":"- The msd method (mean standard deviation) is based on significant values (mean and standard deviation). This type of classification is ideal for symmetrical (normal, Gaussian) distributions and should be solely in the instance. In this method, you do not define the number of classes, but sd, the number of standard deviations taken into account, and middle, a boolean to have the average as a class center. You can set the number of classes with the nb attribute. ","pinned":false,"hidden":false,"mode":"md"},{"id":208,"value":"viewof k = Inputs.range([0.5, 3], { label: \"nb\", step: 0.5 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":211,"value":"viewof middle = Inputs.toggle({ label: \"middle\", value: true })","pinned":false,"hidden":false,"mode":"ojs"},{"id":178,"value":"viz.tool.choro(data, { method: \"msd\", sd: k, middle: middle, precision: 2 })\n .breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":188,"value":"- The headtail method is a data classification method in which the number of classes and the class intervals are both naturally determined by the very property of the heavy-tailed distributions of the data. You can set the number of classes with the nb attribute (it works with up to 7 classes). The precision parameter is used to define the number of decimals. ","pinned":false,"hidden":false,"mode":"md"},{"id":216,"value":"viewof nb4 = Inputs.range([2, 7], { label: \"nb\", step: 1 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":190,"value":"viz.tool.choro(data, { method: \"headtail\", nb: nb4, precision: 2 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":221,"value":"- The pretty method generates breaks that are equally spaced round values which cover the range of values in the input array. You can set the number of classes with the nb attribute. The breaks are chosen so that they are 1, 2, or 5 times a power of 10. ","pinned":false,"hidden":false,"mode":"md"},{"id":223,"value":"viewof nb5 = Inputs.range([2, 15], { label: \"nb\", step: 1, precision: 1 })","pinned":true,"hidden":false,"mode":"ojs"},{"id":225,"value":"viz.tool.choro(data, { method: \"pretty\", nb: nb5 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":228,"value":"- The nestedmeans method computes breaks using nested means : a first (arithmetic) mean divides the series in two, then each group is again split by its mean, and so on, until the desired number of classes is obtained. You can set the number of classes with the nb attribute. As such, the number of classes requested must be a power of 2 (2, 4, 8, etc.).","pinned":false,"hidden":false,"mode":"md"},{"id":253,"value":"viewof nb6 = Inputs.radio([2, 4, 8, 16, 32], { label: \"nb\", value: 8 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":232,"value":"viz.tool.choro(data, { method: \"nestedmeans\", nb: nb6 }).breaks","pinned":true,"hidden":false,"mode":"ojs"},{"id":135,"value":"## 2 - How to choose a method?","pinned":false,"hidden":false,"mode":"md"},{"id":706,"value":"To choose the appropriate classification method, you need to study the distribution of the statistical series. Look to see if the values are organized around the mean, more in the lower values or more in the upper values. ","pinned":false,"hidden":false,"mode":"md"},{"id":701,"value":"figure208 = FileAttachment(\"Figure-2.08.png\").image({ width: 800 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":708,"value":"The best way to appreciate this is to represent them graphically. To do this, I recommend using the wonderful [`Plot`](https://observablehq.com/plot/) library. ","pinned":false,"hidden":false,"mode":"md"},{"id":27,"value":"## Colors","pinned":false,"hidden":false,"mode":"md"},{"id":332,"value":"In `geoviz`, thanks to the [`dicopal`](https://github.com/riatelab/dicopal.js) library, numerous color palettes are available. Dicopal offers color palettes from several providers : Colorbrewer2, Fabio Crameri's Scientific Colour Maps, CARTOColors, cmocean, Light & Bartlein, Matplotlib, MyCarta, Tableau, The Wes Anderson Palettes blog, Masataka Okabe and Kei Ito's Color Universal Design (CUD) palettea and Joshua Stevens' palettes.","pinned":false,"hidden":false,"mode":"md"},{"id":339,"value":"In the function viz.tool.choro(), you juste have to use the colors argument.","pinned":false,"hidden":false,"mode":"md"},{"id":571,"value":"viewof pal = Inputs.select(\n Array.from(\n new Set(dicopal.getPalettes({ type: \"sequential\" }).map((d) => d.name))\n ).concat(\n Array.from(\n new Set(dicopal.getPalettes({ type: \"diverging\" }).map((d) => d.name))\n )\n ),\n { label: \"Colors\" }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":371,"value":"viewof nbcols = Inputs.range([2, 30], { label: \"nb\", step: 1, value: 12 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":609,"value":"viewof reverse = Inputs.toggle({ label: \"reverse\", value: false })","pinned":true,"hidden":false,"mode":"ojs"},{"id":583,"value":"cols = viz.tool.choro(data, { nb: nbcols, colors: pal, reverse }).colors","pinned":true,"hidden":false,"mode":"ojs"},{"id":593,"value":"$${drawpal(cols)}","pinned":false,"hidden":false,"mode":"md"},{"id":22,"value":"## Legends","pinned":false,"hidden":false,"mode":"md"},{"id":616,"value":"Two types of legend are currently available in the library. The legend.choro_horizontal function lets you draw an choro_horizontal legend. The legend.choro_vertical function lets you draw a vertical legend. Theses legends take the following 2 elements as input: breaks and colors. This is the output of the tool.choro() function","pinned":false,"hidden":false,"mode":"md"},{"id":630,"value":"choro = viz.tool.choro(data, { method: \"quantile\", nb: 6, colors: \"Reds\" })","pinned":true,"hidden":false,"mode":"ojs"},{"id":618,"value":"viz.legend.choro_vertical({\n breaks: choro.breaks,\n colors: choro.colors,\n title: \"GDP per capita\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":641,"value":"viz.legend.choro_horizontal({\n breaks: choro.breaks,\n colors: choro.colors,\n title: \"GDP per capita\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":643,"value":"You can also do it directly","pinned":false,"hidden":false,"mode":"md"},{"id":645,"value":"viz.legend.choro_horizontal({ ...choro, title: \"GDP per capita\" })","pinned":true,"hidden":false,"mode":"ojs"},{"id":653,"value":"To understand how legends work, see [this notebook](https://observablehq.com/@neocartocnrs/legends).","pinned":false,"hidden":false,"mode":"md"},{"id":14,"value":"## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":9,"value":"import { style, world, disclaimer, viz } from \"@neocartocnrs/geoviz-appendix\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":12,"value":"style","pinned":false,"hidden":false,"mode":"ojs"},{"id":357,"value":"dicopal = require(\"dicopal@0.5\")","pinned":true,"hidden":true,"mode":"ojs"},{"id":586,"value":"drawpal = function (col) {\n let boxsize = 500 / col.length;\n let str = \"\";\n col.forEach((d) => {\n str += ``;\n });\n\n return str;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":916,"value":"","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}