Merge pull request #58 from developmentseed/develop

New release

content/page/posts/about.md

@@ -0,0 +1,19 @@
+---
+title: About
+---
+## The tool
+
+Access to electricity remains a global development challenge with about 759 million people lacking access to electricity in 2019. Inadequate electricity services also pose a major impediment to reducing extreme poverty and boosting shared prosperity in Sub-Saharan Africa (SSA), where 570 million people and tens of millions of small and medium enterprises had no access to electricity.
+
+For this large share of the world population, welfare, health, and economic development are negatively impacted: children are unable to study at night; businesses, markets and health clinics have constrained operating hours and struggle to offer basic services; and productivity and competitiveness of African firms is impeded, to name just a few. Addressing the energy access challenge has become a global priority.
+
+In light of the close linkage between energy access and poverty alleviation, Sustainable Development Goal 7 was established to ensure universal access to affordable, reliable and modern energy services by 2030. This is particularly ambitious for Africa, which accounts for three-quarters of the global population without access. However, geospatial electrification planning has emerged as a critical tool to help countries think about how best to provide electricity access to those without it.
+
+Aligned with SDG 7 and with funding from the Energy Sector Management Assistance Program, the World Bank established the Geospatial Electrification Planning in the Africa Region program to support external client governments and internal task teams in the area of electrification planning for improved policy and decision-making.
+
+### Geospatial Electrification Planning in the Africa Region (GEPAR) is an ESMAP-funded program that aims to:
+
+- Support countries in the execution of geospatial analysis to inform policy, the development of national electrification strategies and plans as well as to provide analytical underpinnings for specific operations (project identification and scoping)
+- Improve upon existing geospatial planning approaches by ensuring that demand generated by the agricultural sector is incorporated into the analysis
+- Help countries think about evolving priorities, including electrification of health facilities in response to COVID-19, and climate resilience and adaptation
+- Build capacity of clients - in the area of electrification planning, rapid infrastructure mapping, and more

content/page/posts/support.md

@@ -0,0 +1,18 @@
+---
+title: Support
+---
+## What is geospatial electrification planning?
+
+Geospatial electrification planning has become the best-practice approach to determining how best to electrify people, using which technologies, and at what cost. This planning approach establishes high-resolution geospatial data systems to provide:
+
+- Long-term electricity demand forecasts 
+- Cost estimates of electricity supply options such as grid, mini-grid, and stand-alone systems to reach the potential consumers
+- Algorithmic, least-cost optimization of grid and off-grid systems, including a roll-out plan with phased investments *over time* to achieve universal electricity access or a given electrification target
+
+## How geospatial electrification planning is used by the Africa Region of the EEXGP?
+
+- To help inform operations (eg. Estimate potential and scope for access interventions or help with project design)
+- To help countries think about critical elements of and inform National Electrification Strategies
+- To promote transparency and rationality in Government planning and decision-making
+
+For guidance or advice, please [contact our team](mailto:[email protected]).

content/page/posts/toolkit.md

