-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdocumentation.html
262 lines (239 loc) · 20.9 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<!DOCTYPE html>
<html lang="en-GB">
<head>
<title>Trafford Data Lab: Choroplether documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover"/>
<meta charset="UTF-8"/>
<meta name="keywords" content="trafford, vega-lite, choropleth, choropleths, map, documentation"/>
<meta name="description" content="Choroplether documentation. Trafford Data Lab web application allowing the quick creation of choropleth map visualisations based on Vega-Lite."/>
<link rel="stylesheet" href="css/base.css"/>
<link rel="stylesheet" href="css/main.css"/>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans|Roboto"/>
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.0.10/css/all.css" integrity="sha384-+d0P83n9kaQMCwj8F4RJB66tzIwOKmrdb46+porD/OvrJ+37WqIM7UoBtwHO6Nlg" crossorigin="anonymous">
<style>
/* visualisations and/or text content layouts */
.doubleColumnTxtImg div
{
width: 50%;
float: left;
}
.doubleColumnTxtImg div:nth-child(1) p
{
margin-right: 30px; /* to provide space between any text content and the right column when displayed in 2-column format */
}
.doubleColumnTxtImg::after
{
content: "";
display: block;
clear: both;
}
.doubleColumnTxtImg img
{
width: 100%;
}
@media (max-width:800px)
{
/* visualisations and/or text content layouts */
.doubleColumnTxtImg div:nth-child(2)
{
width: 500px;
margin: auto;
}
.doubleColumnTxtImg div:nth-child(1)
{
width: 100%;
}
.doubleColumnTxtImg div
{
float: none;
}
.doubleColumnTxtImg div:nth-child(1) p
{
margin-right: 0px; /* remove space between any text content and the right column when displayed in 2-column format */
}
}
@media (max-width:620px)
{
/* visualisations and/or text content layouts */
.doubleColumnTxtImg, .doubleColumnTxtImg div, .doubleColumnTxtImg div:nth-child(2)
{
width: 100%;
}
.doubleColumnTxtImg div:nth-child(1) p
{
margin-right: 0px; /* remove space between any text content and the right column when displayed in 2-column format */
}
}
.bold
{
font-weight: bold;
}
abbr, .italic
{
font-style: italic;
}
.screenshot
{
box-shadow: 3px 3px 5px #757575;
}
.code
{
display: block;
background-color: #ccc;
padding: 10px;
overflow: hidden;
}
</style>
</head>
<body>
<div class="container">
<header>
<nav>
<a href="https://www.trafforddatalab.io/index.html" aria-label="Go to the Trafford Data Lab home page"><img src="https://www.trafforddatalab.io/assets/logo/trafforddatalab_logo.svg" alt="Trafford Data Lab" width="93" border="0" class="traffordDataLabLogo"/></a>
</nav>
<span id="headerTitle">Choroplether</span>
</header>
<main id="main">
<div class="doubleColumnTxtImg">
<div>
<h1>Choroplether documentation</h1>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#demo">Demonstration</a></li>
<li><a href="#data">Data</a></li>
<li><a href="#geography">Geography</a></li>
<li><a href="#design">Design</a></li>
<li><a href="#exportedit">Exporting and further editing</a></li>
<li><a href="#credits">Credits</a></li>
</ul>
</div>
<div>
<img src="docs_images/example.png" alt="Example screenshot of the application." class="screenshot" style="margin-top: 25px;"/>
</div>
</div>
<a name="intro"></a><h2>Introduction</h2>
<p>
<a href="index.html">Choroplether</a> is a web application that allows you to create <a href="https://www.axismaps.com/guide/univariate/choropleth/" target="_blank">choropleth maps</a> in <a href="https://vega.github.io/vega-lite/" target="_blank">Vega-Lite</a> without having to write all the code yourself. The resulting output can be saved as an <abbr title="Scalable Vector Graphics">SVG</abbr> or <abbr title="Portable Network Graphics">PNG</abbr> image or opened within the <a href="https://vega.github.io/vega-editor/" target="_blank">Vega Editor</a> for further customisation. You can also embed the map in a webpage using <a href="https://github.com/vega/vega-embed" target="_blank">Vega-embed</a> if you require an interactive visualisation.
</p>
<p>
You supply some suitably formatted data, select or provide a spatial geography that matches the data and then customise the appearance. The interface is split into 3 sections: <a href="#data"><strong>Data</strong></a>, <a href="#geography"><strong>Geography</strong></a> and <a href="#design"><strong>Design</strong></a>, each can be collapsed and expanded as required by activating the toggle button at the top of each section. The app attempts to update the visualisation as you make changes in any of the sections, or when you activate the <strong>UPDATE</strong> button.
</p>
<br />
<a name="demo"></a><h2>Demonstration</h2>
<p>
<img src="docs_images/design.png" width="300" alt="Screenshot of the design section expanded." class="screenshot" style="float: left; margin-right: 20px; margin-bottom: 10px; padding: 10px;"/>
The app loads with an example dataset already visualised: Census 2021 population estimates from the <a href="https://www.ons.gov.uk/" target="_blank">Office for National Statistics</a> for the local authorities in Greater Manchester.
</p>
<p>
Expand the <strong>Design</strong> section using the toggle button and add a title by entering some text in the <strong>Map title:</strong> text box. Activate the <strong>UPDATE</strong> button and your title will be added to the map.
</p>
<p>
Next try changing the palette from <strong>tealblues</strong> to <strong>oranges</strong>.
</p>
<p>
Finally select each of the different scale options and see how the map visualisation and legend changes (you can find out what each scale option does in the <a href="#design"><strong>Design</strong></a> section of this documentation). This should give you an idea of how to customise the output. The next section explains how to create a map based on your own data.
</p>
<br class="noFloat"/>
<a name="data"></a><h2>Data</h2>
<p>
<img src="docs_images/data.png" width="300" alt="Screenshot of the data section expanded." class="screenshot" style="float: right; margin-left: 20px; padding: 10px;"/>
This is where you specify the dataset that will be visualised. You can do this by choosing a local file from your device or entering either the <abbr title="Uniform Resource Locator">URL</abbr> (must start with https://) of a data file or the contents of the file itself into the text box provided. The data can be in either <abbr title="Comma Separated Values"><a href="data_example.csv" target="_blank" aria-label="CSV - Comma Separated Values">CSV</a></abbr> or <abbr title="JavaScript Object Notation"><a href="data_example.json" target="_blank" aria-label="JSON - JavaScript Object Notation">JSON</a></abbr> format. The links provide you with example files which you can use as a template to help ensure you structure your data correctly. Once you have entered some data the app will attempt to visualise it. If your data relates to the geography currently selected in the <strong>Geography</strong> section it should display a map straightaway, otherwise the warning notification will be displayed asking you to check your data and/or the geography.
</p>
<p>
<img src="docs_images/warning.png" width="200" alt="Screenshot of the warning message." class="screenshot" style="float: left; margin-right: 20px; padding: 10px;"/>
The warning message means either that the data you have provided doesn't match the currently selected geography (the next section explains this in more detail) or there is something wrong with your data. The most important aspects are:
<br /><br />
1. The data must contain the field "<strong>value</strong>" which contains the values to be visualised.
<br />
2. Both the data and the geography must contain the field "<strong>area_code</strong>" as this is the joining variable used to match the data to the spatial geography. The only exception to this is if you are using a custom geography which doesn't have area codes defined for it, such as Trafford Localities. In this case both the data and the geography must contain the field "<strong>area_name</strong>".
</p>
<p>
You can find the <abbr title="Office for National Statistics">ONS</abbr> area codes for different administrative and statistical geographies from the <a href="http://geoportal.statistics.gov.uk/" target="_blank">Open Geography Portal</a>.
</p>
<br class="noFloat"/>
<a name="geography"></a><h2>Geography</h2>
<p>
<img src="docs_images/geography_initial.png" width="300" alt="Screenshot of the geography section expanded." class="screenshot" style="float: right; margin-left: 20px; padding: 10px;"/>
The geography is a spatial data file which describes the shapes associated with the data (e.g. the Electoral Wards within a Local Authority) as polygons using latitude and longitude coordinates. The list is pre-populated with different geographic boundaries within Trafford and Greater Manchester (at 20m generalised resolution). If your data is related to a different geographic location or type of geography select the <strong>Other (custom)</strong> option.
</p>
<p>
<img src="docs_images/geography_other.png" width="300" alt="Screenshot of the geography section expanded and custom option selected." class="screenshot" style="float: left; margin-right: 20px; padding: 10px;"/>
You can now provide your geography in a similar way to the data: choosing a local file from your device or entering either the <abbr title="Uniform Resource Locator">URL</abbr> (must start with https://) of a geography file or the contents of the file itself into the text box provided.
</p>
<p>
The geography must be valid <abbr title="Geospatial data in JavaScript Object Notation"><a href="https://geojson.org" target="_blank">GeoJSON</a></abbr>, an open-source spatial format, and each "<strong>Feature</strong>" must contain the field/property "<strong>area_code</strong>" to identify it. This field is used to match the features in the spatial geography to the data. The only exception to this is if you are using a custom geography which doesn't have area codes defined for it, such as Trafford Localities. In this case both the data and the geography must contain the field "<strong>area_name</strong>". This field, along with the data values, are also used for map labels. There is an interactive tooltip-style label which displays the name and data value associated to an area when you select/hover over it on the map, and additionally in the <a href="#design">Design</a> section you have the option to add area names and/or values as permanent labels on the map.
</p>
<p>
The following example from a spatial file describing the local authority boundaries within Greater Manchester demonstrates the use of the <strong>area_code</strong> field:
</p>
<code class="code noFloat" aria-label="Example code of a GeoJSON geography file">
<pre>
{
"type": "FeatureCollection",
"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
"features": [
{
"type": "Feature",
"properties": {
"area_code": "E08000009",
"area_name": "Trafford"
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [...
</pre>
</code>
<p>Trafford has an <strong>area_code</strong> of E08000009. In the example data files this <strong>area_code</strong> has the value <strong>235052</strong> (representing the Census 2021 population estimate). This value is assigned to a colour based on the range of values within the dataset and the type of <strong>scale</strong> you want to use, (this is explained in the Design section). The result is the shape of Trafford will be displayed, filled with the assigned colour.</p>
<br class="noFloat"/>
<a name="design"></a><h2>Design</h2>
<p>
<img src="docs_images/design.png" width="300" alt="Screenshot of the design section expanded." class="screenshot" style="float: right; margin-left: 20px; padding: 10px;"/>
The final section is where you specify how your finished map will look. There are options allowing you to add titles, attribution, map labels, select the palette and also choose the scale used to assign the palette to the data.
</p>
<p>
Map labels are useful when you want to use the visualisation as a static image in a document etc. You can choose to have labels for the just the area names, just the values, or both by selecting the relevant checkboxes. They work best with geographies containing around 10 or fewer areas and are limited in length, otherwise they will overlap too much. It is possible to make the map area larger if there are many labels, and/or increase the length of the labels, however you will need to amend the Vega-Lite code in the editor as described in the <a href="#exportedit">Exporting and further editing</a> section.
</p>
<p>
The palette options provided in the select list are a subset of the Vega <a href="https://vega.github.io/vega/docs/schemes/#seq-single-hue" target="_blank">sequential scheme names</a>. You can use any palette listed via the link within Vega-Lite, but Choroplether will only allow sequential palettes (single-hue and multi-hue) to be used. This is because sequential palettes are the most appropriate types to use for a choropleth map displaying differences in continuous data (e.g. population) rather than categorical data. If the palette you want is not listed, you can choose the <strong>Other (custom)</strong> option which will then display a text box for you to type in the scheme name. If you require a non-sequential palette you can edit the visualisation within the Vega Editor, (the <a href="#exportedit">Exporting and further editing</a> section has more information about this).
</p>
<p>
The scale determines how the colours are assigned to the map based on the data being displayed. There are 3 options: <strong>Linear</strong>, <strong>Quantile</strong> and <strong>Equal intervals</strong>. An additional <strong>Intervals</strong> selection list appears except when the <strong>Linear</strong> option is chosen.
</p>
<ul>
<li><strong>Linear</strong>: Assigns a unique colour from the palette to each unique value in the dataset range</li>
<li><strong>Quantile</strong>: Splits the dataset range into the number of intervals specified in the <strong>intervals</strong> select list, assigning an <span class="italic">equal number of observations</span> to each interval. The range of values within each interval can be different.</li>
<li><strong>Equal intervals</strong>: Splits the dataset range into the number of intervals specified in the <strong>intervals</strong> select list, assigning an <span class="italic">equal range of values</span> within each interval. The number of observations within each interval can be different.</li>
</ul>
<p>
The choice of scale depends on your data and what you are trying to show with the visualisation. The number of intervals available are between 4 and 7 inclusive. If you require a different number you will need to use the Vega Editor.
</p>
<br class="noFloat"/>
<a name="exportedit"></a><h2>Exporting and further editing</h2>
<p>
<img src="docs_images/export.png" width="150" alt="Screenshot of export options." class="screenshot" style="float: left; margin-right: 20px; padding: 10px;"/>
Located in the top-right corner of the map visualisation is a circle icon containing 3 dots. Selecting this icon provides the export options available to you.
</p>
<p>
If you are happy with your visualisation and simply need a static graphic to include in a report or presentation you can choose either the <strong>Save as <abbr title="Scalable Vector Graphics">SVG</abbr></strong> or <strong>Save as <abbr title="Portable Network Graphics">PNG</abbr></strong> options to create an image file in the relevant format.
</p>
<p>
To embed the interactive visualisation within a webpage you will need to choose <strong>View Source</strong> which provides the <a href="https://vega.github.io/vega-lite/docs/spec.html" target="_blank">Vega-Lite specification</a> (essentially the code) of your visualisation. You will then need to use the <a href="https://github.com/vega/vega-embed" target="_blank">Vega-Embed</a> tool (as Choroplether does) along with your specification. (The <strong>View Compiled Vega</strong> option is only relevant if you need to use features from the full <a href="https://vega.github.io/vega/" target="_blank">Vega</a> specification as opposed to Vega-Lite.)
</p>
<p>
Finally, <strong>Open in Vega Editor</strong> allows you to tweak and customise your visualisation further by editing the code in the online editor. To use this effectively you will need to read the <a href="https://vega.github.io/vega-lite/docs/" target="_blank">Vega-Lite documentation</a> and understand the Vega-Lite specification.
</p>
<br class="noFloat"/>
<a name="credits"></a><h2>Credits</h2>
<p>
Choroplether was created using the following:
</p>
<ul>
<li><a href="https://vega.github.io/vega-lite/" target="_blank">Vega-Lite</a> - (C) University of Washington Interactive Data Lab (<a href="https://github.com/vega/vega-lite/blob/master/LICENSE" target="_blank">LICENCE</a>)</li>
<li><a href="https://github.com/vega/vega-embed" target="_blank">Vega-Embed</a> - (C) University of Washington Interactive Data Lab (<a href="https://github.com/vega/vega-embed/blob/master/LICENSE" target="_blank">LICENCE</a>)</li>
<li><a href="https://fontawesome.com" target="_blank">Fontawesome</a> - (C) Fonticons, Inc. All rights reserved (<a href="https://fontawesome.com/license" target="_blank">LICENCE</a>)</li>
<li>All other code by <a href="https://www.trafforddatalab.io" target="_blank">Trafford Data Lab</a> (<a href="https://github.com/traffordDataLab/choroplether/blob/master/LICENSE" target="_blank">LICENCE</a>)</li>
</ul>
</main>
</div>
</body>
</html>