|
| 1 | +# Managing studies |
| 2 | + |
| 3 | +* [Anatomy of a study](#anatomy-of-a-study) |
| 4 | + * [Study configuration](#study-configuration) |
| 5 | + * [Map configuration](#map-configuration) |
| 6 | + * [Validating configuration](#validating-configuration) |
| 7 | +* [Howto](#hotwo) |
| 8 | + * [Add a new study](#add-a-new-study) |
| 9 | + * [Add a layer](#add-a-layer) |
| 10 | +* [AEP Map Style](#aep-map-style) |
| 11 | + * [Default styles](#default-styles) |
| 12 | + * [Custom markers](#custom-markers) |
| 13 | +* [FAQ](#faq) |
| 14 | +* [Troubleshooting](#troubleshooting) |
| 15 | + |
| 16 | +## Anatomy of a study |
| 17 | +The study configuration consists of two files: |
| 18 | + |
| 19 | +* a `yml` file that contains the basic information and metadata of the study. |
| 20 | +* a `json` file that contains the map configuration. |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +### Study configuration |
| 25 | +The main information and metadata of each study is managed through a `yml` file, with the following structure. For a full example, please see [`kenya.yml`](/content/study/posts/kenya.yml) |
| 26 | + |
| 27 | +| key | format | description | |
| 28 | +| --- | --- | --- | |
| 29 | +| title | `string` | The title of the study | |
| 30 | +| bbox | [`LngLatBounds`](https://docs.mapbox.com/mapbox-gl-js/api/geography/#lnglatbounds) object | The initial bounds of the map | |
| 31 | +| zoomExtent | `array` of `numbers` | The minimum and maximum zoom of the map | |
| 32 | +| mapConfig | `string` | The filename that contains the study's map configuration | |
| 33 | +| country | `string` | Country name | |
| 34 | +| study | `object` | Metadata about the study | |
| 35 | +| study.consultant | `string` | Name of the consultant | |
| 36 | +| study.period | `string` | Period of the study | |
| 37 | +| study.scope | `string` | Brief decription of the scope of the study | |
| 38 | +| study.summary | `string` | Summary of the study results | |
| 39 | +| platform | `object` | Reference to an external platform that hosts full study results | |
| 40 | +| platform.title | `string` | Title of the platform | |
| 41 | +| platform.url | `string` | URL of the platform | |
| 42 | +| layers | `array` | The layers that make up the layer switcher | |
| 43 | +| layers[].id | `string` | Unique ID of the layer | |
| 44 | +| layers[].name | `string` | Name of the layer that appears in the layer switcher | |
| 45 | +| layers[].category | `enum` one of [`contextual`, `results`] | The layer category is used to organize the layers | |
| 46 | +| layers[].mbLayer | `string` | ID of the layer. Should refer to a layer in the map configuration | |
| 47 | +| layers[].info | `string` | Used for the description in the info drawer | |
| 48 | +| layers[].disabled | `boolean` | If set to true, the `enable/disable` icon will be disabled. *Optional, defaults to false* | |
| 49 | +| layers[].visible | `boolean` | If set to true, this layers is enabled on first load. *Optional, defaults to false* | |
| 50 | +| layers[].info | `string` | Used for the description in the info drawer | |
| 51 | +| layers[].source | `object` | Link to the data source | |
| 52 | +| layers[].source.name | `string` | Name of the source link | |
| 53 | +| layers[].source.url | `string` | URL of the data source | |
| 54 | + |
| 55 | +### Map configuration |
| 56 | +The map is configured using the Mapbox Style specification. This provides a high degree of control over the style and interaction of the map of each study. Please refer to the [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/style-spec/) for a full description of the style spec. |
| 57 | + |
| 58 | +In addition to the default Mapbox styling, AEP has its own set of default styles, optimized for country level analysis. For more details see the [AEP default style](#aep-default-style) section. |
| 59 | + |
| 60 | +#### Validating configuration |
| 61 | +The `yml` and `json` files in `/content/study` are automatically validated when pushing a change to Github. If validation fails, it won't be possible to merge these changes into the `main` branch. |
| 62 | + |
| 63 | +Validation is done in two steps: |
| 64 | + |
| 65 | +1. the `yml` files are validated using the study schema in [`/schema/validate.js`](/schema/validate.js) |
| 66 | +2. the `json` files are validated using the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/) |
| 67 | + |
| 68 | + |
| 69 | +*All checks passing* |
| 70 | + |
| 71 | +#### Validating locally |
| 72 | +To validate changes prior to pushing them to Github, you can run the following command: |
| 73 | + |
| 74 | +``` |
| 75 | +yarn validate |
| 76 | +``` |
| 77 | + |
| 78 | +[To top](#managing-studies) |
| 79 | + |
| 80 | +## Howto |
| 81 | +### Add a new study |
| 82 | + |
| 83 | +1. create a new Github branch from `main` |
| 84 | +2. add a `yml` file to `/content/study/posts` with the [study configuration](#study-configuration) |
| 85 | +3. add a `json` file to `/content/study/posts` with the [map configuration](#map-configuration) |
| 86 | +4. set up a Pull Request and merge once [the validations](#validating-configuration) are run successfully |
| 87 | + |
| 88 | +### Add a layer |
| 89 | +Adding a layer and allowing users to interact with it, requires three things: |
| 90 | + |
| 91 | +1. add a source to the Mapbox Style Specification |
| 92 | +``` json |
| 93 | +"minigrid-proposed": { |
| 94 | + "data": "https://aep-tiles.staging.derilinx.com/geojson/ke/proposed_kosap_minigrid-wgs84.json", |
| 95 | + "type": "geojson" |
| 96 | +} |
| 97 | +``` |
| 98 | +2. add a layer to the Mapbox Style Specification that references the source |
| 99 | +```json |
| 100 | +{ |
| 101 | + "id": "minigrid-proposed", |
| 102 | + "type": "circle", |
| 103 | + "source": "minigrid-proposed" |
| 104 | +} |
| 105 | +``` |
| 106 | +3. add a layer to the study configuration (`yml`). This configures the layer in the layer switcher. |
| 107 | +```yml |
| 108 | + - id: minigrid-new |
| 109 | + name: New Mini-Grid Projects |
| 110 | + category: result |
| 111 | + mbLayer: minigrid-proposed |
| 112 | + info: Potential mini-grid projects; these projects were identified through a least-cost geospatial analysis undertaken over the period 2017-2018. |
| 113 | + source: |
| 114 | + name: energydata.info |
| 115 | + url: https://energydata.info/dataset/kenya-potential-new-mini-grid-sites |
| 116 | +``` |
| 117 | +
|
| 118 | +[To top](#managing-studies) |
| 119 | +
|
| 120 | +## Map style |
| 121 | +### AEP default style |
| 122 | +*More information to come* |
| 123 | +
|
| 124 | +### Custom markers |
| 125 | +AEP supports a number of custom icons that can be used to style point data instead of colored circles. See the folder `/content/icons` for the icons that are currently supported. |
| 126 | + |
| 127 | +#### Add icon to a layer |
| 128 | +Define a [`symbol`](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#symbol) layer. The name of the `icon-image` is the basename of the file, without extension `.png`. |
| 129 | + |
| 130 | +For example: |
| 131 | + |
| 132 | +``` json |
| 133 | +{ |
| 134 | + "id": "transformers", |
| 135 | + "type": "symbol", |
| 136 | + "source": "transformers", |
| 137 | + "source-layer": "data_layer", |
| 138 | + "layout": { |
| 139 | + "icon-image": "electricity" |
| 140 | + } |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +#### Add new icons to AEP |
| 145 | +New icons can be added to [`/content/icons`](/content/icons). They should be in `png` format and measure 64 x 64px. |
| 146 | + |
| 147 | +[To top](#managing-studies) |
| 148 | + |
| 149 | +## FAQ |
| 150 | +*More information to come* |
| 151 | + |
| 152 | +## Troubleshooting |
| 153 | +### Map shows an unexpected layer |
| 154 | +If the map loads with a layer that can't be managed through the layer switcher, it's likely that you added a layer in the Mapbox Style that isn't referenced in the layer configuration of the `yml`. This is by design. It allows you to overlay a contextual layer on the map that the user don't have control over. A use case could be a layer that adds a disputed border. |
0 commit comments