@@ -0,0 +1,60 @@
+---
+title: Toolkit
+---
+## Agriculture based energy demand
+
+### Overview
+
+Achieving universal electricity access by 2030 requires a rapid increase in the rate of new connections and in levels of investment, particularly in countries with low levels of access to electricity. Residential demand has been the main focus in many of the existing geospatial electrification models to date, with the role of productive uses only marginally included.
+
+However, access to electricity is a key part of improving rural productivity and income generating opportunities and therefore a crucial part of many African countries' economic development plans over the coming decade. Electrification of agriculture-related activities for example can create new opportunities in rural areas and lead to a socio-economic uplift. In turn, income generating activities can help diversify the potential customer pool, enhance business models and increase viability of electrification projects.
+
+This section briefly presents an analytical and spatially explicit approach for estimating aspects of electricity requirements related to agricultural activities; namely irrigation and few selected post-harvest activities. The underlying work has been a collaborative effort between [Vivid Economics](https://www.vivideconomics.com/) and [KTH Royal Institute of Technology](https://www.energy.kth.se/energy-systems/about-the-division-of-energy-systems-1.937036) and is part of a multi-year ESMAP-funded project - Geospatial Electrification Planning in the Africa Region (P165617) - aiming to facilitate the execution of geospatial electrification planning activities in various sub-Saharan African countries.
+
+### Methodology
+
+![Methodological flow](../media/toolkit-01.jpg "Methodological flow and key modelling elements of the geospatial model for agriculture-related electricity demand estimation. Source: KTH, Vivid Economics (2020).")
+
+The core part of the methodology is the **irrigation model**, which was developed to provide an estimate of crops’ water and electricity requirements in a designated area of interest (AoI). The ‘agrodem’ model has been constructed as such to allow for its full customization by the user based on available data, information and other modelling constraints.
+
+**Downscaling methods** have been explored in order to overcome data limitations or low resolution crop allocation data. The supporting methodology can help users build up input data in higher resolution using existing tabular data from surveys or statistics.
+
+To evaluate **future scenarios**, relevant code was developed in order to enable users explore hypothetical alternative scenarios of cropland expansion (“extensification”). This component enables the user to evaluate the impact of expected changes to crops, as well the impact that policy can have on the expansion of crops to new areas over time. Users can interact with the code and create alternative future scenarios that best suit the purpose of the modelling exercise.
+
+Finally, the model has been augmented to allow for assessment of electricity requirements for **post-harvest activities** (milling, drying, pressing, cold storage etc.). The model was developed as such to allow calibration of input data depending on the type of crop and AoI.
+
+----
+
+#### Note
+
+Each block of work described above is characterized by three elements, namely input – process – output. It also comes with open source code (available in the form of jupyter notebooks) that provides a clear step-by-step description of how to run the embedded processes. Full access to the code behind the model is available on [GitHub](https://github.com/akorkovelos/agrodem). Additional documentation is [available here](https://agrodem.readthedocs.io/en/latest/index.html).
+
+----
+
+### Output
+
+The primary output of the model indicates electricity requirements for irrigation of the selected crop and AoI. The spatial resolution of the results are defined by the initial vector later and stored in any GIS compatible, OGC complaint format (e.g .shp, .csv, .gpkg, .tiff). Each row indicates a particular location (e.g. farm); and each column indicates a particular attribute for this location. These include all attributes used to derive electricity requirements in the first place and products of the analysis (water and electricity requirements).
+
+![Methodology output](../media/toolkit-02.png "Indicative results showing locations of rainfed maize in need for irrigation in the base year (2017-18) in Mozambique. Source: KTH, Vivid Economics.")
+
+Of course, the degree of employment of the modelling blocks described earlier allow for different levels of analysis. They can be used to develop more complex scenarios and assess the model’s sensitivity to different input parameters (e.g., type of crops, crop calendar and yearly cycles, water management techniques, future scenarios, climate sensitivity, inclusion of post-harvesting activities) to name a few.
+
+![Electricity requirements](../media/toolkit-03.png "Electricity requirements for agriculture related activities are highly depended on input values, modelling parameters and assumptions. Those are, in turn, related to case study in focus as well as the scope of the modelling exercise. Source: KTH, Vivid Economics.")
+
+### Integration to geospatial least-cost modelling
+
+As described earlier, the modelling output consists of GIS layers indicating electricity demand for agricultural processing of a crop (or a combination of them), including e.g. irrigation and post-harvesting activities at a national level and under a defined scenario. This layer can be integrated with geospatial electrification modelling frameworks (e.g., the GEP) as follows:
+
+- A first-order integration may include the simple overlay of modelling outputs for a quick visual inspection and a high-level overview of key areas of interest (or hotspots) of electrification. 
+- A second-order integration may include the utilization of the agrodem output layer(s) into the modelling process. The model will then aggregate agricultural and residential electricity demand and assess the least cost electrification option. For example the GEP-OnSSET model has been developed in a way that allows such an integration. The model can then generate scenarios that explore the electrification mix with/without the inclusion of agricultural demand or even focus only on the agriculture nodes and assess their least cost electrification options.
+
+![Least cost electrification of agricultural nodes](../media/toolkit-04.png "Least cost electrification of agricultural nodes (farms) due to irrigation needs in Mozambique. Indicative example using agrodem results in GEP-OnSSET. Source: The World Bank.")
+
+### Contact
+
+For any questions, feedback or general inquiries please do not hesitate to contact the development team:
+
+- [Rhonda Lenai Jordan](mailto:[email protected]) 
+- [Alexandros Korkovelos](mailto:[email protected])
+- [Bonsuk Koo](mailto:[email protected])
+- [Kabir Malik](mailto:[email protected])

content/study/posts/congo.md

@@ -0,0 +1,7 @@
+## Scope
+
+To be determined...
+
+## Description
+
+To be determined...

content/study/posts/congo.yml

@@ -4,5 +4,4 @@ mapConfig: ./congo-mb.json
 study:
   consultant: Another consultant
   period: 2019
-  scope: not here yet...
-  summary: to be continued...
+  content: ./congo.md

content/study/posts/kenya.md

@@ -0,0 +1,14 @@
+## Scope
+
+National Least-cost geospatial plan identifying least-cost supply solutions and investment requirements to achieve universal electricity access by 2022 and maintain through 2027.
+
+## Description
+
+The geospatial electrification planning platform populated with the latest available census data, satellite imagery, consumption estimates as well as capital and operating cost data was used to evaluate expansion options.
+
+The data used for this report was collected/provided in 2016 and projected over succeeding years to evaluate connection expansion by technology including:
+- expansion of medium voltage service (grid expansion);
+- connection of consumers in close proximity to existing KPLC service (grid densification/intensification);
+- expansion of mini-grid service; and off-grid stand-alone solar home system service.
+
+For the target year 2022, the geospatial planning projects indicate that the following connection thresholds can be met.

content/study/posts/kenya.yml

@@ -6,8 +6,7 @@ country: Kenya
 study:
   consultant: NRECA
   period: 2017-2018
-  scope: National Least-cost geospatial plan identifying least-cost supply solutions and investment requirements to achieve universal electricity access by 2022 and maintain through 2027.
-  summary: The geospatial electrification planning platform populated with the latest available census data, satellite imagery, consumption estimates as well as capital and operating cost data was used to evaluate expansion options.  The data used for this report was collected/provided in 2016 and projected over succeeding years to evaluate connection expansion by  technology including expansion of medium voltage service (grid expansion); connection of consumers in close proximity to existing KPLC service (grid densification/intensification); expansion of mini-grid service; and off-grid stand-alone solar home system service. For the target year 2022, the geospatial planning projects indicate that the following connection thresholds can be met.
+  content: ./kenya.md
 charts:
   - name: Modelled Electricity demand (GWh/year)
     type: donut

docs/README.md

@@ -1,3 +1,16 @@
+# Static pages
+There are 3 static pages whose content can be customized using [Markdown](https://www.markdownguide.org/) files (found in `content/page/posts`):
+  - About
+  - Support
+  - Toolkit
+
+### Images and static pages
+Any image used in these pages should be placed inside `content/page/media` and then referenced using a relative path
+Example when editing a file inside `content/page/posts`:
+```
+![alt text](../media/img_name.png "Image caption if needed")
+```
+
 # Anatomy of a study
 The study configuration consists of two files:
 
@@ -19,8 +32,7 @@ The main information and metadata of each study is managed through a `yml` file,
 | study | `object` | Metadata about the study |
 | study.consultant | `string` | Name of the consultant |
 | study.period | `string` | Period of the study |
-| study.scope | `string` | Brief decription of the scope of the study |
-| study.summary | `string` | Summary of the study results |
+| study.content | `string` | The filename that contains the study's content in markdown |
 | platform | `object` | Reference to an external platform that hosts full study results |
 | platform.title | `string` | Title of the platform |
 | platform.url | `string` | URL of the platform |
@@ -42,8 +54,13 @@ The main information and metadata of each study is managed through a `yml` file,
 | layers[].legendData.dashed | `boolean` | Use a dashed line. Applies to `line` |
 | layers[].legendData.icon | `string` | The basename of the icon, without file extension. Applies to `symbol` |
 | layers[].legendData.min | `string` | Minimum value printed on the x-axis. Applies to `gradient` |
-| layers[].legendData.max | `string` | Maximum value printed on the x-axis. Applies to `gradient` 
-| layers[].legendData.stops | `array` | An array with RGB colors that indicate the stops. Applies to `gradient` 
+| layers[].legendData.max | `string` | Maximum value printed on the x-axis. Applies to `gradient` |
+| layers[].legendData.stops | `array` | An array with RGB colors that indicate the stops. Applies to `gradient` |
+| layers[].displayData | `array` | Configuration for the data to be displayed on the popover |
+| layers[].displayData[].label | `string` | A static label for the popover. Exclusive with `labelProp` |
+| layers[].displayData[].value | `string` | A static value for the popover. Exclusive with `valueProp` |
+| layers[].displayData[].labelProp | `string` | A dynamic label for the popover. Exclusive with `label` |
+| layers[].displayData[].valueProp | `string` | A dynamic value for the popover. Exclusive with `value` |
 
 ## Map configuration
 The map of each study is configured using a `json` file that follows the Mapbox Style specification. For a full example, please see [`kenya-mb.json`](/content/study/posts/kenya-mb.json).
@@ -78,7 +95,8 @@ yarn validate
 1. create a new Github branch from `main`
 2. add a `yml` file to `/content/study/posts` with the [study configuration](#study-configuration). The filename is used to determine the URL of the study. (`kenya.yml` -> `/studies/kenya`)
 3. add a `json` file to `/content/study/posts` with the [map configuration](#map-configuration)
-4. set up a Pull Request and merge once [the validations](#validating-configuration) are run successfully
+4. add a `md` file to `/content/study/posts` with the study content. This is rendered in the study summary page.
+5. set up a Pull Request and merge once [the validations](#validating-configuration) are run successfully
 
 ## Add a layer
 To add a new layer to a study that users can interact with, requires three things:
@@ -160,6 +178,10 @@ New icons can be added to [`/content/icons`](/content/icons). They should be in
 
 [To top](#managing-studies)
 
+
+### Update summary content
+The summary content can be updated from the study respective markdown file. This block is rendered bellow the summary overview.
+
 # Charts
 The charts on the Summary page are configured and managed through the `yml` file with study configuration. They are included on the right side of the summary page and ordered using the order in the study configuration file.
 
@@ -190,7 +212,7 @@ charts:
 ## Big number
 The big number consists of a title (`name`), a `value` and an optional `unit`.
 
-![](media/big-number.png)
+![](media/big-number.png)  
 _Big number with and without the `unit`_
 
 Configuration:
@@ -255,10 +277,60 @@ legendData:
 [To top](#managing-studies)
 
 # Popups
-The popups in the application show all the attributes that are available in the source data. To adjust the label or the value, you can update the original GeoJSON or Vector Tiles.
+By default, the popups in the application show all the attributes that are available in the source data. This can be customized by specifying a `displayData` list on the layer configuration.
 
 ![](media/popup.png)
 
+## Customizing popup data
+It is possible to extract data from the features the map layer and display it on a popover.
+For each layer you can specify a `label:value` pair using a syntax expression.
+Once a customization is defined, only the specified options will be displayed.
+
+![](media/popup-label-val.png)  
+_The label property will always be displayed in uppercase format._
+
+There are 2 properties to get a label and a value.
+  - When using `label` the value is assumed static and will be displayed as is.
+  - When using `labelProp` the value will be extracted from the feature data and computed.
+
+These two properties are mutually exclusive. Use one or the other, not both at the same time. The same is true for `value` and `valueProp`.
+
+To allow some processing of labels and values it is possible to use a simple inline piping syntax to define functions (and respective arguments) to apply to a value.
+The feature property name is always the first element to appear and subsequent functions are separated using pipes `|` and arguments are separated using colons `:`
+
+Example:
+```
+Length_km|round:2|suffix:km
+```
+In this example the system would get the value of the property `road_length` from the selected feature, `round` it to `2` decimal digits, and then add a `suffix` of `km`.
+
+The available functions are:
+```
+sum : value
+subtract : value
+multiply : value
+divide : value
+prefix : value
+suffix : value
+capitalize
+toUpperCase
+toLowerCase
+round : decimal_digits
+```
+
+Configuration:
+
+```yml
+displayData:
+  - label: A static label
+    value: Static value
+  - label: Length
+    valueProp: Length_km|round:2|suffix:km
+```
+
 # Troubleshooting
 ## Map shows an unexpected layer
 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.
+
+## Popover doesn't show a value after customization
+If no value is displayed double check that the property name is correct. Some times it is a matter of an uppercase letter.