diff --git a/.prettierignore b/.prettierignore index c51c13ccc..5424181a0 100644 --- a/.prettierignore +++ b/.prettierignore @@ -4,7 +4,8 @@ src/locales build cypress/fixtures/* cypress.env.json -docs +docs/maps.md +docs/resources/ colorbrewer.js diff --git a/docs/maps.md b/docs/maps.md index 92644e0c7..b6dfd71ef 100644 --- a/docs/maps.md +++ b/docs/maps.md @@ -1,685 +1,556 @@ # Using the Maps app { #using_maps } - ## About the Maps app { #about_maps } -The Maps App was introduced in release 2.29 and serves as a replacement -of the GIS App offering a more intuitive and user-friendly interface. -The mapping engine from version 2.34 is based on WebGL technology, -capable of showing thousands of features on a map simultaneously. +The Maps app was introduced in release 2.29 as a replacement for the original GIS app, offering a +more intuitive and user-friendly interface. Since version 2.34, the mapping engine is based on WebGL +technology, capable of showing thousands of features on a map simultaneously. + +> **Note** +> +> The Maps app requires WebGL. Visit [get.webgl.org](https://get.webgl.org) to verify that WebGL is +> working in your browser or to troubleshoot display issues. -With the Maps app you can overlay multiple layers and choose among -different basemaps. You can create thematic maps of areas and points, -view facilities based on classifications, and visualize catchment areas -for each facility. You can add labels to areas and points, and search -and filter using various criteria. You can move points and set locations -on the fly. Maps can be saved and shared with other users -and groups, or downloaded as an image. +With the Maps app, you can overlay multiple layers and choose from different basemaps. Supported +layer types include thematic maps, events, tracked entities, facilities, org unit boundaries, and +Earth Engine data such as population, elevation, or climate indicators. You can label features, +search and filter data, and save or share maps with other users, or download them as an image. Saved +maps can be added to dashboards in the **Dashboard** app. Thematic layers also integrate with the +**Data Visualizer** app, letting you open the same data as a chart. > **Note** > -> To use predefined legends in the **Maps** app, you need to create them -> first in the **Maintenance** app. +> To use predefined legends in the **Maps** app, you need to create them first in the +> **Maintenance** app. ![](resources/images/maps_main.png) -- The **layer panel** on the left side of the workspace shows an - overview of the layers for the current map: +### Layers panel - - As layers are added, using the **(+) Add layer** button, they - are arranged and managed in this panel. +The **layer panel** on the left side of the workspace shows an overview of the layers for the +current map: - - The **basemap** card is always shown in the panel. The default available - basemaps are OpenStreetMap Light (OSM Light), OpenStreetMap Detailed (OSM Detailed) - and Sentinel-2 Cloudless by EOX (Sentinel-2 EOX). The default selected basemap is OSM Light, - unless a different basemap has been configured in the system settings. - OSM Detailed contains more map features and place names. Sentinel-2 Cloudless is a cloud-free satellite imagery showing natural-color views of the Earth's surface with a 10m resolution. - - If the Azure or Bing Maps API key has been added by a system administrator, then there will be an additional 4 basemaps from Azure/Bing Maps. Road and Dark show roads, borders and places. Use the dark version if the colors on your map layers are bright. Aerial and Aerial Labels show satellite and detailed aerial imagery. Switch between them by selecting the desired image. +- As layers are added, using the **(+) Add layer** button, they are arranged and managed in this + panel. - *Note: Bing maps is being retired, see the announcement on the [Bing Maps Blog](https://aka.ms/BMERetirementAnnouncement). For migration to Azure Maps, you can consult the [Bing Maps Migration Overview](https://learn.microsoft.com/azure/azure-maps/migrate-bing-maps-overview).* +- The **basemap** card is always shown at the bottom of the panel. See + [Basemaps](#using_maps_basemaps) for available options. - - The small arrow button to the right of the layer panel, at the - top, allows the panel to be hidden or shown. +- The small arrow button to the right of the layer panel, at the top, allows the panel to be + hidden or shown. - +Each layer is represented by a card in the panel. Along the top of the card are a grab handle for +reordering layers with the mouse, the layer title, and an arrow to collapse or expand the card. The +middle of the card shows the layer legend where applicable. Along the bottom of the card from left +to right are: -- The **File** button near the top left allows you to open and save - maps. See [using the maps file menu](#using_maps_file_menu) for more detailed information. +- An edit (pencil) button opens the layer configuration dialog. - +- An eye symbol toggles the visibility of the layer. -- The **Download** button next to the File button allows you to download the current map as a PNG image. +- A slider modifies the layer transparency. - +- A more actions (three dots) button provides additional options, including showing or hiding the + data table, downloading the layer data, and removing the layer. -- The **Interpretations** button at top right opens an interpretations - panel on the right side of the workspace. See [viewing interpretations](#mapsInterpretation) for more information. +### Map controls - +- The **+** and **-** buttons on the map allow you to zoom in and out of the map respectively. The + mouse scroll wheel zoom is continuous, allowing you to fit the map perfectly to your content. -- The **+** and **-** buttons on the map allow you to zoom in and out - of the map respectively. The mouse scroll wheel zoom is continuous, - allowing us to fit the map perfectly to your content. +- The **rotate map** button (triangle arrows) allows you to rotate and tilt the map to enhance the + view of your data. Press and hold the button (or hold the Control key on your keyboard) while + moving your mouse to change the map view. Click the button again to reset the view. -- The **rotate map** button (triangle arrows) allows you to - rotate and tilt the map to enhance the view of your data. Press and hold the button - (or hold the Control key on your keyboard) while moving your mouse to change the - map view. Click to button again to reset the view. +- **Fullscreen** (four arrows) allows you to view the map in fullscreen. To exit fullscreen, click + the button again or press the escape key on your keyboard. -- **Fullscreen** (four arrows) allows you to view the map in fullscreen. - To exit fullscreen click the button again or the escape key on your keyboard. +- **Zoom to content** (bounded magnifying glass symbol) automatically adjusts the zoom level and + map center position to put the data on your map in focus. -- **Zoom to content** (bounded magnifying glass symbol) automatically - adjusts the zoom level and map center position to put the data on - your map in focus. - -- **Search** (magnifying glass symbol) allows searching for and - jumping to a location on the map. +- **Search** (magnifying glass symbol) allows searching for and jumping to a location on the map. - The **ruler** button allows you to measure distances and areas on the map. -- Right-click on the map to display the longitude and latitude of that - location. - -**Basemaps** - -Basemap layers are represented by layer _cards_ in the layer panel such -as: +- Right-click on the map to display the longitude and latitude of that location. -![](resources/images/maps_basemap_card.png) - -Along the top of the basemap card from left to right are: - -- The title of the selected basemap - -- An arrow symbol to collapse and expand the basemap card +### File menu -In the middle of the basemap card is the list of available basemaps. The -current basemap is highlighted. +- The **File** button near the top left allows you to open and save maps. See + [using the maps file menu](#using_maps_file_menu) for more detailed information. -Along the bottom of the basemap card is: - -- An eye symbol for toggling the visibility of the layer - -- A slider for modifying the layer transparency +- The **Download** button next to the File button allows you to download the current map as a PNG + image. +- The **Interpretations** button at top right opens an interpretations panel on the right side of + the workspace. See [viewing interpretations](#mapsInterpretation) for more information. ## Create a new map { #using_maps_create_map } -1. In the **Apps** menu of DHIS2, click **Maps**. The **DHIS2 Maps** app - opens. +When you open the Maps app, you start with an empty map canvas and the default basemap selected. If +a map is already open, start a new one using **File** > **New**. You can change the basemap at any +time from the basemap card in the layer panel (see [Basemaps](#using_maps_basemaps)). -2. Click the (+) Add layer button in the top left. You are presented - with the layer selection dialog: +To add a layer, click the **(+) Add layer** button in the top left. The layer selection dialog +opens: - ![](resources/images/maps_layer_selection.png) +![](resources/images/maps_layer_selection.png) -3. Select a layer to add to the current map. Possible options are: +Available layer types are: - - [Thematic](#using_maps_thematic_layer) +- [**Thematic**](#using_maps_thematic_layer): Visualize data values (indicators or data elements) + aggregated by org unit. +- [**Events**](#using_maps_event_layer): Display individual events from event or tracker programs. +- [**Tracked entities**](#using_maps_tracked_entity_layer): Display tracked entities and their + relationships on the map. +- [**Facilities**](#using_maps_facility_layer): Display facilities as icons based on their + coordinates. +- [**Org units**](#using_maps_org_unit_layer): Display org unit boundaries. - - [Events](#using_maps_event_layer) +In addition, several layers may be provided by [Google Earth Engine](#using_maps_gee) (such as +population, elevation, or climate indicators) and +[other external services](#using_maps_external_map_layers). Various Google Earth Engine layer +sources are available if the Google Earth Engine API key has been set up (see +[documentation](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API)). - - [Tracked entities](#using_maps_tracked_entity_layer) - - - [Facilities](#using_maps_facility_layer) - - - [Org units](#using_maps_org_unit_layer) - - In addition, several layers may be provided by [Google Earth - Engine](#using_maps_gee) and [other external services](#using_maps_external_map_layers). Various Google Earth Engine layer sources are available - if the Google Earth Engine API key has been set up (see [documentation](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API)). - - > **Note** - > - > The [**Maps app administrator**](#maps_app_administrator) can: - > - > - Select the sources for Google Earth Engine layers available to other users via the **Manage available layer sources** button. - > - Add external layer sources in the Maintenance app. - - Here is the list of default sources for a Google Earth Engine layer (see [complete list](#using_maps_gee)): +> **Note** +> +> The [**Maps app administrator**](#maps_app_administrator) can: +> +> - Select the sources for Google Earth Engine layers available to other users via the **Manage +> available layer sources** button. +> - Add external layer sources in the Maintenance app. +## Basemaps { #using_maps_basemaps } - - Population and Population age groups +A basemap provides the background map on which your data layers are displayed. You can select and +configure the basemap from the **basemap** card at the bottom of the layer panel. - - Building footprints +The following basemaps are available by default: - - Elevation +- **OSM Light**: A minimal, light-colored map based on OpenStreetMap data. This is the default + basemap. +- **OSM Detailed**: Contains more map features and place names. +- **Sentinel-2 EOX**: Cloud-free satellite imagery showing natural-color views of the Earth's + surface at 10m resolution. - - Precipitation (monthly) +If a Bing Maps or Azure Maps API key has been configured by a system administrator, four additional +basemaps become available from each provider. Both providers offer the same four styles, prefixed +with the provider name — for example, **Bing Road** and **Azure Road**: - - Temperature (monthly) +- **Road**: Shows roads, borders and places. +- **Dark**: A dark-themed road map. Useful when the colors on your data layers are bright. +- **Aerial**: Satellite and detailed aerial imagery. +- **Aerial Labels**: Aerial imagery with place name labels. - - Landcover +A [**Maps app administrator**](#maps_app_administrator) can also add external basemaps via the +Maintenance app. These appear in the basemap card alongside the default basemaps. - The single default source for an external layer is: +Basemap layers are represented by a card in the layer panel. The card shows the list of available +basemaps with the current one highlighted. Controls at the bottom allow you to toggle the basemap +visibility and adjust its transparency. - - Labels overlay +![](resources/images/maps_basemap_card.png) +> **Note** +> +> Bing Maps is being retired. See the [Bing Maps Blog](https://aka.ms/BMERetirementAnnouncement) for +> the retirement announcement. For migration to Azure Maps, consult the +> [Bing Maps Migration Overview](https://learn.microsoft.com/azure/azure-maps/migrate-bing-maps-overview). ## Manage thematic layers { #using_maps_thematic_layer } -_Thematic maps_ represent spatial variation of geographic distributions. -Select your desired combination of indicator/data element, period and -organisation unit level. If your database has coordinates and aggregated -data values for these organisation units, they will appear on the map. +_Thematic maps_ represent spatial variation of geographic distributions. They display aggregated +data values for a selected data item (such as an indicator or data element), period and org unit +level. Org units with coordinates and matching data values will appear on the map. > **Note** > -> You must generate the DHIS2 analytics tables to have aggregated data -> values available. +> You must generate the DHIS2 analytics tables to have aggregated data values available. ![](resources/images/maps_thematic_mapping.png) -Thematic layers are represented by layer _cards_ in the layer panel such -as: - -Along the top of the thematic card from left to right are: - -- A grab field to allow dragging and re-ordering layers with the mouse - -- The title and period associated with the layer - -- An arrow symbol to collapse and expand the thematic card - -In the middle of the thematic card is a legend indicating the value -ranges displayed on the layer. - -Along the bottom of the thematic card from left to right are: - -- An edit (pencil) button to open the layer configuration dialog - -- An eye symbol for toggling the visibility of the layer - -- A slider for modifying the layer transparency - -- A more actions (three dots) button with additional options: - - - A **Show/hide data table** toggle button to show or hide the data table - associated with the layer - - - **Open as chart** will open this thematic data as a chart in the Data Visualizer app - - - **Download data** allows you to download the data for this layer in GeoJSON format for use in other mapping software - - - **Edit layer** is the same as edit button above - - - **Remove layer** will remove this layer from the current map. +Thematic layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the value ranges displayed on the layer. The more actions (three dots) button +includes options to show or hide the data table, download the data, and open the data as a chart in +the Data Visualizer app via **Open as chart**. ### Create a thematic layer -To create a thematic layer, choose **Thematic** on the **Add -layer** selection. This opens the Thematic layer configuration dialog. +To create a thematic layer, choose **Thematic** on the **Add layer** selection. This opens the +Thematic layer configuration dialog. -1. In the **Data** tab: +#### 1. Data - ![](resources/images/maps_thematic_layer_dialog_DATA.png) +![](resources/images/maps_thematic_layer_dialog_DATA.png) - - Select a data item. +- Select a data item. - - Select a value from the **Aggregation type** field for the data - values to be shown on the map. By default, "By data element" is - selected. Alternative values are: Count; Average; Sum; Standard - deviation; Variance; Min; Max. See also [Aggregation - operators](https://dhis2.github.io/dhis2-docs/master/en/user/html/ch10s05.html#d0e8082). +- Select a value from the **Aggregation type** field for the data values to be shown on the map. + By default, "By data element" is selected. Alternative values are: Count, Average, Sum, Standard + deviation, Variance, Min, Max. See also + [Aggregation operators](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/metadata.html#create_data_element:~:text=Aggregation%20operators). - - **Only show completed events**: Includes only completed events in the aggregation process. - This is useful when you want to exclude partial events in indicator calculations. Available - for indicators, program indictors and event data items. +- **Only show completed events**: Includes only completed events in the aggregation process. This + is useful when you want to exclude partial events in indicator calculations. Available for + indicators, program indicators and event data items. -2. In the **Period** tab +#### 2. Period - ![](resources/images/maps_thematic_layer_dialog_PERIOD.png) +![](resources/images/maps_thematic_layer_dialog_PERIOD.png) - Select the time span over which the thematic data is mapped. +Select the time span over which the thematic data is mapped. - - **Period display mode** - Select how the selected periods will be visualized on the map: +- **Period display mode**: Select how the selected periods will be visualized on the map: - - _Single_ (default) + - _Single_ (default): Displays all selected periods as a single combined layer with aggregated + data. Required when only one period is selected or when using start–end dates. - Displays all selected periods as a single combined layer with aggregated data. - (Required when only one period is selected or when using start–end dates.) + - _Timeline_: Displays multiple periods as an interactive timeline ordered chronologically. + Multiple timeline layers can be added to a map (they will all share the same periods). - - _Timeline_ + - _Split_: Displays multiple periods side by side for comparison. Supports up to 12 periods + (including multi-period presets) and can only be combined with other split layers (they will + all share the same periods). - Displays multiple periods as an interactive timeline ordered chronologically. - Multiple timeline layers can be added to a map (they will all share the same - periods). +- After selecting a display mode, choose how to define the periods: - - _Split_ + - **Choose from presets**: Available for all display modes. You can combine one or more + relative and fixed periods. - Displays multiple periods side by side for comparison. Supports up to 12 periods - (including multi-period presets) and can only be combined with other split layers - (they will all share the same periods). + - _Relative period_: Select **Relative periods**, then the **Period type** (**Years**, + **Months**, etc.) and choose one or more relative periods, such as **This year** and + **Last year** or **Last 12 months**. A **default relative period for analysis** can be + set in the **System Settings** app. - - After selecting a display mode, choose how to define the period(s): - - - **Choose from presets** - _Available for all display modes. If you selected Single, you will also see_ Define start–end dates _as an alternative._ You can combine one or more relative and fixed periods. + - _Fixed period_: Select **Fixed periods**, then choose the **Period type** (**Yearly**, + **Monthly**, etc.) and choose one or more fixed periods, such as **2024** or **January + 2025** and **February 2025**. - - _Relative period_ + - **Define start–end dates**: Available only when the Single display mode is selected. Specify + exact start and end dates. Both dates are inclusive and will be reflected in the outputs. - Select **Relative periods**, then the **Period type** (**Years**, **Months**, etc.) and choose one or more relative periods, such as **This year** and **Last year** or **Last 12 months**. +#### 3. Org units - A **default relative period for analysis** can be set in the **Systems Settings** app. +![](resources/images/maps_thematic_layer_dialog_ORG_UNITS.png) - - _Fixed period_ +- Select the org units you want to include in the layer. It is possible to select either - Select **Fixed periods**, then choose the **Period type** (**Yearly**, **Monthly**, etc.) and choose one or more fixed periods, such as **2024** or **January 2025** and **Febuary 2025**. + - One or more specific org units, org unit levels in the hierarchy, org unit groups, or - - **Define start - end dates** - _Available only when the Single display mode is selected._ Specify exact start and end dates. Both dates are inclusive and will be reflected in the outputs. + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. -3. In the **Org Units** tab: +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. - ![](resources/images/maps_thematic_layer_dialog_ORG_UNITS.png) +#### 4. Filter - - Select the organisation units you want to include in the layer. - It is possible to select either +![](resources/images/maps_thematic_layer_dialog_FILTER.png) - - One or more specific organisation units, organisation unit levels in - the hierarchy, organisation unit groups, or +- Click **Add filter** and select an available data item to add a new filter to the data set. - - A relative level in the organisation unit hierarchy, with - respect to the user. By selecting a **User organisation - unit** the map data will appear differently for users at - different levels in the organisation unit hierarchy. + - Select a data dimension from the dropdown box. You can reduce the number of dimensions shown + by using the search field. Click the name to select a dimension. - - **Use associated geometry**: This dropdown will only show if there - are any additional geometry available for your organisation units. - This is typically used to show facility catchment areas. + - When a dimension is selected you get a second dropdown with dimension items. Check the items + you want to include in the filter. -4. In the **Filter** tab: + Multiple filters may be added. Click the trash button on the right of the filter to remove it. - ![](resources/images/maps_thematic_layer_dialog_FILTER.png) +#### 5. Style { #using_maps_thematic_layer_style } - - Click **Add Filter** and select an available data item to add a new - filter to the data set. +![](resources/images/maps_thematic_layer_dialog_STYLE.png) - - Select a data dimension from the dropdown box. You can - reduce the number of dimensions shown by using the search field. - Click on the name to select a dimension. +- Select either **Choropleth** or **Bubble map**. - - When a dimension is selected you get a second dropdown with - dimension items. Check the items you want to include in the - filter. + - A choropleth map assigns a color to each org unit shape according to the data value. This is + the recommended technique if the data is normalized (per capita). - Multiple filters may be added. Click the trash button on the right of - the filter to remove it. + - A bubble map shows data values as proportional circles. Use this technique if the data is + not normalized (absolute numbers). The circles are placed in the center of each org unit. + Set the **Low radius** and **High radius** for the proportional circles. The circles will be + scaled between low and high radius according to the data value. The radius must be between 0 + and 50 pixels. -5. In the **Style** tab: +- **Show labels**: Show org unit names and/or values on the layer. Select **Name**, **Name and + value**, or **Value**. Font size, weight, style and color can also be modified. - ![](resources/images/maps_thematic_layer_dialog_STYLE.png) +- **Count org units without coordinates**: Org units without map coordinates are counted and shown + in a **Data quality** section of the legend. They also appear in the data table. These org units + may or may not have data. - - Select either **Choropleth** or **Bubble map**. +- Select the legend type: - - Choropleth will assign a color to each org unit shape according to the data value. This is the recommended technique if the data is normalised (per capita). + - **Automatic color legend**: A legend is automatically created based on the classification + method, number of classes and color scale you select. Set **Classification** to one of: - - Bubble map will show data values as proportional circles. Use this - technique if the data is not normalised (absolute numbers). The circles are placed in the center of each org unit. + - _Equal intervals_: Divides the value range into equally-sized intervals, each spanning + (highest value − lowest value) ÷ number of classes. + - _Equal counts_: Org units are distributed as evenly as possible across classes (also + known as quantile classification). Some datasets cannot be evenly partitioned, + particularly when values are heavily repeated or the number of distinct values is small. + - _Natural breaks (intervals)_ and _Natural breaks (clusters)_: Class boundaries are + placed at the largest gaps in the data distribution, based on the + [ckmeans](https://simple-statistics.github.io/docs/#ckmeans) algorithm. Both methods + group values similarly; _intervals_ produces contiguous class ranges, while _clusters_ + may leave gaps between classes where no values fall. + - _Pretty breaks_: Break points are rounded to clean, human-readable numbers. Based on R's + [pretty](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/pretty) + algorithm. + - _Logarithmic scale_: Uses a logarithmic scale. Values must be positive; zero or negative + values are left unclassified. + - _Standard deviation_: Classes are defined as multiples of standard deviations from the + mean. The number of standard deviations per class depends on the number of classes + chosen; values further from the mean are left unclassified. - - Set the **Low radius** and **High radius** for the proportional circles or the point facilities. The circles will be scaled between low and high radius according to the data value. The radius needs to be between 0 and 50 px. + **Decimal places**: Number of decimal places shown in legend labels. **Auto** lets the app + decide based on the data range, or choose a fixed value from **0** to **6** (also available + for single color legends). - - **Show labels**: Allows org unit names and values to be shown on the layer. - Select between "Name", "Name and value" and "Value" only. Font size, weight, style - and color can also be modified. + **Isolated class**: Define a value range (min–max) with a fixed color and optional label. + Org units in that range are shown separately and excluded from automatic classification. - - **Show no data**: By default org units with missing data values will not show on the map. - Check this box if you want to show them with a color. Click the color to change it. + - **Predefined color legend**: Select from the predefined legends. - - Select the legend type: + - **Single color legend**: Select the color of the bubbles or circles. Only available for + bubble maps. - - **Automatic color legend**: the application will create a legend for you based on - what classification method, number of classes and the color scale you select. Set - **Classification** to either: +- **Include unclassified org units**: Org units whose values fall outside all classification + ranges are shown with a configurable color and label (default: "Unclassified"). - - Equal intervals +- **Include org units with no data**: Org units with no data value are shown with a configurable + color and label (default: "No data"). - the range of each interval will be (highest data value - lowest data value / number of classes) +> **Note**: All legend items and their counts - including **No data** and **Unclassified** - only +> include org units with coordinates. - - Equal counts - - the legend creator will try to distribute the organisation units evenly. - - - **Predefined color legend**: Select between the predefined legends. - - - **Single color legend**: Select the color of the bubbles or circles. Only available - for bubble maps. +> **Note** +> +> Most classes use half-open intervals (`startValue ≤ value < endValue`): a value sitting exactly on +> a boundary belongs to the upper class, not the one whose label ends there. The exceptions - where +> the upper bound is inclusive - are the last class, isolated classes, single-value classes, and +> clusters (natural breaks). +> +> If the exact class a boundary value belongs to matters for your analysis, use **Show labels** to +> overlay values directly on each feature. If it still matters after that, consider whether a +> different legend, maybe with more classes or higher decimal precision, is the right tool for the +> decision you are trying to make. -6. Click **Add layer**. +Click **Add layer**. ### Modify a thematic layer -1. In the layer panel, click the edit (pencil) icon on the thematic - layer card. +1. In the layer panel, click the edit (pencil) icon on the thematic layer card. -2. Modify the setting on any of the tabs as desired. +2. Modify the settings on any of the tabs as desired. 3. Click **Update layer**. ### Filter values in a thematic layer -Thematic layers have a **Show/hide data table** option that can be toggled on or -off from the thematic layer card. +Thematic layers have a **Show/hide data table** option that can be toggled on or off from the +thematic layer card. ![](resources/images/maps_thematic_layer_data_table.png) -The data table displays the data forming the thematic layer. - -- clicking on a up/down arrow button will sort the table based on that column; - toggling between ascending and descending. - -- entering text or expressions into the filter fields below the titles - will apply those filters to the data, and the display will adjust - according to the filter. The filters are applied as follows: - - - NAME - - filter by name containing the given text - - - VALUE - - filter values by given numbers and/or ranges using `>` (greater - than), `<` (less than), `>=` (greater than or equal), or `<=` - (less than or equal). Use `,` for OR and `&` for AND logic, for - example: `2,>3&<8` matches the value 2, or any value greater - than 3 and less than 8. - - - LEGEND - - filter by legend containing the given text +The data table displays the data associated with the thematic layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. - - RANGE +The name filter field is an effective way to search for individual org units. - filter by ranges containing the given text - - - LEVEL - - filter level by numbers and/or ranges, using the same operators - as VALUE, for example: `2,>3&<8` - - - PARENT - - filter by parent names containing the given text - - - ID - - filter by IDs containing the given text - - - TYPE - - filter by GIS display types containing the given text - - - COLOR - - filter by color names containing the given text +For numeric columns, you can filter using comparison operators: `>`, `<`, `>=`, and `<=`. Use `,` +for OR logic and `&` for AND logic — for example: `2,>3&<8` matches the value 2 or any value greater +than 3 and less than 8. > **Note** > -> Data table filters are temporary and are not saved with the map layers -> as part of the saved map. - -### Search for an organisation unit +> Data table filters are temporary and are not saved with the map. -The NAME filter field in the data table provides an effective way of -searching for individual organisation units. +### Open org unit profile -### Open organisation unit profile +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: -You can open the [organisation unit profile](#using_maps_org_unit_profile) in three ways: +1. Click an org unit on the map, then click the **View profile** button in the popup. -1. Click on any of the organisasjon units shown on the map, and click - the **View profile** button in the popup. +2. Right-click one of the org units on the map, and select **View profile** from the menu. -2. Right-click one of the organisation units on the map, and select **View profile** - from the menu. +3. Click an org unit row in the **data table**. -3. Click on an organisation unit row in the **data table**. +### Navigate between org unit hierarchies -### Navigate between organisation hierarchies +When there are visible org units on the map, you can easily navigate up and down in the hierarchy +without changing the org unit selection. -When there are visible organisation units on the map, you can easily -navigate up and down in the hierarchy without using the level/parent -user interface. - -1. Right-click one of the organisation units. +1. Right-click one of the org units. 2. Select **Drill up one level** or **Drill down one level**. - The drill down option is disabled if you are on the lowest level or - if there are no coordinates available on the level below. Likewise - the drill up option is disabled from the highest level. - -### Remove thematic layer - -To clear all data in a thematic layer: + The drill down option is disabled if you are on the lowest level or if there are no coordinates + available on the level below. Likewise, the drill up option is disabled from the highest level. -1. In the layer card to the left, click the _more actions_ (three dots) icon - and then on **Remove layer**. - - The layer is removed from the current map. +### Remove a thematic layer +To remove a thematic layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. ## Manage event layers { #using_maps_event_layer } -The event layer displays the geographical location of events registered -in the DHIS2 tracker. Provided that events have associated point or polygon -coordinates, you can use this layer to drill down from the aggregated -data displayed in the thematic layers to the underlying individual -events or cases. +The event layer displays the geographical location of events recorded in DHIS2 programs. When events +have associated point or polygon coordinates, you can drill down from aggregated data in thematic +layers to the underlying individual events or cases. Alternative coordinate fields also let you plot +events using locations other than the event itself, such as the org unit or enrollment location. -You can also display aggregated events for facilities or organisation -units. You do this through a thematic layer using event data -items. This is useful when you only have the coordinates for the Org -Unit under which the events are recorded. +To display aggregated event statistics at the org unit level, use a thematic layer with event data +items instead. ![](resources/images/maps_event_layer.png) -Event layers are represented by layer _cards_ in the layer panel such -as: - -Along the top of the event card from left to right are: - -- A grab field to allow dragging and re-ordering layers with the mouse - -- The title and period associated with the layer - -- An arrow symbol to collapse and expand the event card - -In the middle of the event card is a legend indicating the styling of -the layer. - -Along the bottom of the event card from left to right are: - -- An edit (pencil) button to open the layer configuration dialog - -- An eye symbol for toggling the visibility of the layer - -- A slider for modifying the layer transparency - -- A more actions (three dots) button with additional options: - - - A **Show/hide data table** toggle button to show or hide the data table associated with the layer - - - **Download data** allows you to download the data for this layer in GeoJSON format for use in other mapping software - - - **Edit layer** is the same as edit button above - - - **Remove layer** will remove this layer from the current map. +Event layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the styling of the layer. The more actions (three dots) button includes options to +show or hide the data table and to download the data in GeoJSON format. ### Create an event layer { #maps_create_event_layer } -To create an event layer, choose **Events** on the **Add -layer** selection. This opens the Events layer configuration dialog. +To create an event layer, choose **Events** on the **Add layer** selection. This opens the Events +layer configuration dialog. -1. In the **Data** tab: +#### 1. Data - ![](resources/images/maps_event_layer_dialog_DATA.png) +![](resources/images/maps_event_layer_dialog_DATA.png) - - Select a program and then select a program stage. The **Stage** - field is only shown once a program is selected. +- Select a program and then select a program stage. The **Stage** field is only shown once a + program is selected. - If there is only one stage available for the selected program, - the stage is automatically selected. + If there is only one stage available for the selected program, the stage is automatically + selected. - - Select a value from the **Coordinate field** to determine which positions are displayed - on the map. By default, "Event location" is selected. You can also choose "Organisation unit location". - Depending on the selected program, additional options may include "Tracked entity location", "Enrollment location", and coordinate-type/organisation-unit-type data elements or attributes such as "Household location"/"Referral facility". - The number of events represented on the map may vary depending on the selected option and the availability of coordinates. Organisation units are represented by their centroids. +- Select a value from the **Coordinate field** to determine which positions are displayed on the + map. By default, "Event location" is selected. You can also choose "Org unit location". + Depending on the selected program, additional options may include "Tracked entity location", + "Enrollment location", and coordinate or org unit type data elements or attributes, such as + "Household location" or "Referral facility". The number of events represented on the map may + vary depending on the selected option and the availability of coordinates. Org units are + represented by their centroids. - - By default all events with coordinates are shown on the map. - Use the **Event status** field to only show events having one - status: Active, Completed, Schedule, Overdue or Skipped. +- By default, all events with coordinates are shown on the map. Use the **Event status** field to + only show events having one status: Active, Completed, Schedule, Overdue, or Skipped. -2. In the **Period** tab +#### 2. Period - ![](resources/images/maps_event_layer_dialog_PERIOD.png) +![](resources/images/maps_event_layer_dialog_PERIOD.png) - - Select the time span for when the events took place. You can - select either a fixed period or a relative period. +- Select the time span for when the events took place. You can select either a fixed period or a + relative period. - - _Relative period_ + - _Relative period_: Select one of the relative periods, for example **This month** or **Last + year**. A **default relative period for analysis** can be set in the **System Settings** + app. - In the **Period** field, select one of the relative periods, - for example **This month** or **Last year**. + - _Fixed period_: Select **Start/end dates** and fill in a start date and an end date. - A **default relative period for analysis** can be set in the - **Systems Settings** app. +#### 3. Org units - - _Fixed period_ +![](resources/images/maps_event_layer_dialog_ORG_UNITS.png) - In the **Period** field, select **Start/end dates** and fill - in a start date and an end date. +- Select the org units you want to include in the layer. It is possible to select either -3. In the **Org Units** tab: + - One or more specific org units, or - ![](resources/images/maps_event_layer_dialog_ORG_UNITS.png) + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. - - Select the organisation units you want to include in the layer. - It is possible to select either +#### 4. Filter - - One or more specific organisation units, or +![](resources/images/maps_event_layer_dialog_FILTER.png) - - A relative level in the organisation unit hierarchy, with - respect to the user. By selecting a **User organisation - unit** the map data will appear differently for users at - different levels in the organisation unit hierarchy. +- Click **Add filter** and select an available data item to add a new filter to the data set. -4. In the **Filter** tab: + - For data item of type _option set_, you can select any of the options from the dropdown box, + or type to filter. - ![](resources/images/maps_event_layer_dialog_FILTER.png) + - For data item of type _number_, you can select operators like equal, not equal, greater than + or less than. - - Click ADD FILTER and select an available data item to add a new - filter to the data set. + - For data item of type _boolean_ (yes/no), you can check the box if the condition should be + true. - - For data item of type _option set_, you can select any of - the options from the dropdown box by using the down-wards - arrow or by start typing directly in the box to filter for - options. + - For data item of type _text_, select **Contains** (matches any value containing the search + text) or **Is exact** (matches only identical values). - - For data item of type _number_, you can select operators like - equal, not equal, greater than or less than. + Multiple filters may be added. Click the trash button on the right of the filter to remove it. - - For data item of type _boolean_ (yes/no), you can check the box - if the condition should be valid or true. +#### 5. Style - - For data item of type _text_ you will get two choices: - **Contains** implies that the query will match all values - which contains your search value, and **Is exact** implies - that only values which is completely identical to your - search query will be returned. +![](resources/images/maps_event_layer_dialog_STYLE.png) - Multiple filters may be added. Click the trash button on the right of - the filter to remove it. +- Select **Group events** to group nearby events (cluster), or **View all events** to display + events individually. -5. In the **Style** tab: + - Select a **color** and **radius** (between 1 and 20) for the event or cluster points. - ![](resources/images/maps_event_layer_dialog_STYLE.png) + - Select **Show buffer** to display a visual buffer around each event. The radius of the + buffer can be modified here. Only available when **View all events** is selected. - - Select **Group events** to group nearby events (cluster), or - **View all events** to display events individually. +- **Count events without coordinates**: Events without coordinates are counted and shown in a + **Data quality** section of the legend. They also appear in the data table. These events may or + may not have data. - - Select a **color** for the event or cluster points. +- Select **Style by data item** (data element or attribute) to colorize the events according to a + data value. If events are grouped, clusters are displayed as small donut charts showing the + distribution of the data values. The available options vary for different data types: - - Select the **radius** (between 1 and 20) for the events. + - **Option sets**: Select a color for each option in an option set. You can set default colors + for an option in the Maintenance app. - - Select **Show buffer** to display visual buffer around each - event. The radius of the buffer can be modified here. This - option is only available if you select **View all events** - above. + - **Numbers**: You can style a numeric data item in + [the same way as thematic layers](#using_maps_thematic_layer_style) using automatic or + predefined legends. - - Select a **Style by data item** (data element or attribute) to colorise - the events according to a data value. If you also select to group events, - the culsters will be displayed as small donut charts showing - the distribution of the data values. The available options vary for - different data types: + - **Booleans**: Select a color for true/yes and another for false/no. - - **Option sets**: Select a color for each option in an option - set. You can set default colors for an option in the - Maintenance app. + **Include unclassified events**: Events whose values fall outside all classification ranges are + shown with a configurable color and label (default: "Unclassified"). - - **Numbers**: You can style a numeric data item in [the same - way as thematic layers](#using_maps_thematic_layer_style) using - automatic or predefined legends. + **Include events with no data**: Events with no data value are shown with a configurable color + and label (default: "No data"). - - **Booleans**: Select a color for true/yes and another for - false/no. +> **Note**: All legend items and their counts - including **No data** and **Unclassified** - only +> include events with coordinates. -6. Click **Add layer**. +Click **Add layer**. ### Modify an event layer -1. In the layer panel, click the edit (pencil) icon on the event layer - card. +1. In the layer panel, click the edit (pencil) icon on the event layer card. -2. Modify the setting on the DATA, PERIOD, FILTER, ORG UNIT and STYLE - tabs as desired. +2. Modify the settings on the **Data**, **Period**, **Filter**, **Org units** and **Style** tabs as + desired. 3. Click **Update layer**. -### Listing and filtering events +### Filter events -Event layers have a **Show/hide data table** option that can be toggled on or -off from the event layer card. +Event layers have a **Show/hide data table** option that can be toggled on or off from the event +layer card. ![](resources/images/maps_event_layer_data_table.png) -The data table displays the data forming the event layer. - -- clicking on the up/down arrow will sort the table based on that column; - toggling between ascending and descending. - -- entering text or expressions into the filter fields below the titles - will apply those filters to the data, and the display will adjust - according to the filter. The filters are applied as follows: - - - ID - - filter by event IDs containing the given text - - - ORG UNIT - - filter by org unit name containing the given text - - - EVENT TIME - - filter by event time containing the given text - - - TYPE +The data table displays the data associated with the event layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. - filter by GIS display types containing the given text - - - **Style by data item**: If events are styled by a data element or - attribute (e.g. gender) both the data value and the color can be filtered. - - - **Display in reports**: Data elements checked to display in reports will - be shown in separate columns (see below how to add them). - - - Numeric data values can be filtered by given numbers, and/or ranges, - for example: 2,\>3&\<8 +Additional columns appear for data elements configured to display in reports, and for any data item +used to style the events — both the data value and the color can be filtered in those columns. +Numeric columns support comparison operators: `>`, `<`, `>=`, and `<=`, with `,` for OR and `&` for +AND logic — for example: `2,>3&<8`. > **Note** > -> Data table filters are temporary and are not saved with the map layers -> as part of the saved map. +> Data table filters are temporary and are not saved with the map. ### Modify information in event data table and popups -If you have access to the selected program in the Maintenance app, you can modify the information displayed in the event pop-up window. +If you have access to the selected program in the Maintenance app, you can modify the information +displayed in the event popup window. ![](resources/images/maps_eventlayer_eventinfopopup.png) @@ -689,167 +560,143 @@ If you have access to the selected program in the Maintenance app, you can modif 3. Click the program you want to modify and select **(2) Assign data elements**. -4. For every data element you want to display in the pop-up window, - select corresponding **Display in reports**. +4. For every data element you want to display in the popup window, select corresponding **Display + in reports**. 5. Click **Save**. ### Download raw event layer data -The raw data for event layers can be downloaded in GeoJSON format for more advanced geo-analytics and processing in desktop GIS software such as [QGIS](https://www.qgis.org/). The downloaded data includes all individual events as GeoJSON features, including attributes for each data element selected for **Display in reports**. +The raw data for event layers can be downloaded in GeoJSON format for more advanced geo-analytics +and processing in desktop GIS software such as [QGIS](https://www.qgis.org/). The downloaded data +includes all individual events as GeoJSON features, including attributes for each data element +selected for **Display in reports**. ![](resources/images/maps_data_download_dialog.png) -- In the layer card to the left, click the _more actions_ (three dots) icon and then on **Download data** - -- Select the **ID format** to use as the key for Data Element values in the downloaded GeoJSON file. There are three options available: +- In the layer card to the left, click the _more actions_ (three dots) icon and then click + **Download data**. - - **ID** - Use the unique ID of the data element - - **Name** - Use the human-friendly name of the data element (translated) - - **Code** - Use the code of the data element +- Select the **ID format** to use as the key for data element values in the downloaded GeoJSON + file: -- Select whether or not to **Use human-readable keys** for other Event attributes, such as Program Stage, Latitude, Longitude, Event Data, and Organization Unit ID, Name, and Code. When this option is **not** selected these values will be the computer-friendly ID instead of the human-readable (and translated) name. + - **ID**: Use the unique ID of the data element. + - **Name**: Use the human-friendly name of the data element (translated). + - **Code**: Use the code of the data element. -- Click the **Download** button to generate and download a GeoJSON file. The data will be requested from the DHIS2 server and processed by the maps application. This operation may take several minutes to complete. +- Select whether or not to **Use human-readable keys** for other event attributes, such as Program + Stage, Latitude, Longitude, Event Data, and Org Unit ID, Name, and Code. When this option is + **not** selected, these values will be computer-friendly IDs instead of human-readable + (translated) names. -- Once the GeoJSON file has been downloaded it can be imported into most standard GIS software applications. +- Click the **Download** button to generate and download a GeoJSON file. The data will be + requested from the DHIS2 server and processed by the maps application. This operation may take + several minutes to complete. -> Note that the downloaded data does not include style information as it is not natively supported by the GeoJSON format. Styles can optionally be recreated in external GIS applications using the attributes of each feature. +- Once the GeoJSON file has been downloaded, it can be imported into most standard GIS software. -### Clear event layer - -To clear all event layer data in a map: - -1. In the layer card to the left, click the _more actions_ (three dots) icon - and then on **Remove layer**. +> **Note** +> +> The downloaded data does not include style information as it is not natively supported by the +> GeoJSON format. Styles can optionally be recreated in external GIS applications using the +> attributes of each feature. - The layer is removed from the current map. +### Remove an event layer +To remove an event layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. ## Manage tracked entity layers { #using_maps_tracked_entity_layer } -The tracked entity layer displays the geographical location of tracked -entities registered in the DHIS2. Provided that tracked entities have -associated point or polygon coordinates, you can explore these on a map. +The tracked entity layer displays the geographical location of tracked entities registered in DHIS2. +Tracked entities with associated point or polygon coordinates appear on the map. ![](resources/images/maps_tracked_entity_layer.png) -Tracked entity layers are represented by layer cards in the layer panel -such as: - -Along the top of the tracked entity card from left to right are: - -- A grab field to allow dragging and re-ordering layers with the - mouse. - -- The title and period associated with the layer. - -- An arrow symbol to collapse and expand the tracked entity card. - -In the middle of the tracked entity card is a legend indicating the -styling of the layer. +Tracked entity layers are represented by layer cards in the layer panel. The middle of the card +shows a legend indicating the styling of the layer. -Along the bottom of the tracked entity card from left to right are: +### Create a tracked entity layer { #maps_create_tracked_entity_layer } -- An edit (pencil) button to open the layer configuration dialog +To create a tracked entity layer, choose **Tracked entities** on the **Add layer** selection. This +opens the Tracked entity layer configuration dialog. -- An eye symbol for toggling the visibility of the layer +#### 1. Data -- A slider for modifying the layer transparency - -- A more actions (three dots) button with additional options: - - - **Edit layer** is the same as edit button above - - - **Remove layer** will remove this layer from the current map. - -### Create a tracked entity layer { #maps_create_tracked_enity_layer } - -To create an tracked entity layer, choose **Tracked entities** on the -**Add layer** selection. This opens the Tracked entity layer -configuration dialog. - -1. In the **Data** tab: +![](resources/images/maps_tracked_entity_layer_dialog_DATA.png) - ![](resources/images/maps_tracked_entity_layer_dialog_DATA.png) +- Select the **Tracked entity type** you want to show on the map. - - Select the **Tracked Entity Type** you want to show on the map. +- Select a **Program** to filter tracked entities by enrollment. - - Select a **Program** where the tracked entities belong. +- Use the **Program status** field to select the enrollment status of tracked entities to include: + All, Active, Completed, or Cancelled. - - Use the **Program status** field to select the enrollment status of tracked entities - to include: All, Active, Completed or Cancelled. +- Filter by the **Follow-up** flag to include only tracked entities marked for follow-up. - - Set the **Follow up** status of the tracked entity for the given - program. +#### 2. Relationships -2. In the **Relationships** tab +![](resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png) - ![](resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png) - - > **Caution** - > - > Displaying tracked entity relationships in Maps is an experimental feature +> **Caution** +> +> Displaying tracked entity relationships in Maps is an experimental feature. - - If a Tracked Entity Type with relationships has been selected, you can select the **Display Tracked Entity relationships** checkbox +- Select the **Display tracked entity relationships** checkbox to show relationships on the map. - - Once checked, you can select the type of relationship to display on the map from the dropdown list. Only relationships from the selected Tracked Entity type are available. +- Select the **Relationship type** to display from the dropdown list. Only relationships defined + for the selected tracked entity type are available. -3. In the **Period** tab +#### 3. Period - ![](resources/images/maps_tracked_entity_layer_dialog_PERIOD.png) +![](resources/images/maps_tracked_entity_layer_dialog_PERIOD.png) - - If no program is selected, you can set start and end dates when - the tracked entities were last updated. +- If no program is selected, you can set start and end dates for when the tracked entities were + last updated. - - If a program is selected, you can set the period when tracked entities were last - updated or when they were registered or enrolled in the program. +- If a program is selected, you can set the period when tracked entities were last updated or when + they were enrolled in the program. -4. In the **Org Units** tab: +#### 4. Org units - ![](resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png) +![](resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png) - - Select the organisation units you want to include in the layer. - You have 3 selection modes: +- Select the org units you want to include in the layer. Three selection modes are available: - - **Selected only**: Include tracked entities belonging to - selected org units only. + - **Selected only**: Include tracked entities belonging to selected org units only. - - **Selected and below**: Included tracked entities in and - right below selected org units. + - **Selected and below**: Include tracked entities in and right below selected org units. - - **Selected and all below**: Included tracked entities in and - all below selected org units. + - **Selected and all below**: Include tracked entities in and all below selected org units. -5. In the **Style** tab: +#### 5. Style - ![](resources/images/maps_tracked_entity_layer_dialog_STYLE.png) +![](resources/images/maps_tracked_entity_layer_dialog_STYLE.png) - - Select a **color** for the tracked entities points and polygons. +- Select a **Color** for tracked entity points and polygons. - - Select the **point size** (radius between 1 and 20) for the - points. +- Select the **Point size** (radius between 1 and 20) for the points. - - Select **Show buffer** to display visual buffer around each - tracked entity. The buffer distance in meters can be modified - here. +- Select **Buffer** to display a visual buffer around each tracked entity. The buffer distance in + meters can be modified here. - - If a relationship type has been selected on the relationships tab you can select **color**, **point size**, and **line color** for relationships and related tracked entities instances +- If a relationship type has been selected on the Relationships tab, you can select a **Color** + and **Point size** for related tracked entities and a **Line color** for the relationship lines. -6. Click **Add/Update layer**. +Click **Add layer**. ### Modify a tracked entity layer -1. In the layer panel, click the edit (pencil) icon on the tracked - entity layer card. +1. In the layer panel, click the edit (pencil) icon on the tracked entity layer card. -2. Modify the setting on the DATA, PERIOD, ORG UNIT and STYLE tabs as - desired. +2. Modify the settings on the **Data**, **Relationships**, **Period**, **Org units** and **Style** + tabs as desired. 3. Click **Update layer**. ### Modify information in tracked entity popups -If you have access to the selected program in the Maintenance app, you can modify the information displayed in the tracked entity pop-up window. +If you have access to the selected program in the Maintenance app, you can modify the information +displayed in the tracked entity popup window. ![](resources/images/maps_eventlayer_eventinfopopup.png) @@ -859,594 +706,435 @@ If you have access to the selected program in the Maintenance app, you can modif 3. Click the program you want to modify and select **(3) Attributes**. -4. For every attribute you want to display in the pop-up window, - select corresponding **Display in list**. +4. For every attribute you want to display in the popup window, enable **Display in list**. 5. Click **Save**. -### Clear a tracked entity layer - -To clear a tracked entity layer from a map: - -1. In the layer card to the left, click the _more actions_ (three dots) icon - and then on **Remove layer**. - - The layer is removed from the current map. +### Remove a tracked entity layer +To remove a tracked entity layer from the map, in the layer card to the left, click the _more +actions_ (three dots) icon and then click **Remove layer**. ## Manage facility layers { #using_maps_facility_layer } -The facility layer displays icons that represent types of facilities. -Polygons do not show up on the map, so make sure that you select an -organisation unit level that has facilities. - -_A polygon is an enclosed area on a map representing a country, a -district or a park._ +The facility layer displays icons representing types of facilities. Only point-type org units are +shown - polygon org units such as districts or regions are not displayed. ![](resources/images/maps_facility_layer.png) -Facility layers are represented by layer _cards_ in the layer panel such -as: - -Along the top of the facilities card from left to right are: - -- A grab field to allow dragging and re-ordering layers with the mouse - -- The **Facilities** title - -- An eye symbol for toggling the visibility of the layer - -- An arrow symbol to collapse and expand the facilities card - -In the middle of the facilities card is a legend indicating the group -set representation. - -Along the bottom of the facilities card from left to right are: - -- An edit (pencil) button to open the layer configuration dialog - -- A slider for modifying the layer transparency - -- A more actions (three dots) button with additional options: - - - A **Show/hide data table** toggle button to show or hide the data table - associated with the layer - - - **Download data** allows you to download the data for this layer in GeoJSON format for use in other mapping software - - - **Edit layer** is the same as edit button above - - - **Remove layer** will remove this layer from the current map. +Facility layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the group set representation. The more actions (three dots) button includes +options to show or hide the data table and to download the data in GeoJSON format. ### Create a facility layer -To create facility layer, choose **Facilities** on the **Add -layer**selection. This opens the Facility layer configuration dialog. +To create a facility layer, choose **Facilities** on the **Add layer** selection. This opens the +Facility layer configuration dialog. -1. In the **Organisation Units** tab +#### 1. Org units - ![](resources/images/maps_facility_layer_dialog_ORG_UNITS.png) +![](resources/images/maps_facility_layer_dialog_ORG_UNITS.png) - - Select the organisation unit level(s) and/or group(s) from the - selection fields on the right hand side. +- Select org unit levels and/or groups from the selection fields on the right-hand side. - - Select the organisation units you want to include in the layer. - It is possible to select either +- Select the org units you want to include in the layer. It is possible to select either - - One or more specific organisation units, or + - One or more specific org units, or - - A relative level in the organisation unit hierarchy, with - respect to the user. By selecting a **User organisation - unit** the map data will appear differently for users at - different levels in the organisation unit hierarchy. + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. - - The system administrator can set the default organsation unit - level containing facilities in the **System Settings** app. +- The system administrator can set the default org unit level containing facilities in the + **System Settings** app. - - **Use associated geometry**: This dropdown will only show if there - are any additional geometry available for your organisation units. - This is typically used to show facility catchment areas. +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. -2. In the **Style** tab: +#### 2. Style - ![](resources/images/maps_facility_layer_dialog_STYLE.png) +![](resources/images/maps_facility_layer_dialog_STYLE.png) - - Select any styling you wish to apply to the facilities. +- **Labels**: Allows labels to be shown on the layer. Font size, weight and color can be modified + here. - - Show labels +- **Buffer**: Displays a visual buffer around each facility. The radius of the buffer can be + modified here. Not available if associated geometry is used. - Allows labels to be shown on the layer. Font size, weight - and color can be modified here. +- **Count org units without a point location**: Org units without point coordinates are counted + and shown in a **Data quality** section of the legend. They also appear in the data table. - - Show buffer +- Facilities with a point location can be styled with an **org unit group set** using different + icons. Select a group set from the list of org unit group sets defined for your DHIS2 instance. + The system administrator can set the default org unit group set in the **System Settings** app. - Allows a visual buffer to be displayed on the layer around - each facility. The radius of the buffer can be modified - here. Buffer option is not available if asscoiated geometry is used. + **Include unclassified org units**: Org units not belonging to any group in the selected group + set are shown with a configurable color and label (default: "Unclassified"). - - Facilities can be styled an **organisation unit group set** using - different icons. Select a group set from the list of organisation - unit group sets defined for your DHIS2 instance. - The system administrator can set the default organsation unit - group set in the **System Settings** app. +- If no group set is selected, the facilities will be shown as filled circles. The color and + radius can be changed. - - If no group set is selected, the facilities will be shown as filled - circles. The color and the circle radius can be changed. +Click **Add layer**. -3. Click **Add layer**. +### Modify a facility layer -### Create or modify a facility layer +1. In the layer panel, click the edit (pencil) icon on the facility layer card. -1. In the layer panel, click the edit (pencil) icon on the facility - layer card. - -2. Modify the setting on the GROUP SET, ORGANISATION UNITS and STYLE - tabs as desired. +2. Modify the settings on the **Org units** and **Style** tabs as desired. 3. Click **Update layer**. ### Filter values in a facility layer -Facility layers have a **Show/hide data table** option that can be toggled on or -off from the facility layer card. +Facility layers have a **Show/hide data table** option that can be toggled on or off from the +facility layer card. ![](resources/images/maps_facility_layer_data_table.png) -The data table displays the data forming the facility layer. - -- clicking on the up/down arrow will sort the table based on that column; - toggling between ascending and descending. - -- entering text or expressions into the filter fields below the titles - will apply those filters to the data, and the display will adjust - according to the filter. The filters are applied as follows: - - - NAME - - filter by name containing the given text - - - ID - - filter by IDs containing the given text - - - TYPE - - filter by GIS display types containing the given text +The data table displays the data associated with the facility layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. The name filter field is an effective way to search for individual facilities. > **Note** > -> Data table filters are temporary and are not saved with the map layers -> as part of the saved map. - -### Search for a facility +> Data table filters are temporary and are not saved with the map. -The NAME filter field in the data table provides an effective way of -searching for individual facilities. +### Open org unit profile -### Open organisation unit profile +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: -You can open the [organisation unit profile](#using_maps_org_unit_profile) in three ways: +1. Click an org unit on the map, then click the **View profile** button in the popup. -1. Click on any of the organisasjon units shown on the map, and click - the **View profile** button in the popup. +2. Right-click one of the org units on the map, and select **View profile** from the menu. -2. Right-click one of the organisation units on the map, and select **View profile** - from the menu. +3. Click an org unit row in the **data table**. -3. Click on an organisation unit row in the **data table**. - -### Remove facility layer - -To clear all data in a facility layer: - -1. In the layer card to the left, click the _more actions_ (three dots) icon - and then on **Remove layer**. - - The layer is removed from the current map. +### Remove a facility layer +To remove a facility layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. ## Manage org unit layers { #using_maps_org_unit_layer } -The org unit layer displays the borders and locations of your -organisation units. This layer is particularly useful if you are offline -and don't have access to background maps. +The org unit layer displays the borders and locations of your org units. This layer is particularly +useful if you are offline and don't have access to background maps. ![](resources/images/maps_org_unit_layer.png) -Org unit layers are represented by layer _cards_ in the layer panel such -as: - -Along the top of the org unit card from left to right are: - -- A grab field to allow dragging and re-ordering layers with the mouse - -- The **Organisation unit** title - -- An arrow symbol to collapse and expand the org unit card - -Along the bottom of the org unit card from left to right are: - -- An edit (pencil) button to open the layer configuration dialog - -- An eye symbol for toggling the visibility of the layer - -- A slider for modifying the layer transparency - -- A more actions (three dots) button with additional options: - - - A **Show/hide data table** toggle button to show or hide the data table - associated with the layer - - - **Download data** allows you to download the data for this layer in GeoJSON format for use in other mapping software - - - **Edit layer** is the same as edit button above - - - **Remove layer** will remove this layer from the current map. +Org unit layers are represented by layer cards in the layer panel. The more actions (three dots) +button includes options to show or hide the data table and to download the data in GeoJSON format. ### Create an org unit layer -To create an org unit layer, choose **Org units** on the **Add -layer** selection. This opens the org unit layer configuration dialog. - -1. In the **ORGANISATION UNITS** tab - - ![](resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png) +To create an org unit layer, choose **Org units** on the **Add layer** selection. This opens the Org +unit layer configuration dialog. - - select the organisation unit level(s) and/or group(s) from the - selection fields on the right hand side. +#### 1. Org units - - Select the organisation units you want to include in the layer. - It is possible to select either +![](resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png) - - One or more specific organisation units, or +- Select org unit levels and/or groups from the selection fields on the right-hand side. - - A relative level in the organisation unit hierarchy, with - respect to the user. By selecting a **User organisation - unit** the map data will appear differently for users at - different levels in the organisation unit hierarchy. +- Select the org units you want to include in the layer. It is possible to select either - - **Use associated geometry**: This dropdown will only show if there - are any additional geometry available for your organisation units. - This is typically used to show facility catchment areas. + - One or more specific org units, or -2. In the **Style** tab: + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. - ![](resources/images/maps_org_unit_layer_dialog_STYLE.png) +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. - - select any styling you wish to apply to the org unitss. +#### 2. Style - - Labels +![](resources/images/maps_org_unit_layer_dialog_STYLE.png) - Allows labels to be shown on the layer. Font style can be - modified here. +- **Labels**: Allows labels to be shown on the layer. Font style can be modified here. - - Boundary color +- **Boundary color**: Allows the boundary or outline color of the org units to be changed. - Allows the boundary or outline color of the organisation units - to be changed. +- **Point radius**: Sets the base radius when point type elements, such as facilities, are + presented on the org unit layer. - - Point radius +- **Count org units without coordinates**: Org units without coordinates are counted and shown in + a **Data quality** section of the legend. They also appear in the data table. - Sets the base radius when point type elements, such as - facilities, are presented on the org unit layer. +- Org units with coordinates can be styled with an **org unit group set** using different colors. + Select a group set from the list of org unit group sets defined for your DHIS2 instance. - - Organisation units can be styled an **organisation unit group set** - using different colors. Select a group set from the list of organisation - unit group sets defined for your DHIS2 instance. + **Include unclassified org units**: Org units not belonging to any group in the selected group + set are shown with a configurable color and label (default: "Unclassified"). -3. Click **Add layer**. +Click **Add layer**. ### Modify an org unit layer -1. In the layer panel, click the edit (pencil) icon on the org unit - layer card. +1. In the layer panel, click the edit (pencil) icon on the org unit layer card. -2. Modify the setting on the ORGANISATION UNITS and STYLE tabs as - desired. +2. Modify the settings on the **Org units** and **Style** tabs as desired. 3. Click **Update layer**. ### Filter values in an org unit layer -Org unit layers have a **Show/hide data table** option that can be toggled on or -off from the org unit layer card. +Org unit layers have a **Show/hide data table** option that can be toggled on or off from the org +unit layer card. ![](resources/images/maps_bound_layer_data_table.png) -The data table displays the data forming the org unit layer. - -- clicking on a title will sort the table based on that column; - toggling between ascending and descending. - -- entering text or expressions into the filter fields below the titles - will apply those filters to the data, and the display will adjust - according to the filter. The filters are applied as follows: - - - NAME +The data table displays the data associated with the org unit layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. The name filter field is an effective way to search for individual org units. - filter by name containing the given text +The level column supports numeric filtering using comparison operators: `>`, `<`, `>=`, and `<=`, +with `,` for OR and `&` for AND logic — for example: `2,>3&<8`. - - LEVEL - - filter level by numbers and/or ranges, for example: 2,\>3&\<8 +> **Note** +> +> Data table filters are temporary and are not saved with the map. - - PARENT +### Open org unit profile - filter by parent names containing the given text +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: - - ID +1. Click an org unit on the map, then click the **View profile** button in the popup. - filter by IDs containing the given text +2. Right-click one of the org units on the map, and select **View profile** from the menu. - - TYPE +3. Click an org unit row in the **data table**. - filter by GIS display types containing the given text +### Navigate between org unit hierarchies -> **Note** -> -> Data table filters are temporary and are not saved with the map layers -> as part of the saved map. +When there are visible org units on the map, you can navigate up and down in the hierarchy without +changing the org unit selection. -### Search for an organisational unit +1. Right-click one of the org units. -The NAME filter field in the data table provides an effective way of -searching for individual organisational units displayed in the org unit -layer. +2. Select **Drill up one level** or **Drill down one level**. -### Open organisation unit profile + The drill down option is disabled if you are on the lowest level. Likewise, the drill up option + is disabled from the highest level. -You can open the [organisation unit profile](#using_maps_org_unit_profile) in three ways: +### Remove an org unit layer -1. Click on any of the organisasjon units shown on the map, and click - the **View profile** button in the popup. +To remove an org unit layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. +## Manage Earth Engine layers { #using_maps_gee } -2. Right-click one of the organisation units on the map, and select **View profile** - from the menu. +![](resources/images/maps_ee_layer.png) -3. Click on an organisation unit row in the **data table**. +Google Earth Engine layers are enabled if a Google Earth Engine API key has been configured for your +system. Contact your system administrator if you need access to these layers. -### Navigate between organisation hierarchies +The layers from Google Earth Engine let you display and aggregate external data for your org units. +Aggregated values can be viewed either in popups or in the data table. -You can modify the target of the org unit layer in the hierarchy without -using the level/parent user interface. +Earth Engine layers are represented by layer cards in the layer panel. The more actions (three dots) +button includes an option to show or hide the data table. -1. Right-click one of the organisation units. +![](resources/images/maps_ee_layer_types.png) -2. Select **Drill up one level** or **Drill down one level**. +> **Note** +> +> The [**Maps app administrator**](#maps_app_administrator) can configure available layer sources. - The drill down option is disabled if you are on the lowest level. - Likewise the drill up option is disabled from the highest level. +The following layer sources are supported (sources marked with an asterisk "\*" are available by +default): -### Remove org unit layer +- **Population (group)**: Detailed population data from WorldPop. Estimates are provided annually + and include current, historical, and projected population values. Available between 2015 + and 2030. -To clear all data in an org unit layer: + - **Population** \*: Total population count. + - **Population age groups** \*: Population broken down by age and gender. -1. In the layer card to the left, click the _more actions_ (three dots) icon - and then on **Remove layer**. +- **Building footprints** \*: The outlines of buildings derived from high-resolution satellite + imagery. Only for sub-Saharan Africa, South and Southeast Asia, Latin America and the Caribbean. - The layer is removed from the current map. +- **Elevation** \*: Elevation above sea level. -## Manage Earth Engine layer { #using_maps_gee } +- **Heat stress (group)**: Universal Thermal Climate Index (UTCI), a measure of the thermal stress + experienced by a person in a given environment. Available from 1950. -![](resources/images/maps_ee_layer.png) + - **Heat stress daily**. + - **Heat stress weekly** (derived from daily dataset). + - **Heat stress monthly** (derived from daily dataset). -Google Earth Engine layers are enabled if a Google Earth Engine API key has -been configured for your system. Contact your system administrator if you -need access to these layers. +- **Humidity (group)**: Relative humidity is the amount of water vapour present in air. Available + from 1950. -The layers from Google Earth Engine let you display and aggregate external -data to your organisation units. Aggregated values can be viewed either in -popups or in the data table. + - **Humidity daily**. + - **Humidity weekly** (derived from daily dataset). + - **Humidity monthly**. -![](resources/images/maps_ee_layer_types.png) +- **Precipitation (group)**: Accumulated water that falls to the surface. Combines model data with + observations from across the world. Two sources are available: -> **Note** -> -> The [**Maps app administrator**](#maps_app_administrator) can configure -> available layer sources. - - -The following layer sources are supported (sources marked with an asterisk -"*" are available by default): - -- **Population (group)**: Detailed population data from WorldPop. Estimates are provided annually and include current, historical, and projected population values. Available between 2015 and 2030. - - **Population** *: Total population count. - - **Population age groups** *: Population broken down by age and gender. - -- **Building footprints** *: The outlines of buildings derived from - high-resolution satellite imagery. Only for sub-Saharan Africa, South and - Southeast Asia, Latin America and the Caribbean. - -- **Elevation** *: Elevation above sea level. - -- **Heat stress (group)**: Universal Thermal Climate Index (UTCI), a measure - of the thermal stress experienced by a person in a given environment. - Available from 1950. - - **Heat stress daily**. - - **Heat stress weekly** (derived from daily dataset). - - **Heat stress monthly** (derived from daily dataset). - -- **Humidity (group)**: Relative humidity is the the amount of water vapour - present in air. Available from 1950. - - **Humidity daily**. - - **Humidity weekly** (derived from daily dataset). - - **Humidity monthly**. - -- **Precipitation (group)**: Accumulated water that falls to the surface. - Combines model data with observations from across the world. Two sources are - available: - - ERA5-Land. Available from 1950. - - **Precipitation daily**. - - **Precipitation weekly** (derived from daily dataset). - - **Precipitation monthly** *. - - CHIRPS. Available from 1981. - - **Precipitation daily**. - - **Precipitation weekly** (derived from daily dataset). + - ERA5-Land. Available from 1950. + - **Precipitation daily**. + - **Precipitation weekly** (derived from daily dataset). + - **Precipitation monthly** \*. + - CHIRPS. Available from 1981. + - **Precipitation daily**. + - **Precipitation weekly** (derived from daily dataset). - **Precipitation monthly** (derived from daily dataset). -- **Temperature (group)**: Temperature at 2m above the surface. Combines - model data with observations from across the world. Available from 1950. - - **Temperature daily**. - - **Temperature weekly** (derived from daily dataset). - - **Temperature monthly** *. +- **Temperature (group)**: Temperature at 2m above the surface. Combines model data with + observations from across the world. Available from 1950. + + - **Temperature daily**. + - **Temperature weekly** (derived from daily dataset). + - **Temperature monthly** \*. -- **Land cover** *: 17 distinct landcover types collected from satellites by - NASA. Available yearly, between 2001 and 2022. +- **Land cover** \*: 17 distinct landcover types collected from satellites by NASA. Available + yearly, between 2001 and 2022. -- **Vegetation**: Normalized difference vegetation index (NDVI) and - Enhanced Vegetation Index (EVI), used to quantify vegetation greenness. - Collected from satellites by NASA. Available at 16-day intervals, from 2000. - - **Vegetation 16-day** +- **Vegetation**: Normalized difference vegetation index (NDVI) and Enhanced Vegetation Index + (EVI), used to quantify vegetation greenness. Collected from satellites by NASA. Available at + 16-day intervals, from 2000. + - **Vegetation 16-day** - **Vegetation weekly** (derived from 16-day dataset). - **Vegetation monthly** (derived from 16-day dataset). ### Create an Earth Engine layer -To create an Earth Engine layer, choose the desired layer from the **Add -layer** selection. This opens the layer configuration dialog. +To create an Earth Engine layer, choose the desired layer from the **Add layer** selection. This +opens the layer configuration dialog. -1. In the **Data** tab: +#### 1. Data - ![](resources/images/maps_ee_layer_dialog_DATA.png) +![](resources/images/maps_ee_layer_dialog_DATA.png) - - Select dataset (if within a data group): - - For **Population** you can select either the **Population** or the - **Population age group** dataset. +- **Dataset** (if within a data group): - - Select data subset: - - For **Population age groups** you can select the age/gender - **groups** you would like to include when aggregating the data. - - For **Temperature** or **Heat stress** you can select the - **temporal aggregation method** you want to use (Mean, Min, Max). - - For **Vegetation** you can select the **index** you want to use - (NDVI or EVI). + - For **Population** you can select either the **Population** or the **Population age group** + dataset. - - Select the **spatial aggregation methods** you would like to use when - calculating values for the selected organisation units, this will only - affect results in popups and data table (some options might not be - available depending on the layer source). +- **Data subset**: - - **Sum**: Calculates the total number within each organisation unit. - Recommended to use for the population layers. + - For **Population age groups** you can select the age/gender **groups** you would like to + include when aggregating the data. + - For **Temperature** or **Heat stress** you can select the **temporal aggregation method** + you want to use (Mean, Min, Max). + - For **Vegetation** you can select the **index** you want to use (NDVI or EVI). - - **Min**: Returns the minimum value in the layer unit displayed - below the selection. For population layers it will be the minimum - _people per hectare_. For elevation layer it will return the lowest - elevation (meters above sea level). +- Select the **spatial aggregation methods** to use when calculating values for the selected org + units. This only affects results in popups and the data table (some options might not be + available depending on the layer source). - - **Max**: Returns the maximum value in the layer unit. For population - layers it will be the minimum _people per hectare_. For elevation - layer it will return the highest elevation for each organisation - unit. + - **Sum**: Calculates the total number within each org unit. Recommended to use for the + population layers. - - **Mean**: Returns the mean value in the layer unit. For population - layers it will be the mean _people per hectare_. For precipitation - layer it will be the mean rainfall in millimeters across the - organisation unit. + - **Min**: Returns the minimum value in the layer unit displayed below the selection. For + population layers it will be the minimum _people per hectare_. For the elevation layer it + will return the lowest elevation (meters above sea level). - - **Median**: Returns the median value in the layer unit. For - population layers it will be the median _people per hectare_. For - temperature layer it will be the median °C across the - organisation unit. + - **Max**: Returns the maximum value in the layer unit. For population layers it will be the + maximum _people per hectare_. For the elevation layer it will return the highest elevation + for each org unit. - - **Standard deviation**: Returns the standard deviation value in the - layer unit. + - **Mean**: Returns the mean value in the layer unit. For population layers it will be the + mean _people per hectare_. For the precipitation layer it will be the mean rainfall in + millimeters across the org unit. - - **Variance**: Returns the variance value in the layer unit. + - **Median**: Returns the median value in the layer unit. For population layers it will be the + median _people per hectare_. For the temperature layer it will be the median °C across the + org unit. - - **Special cases**: - - For "building footprints": **Count**: Returns the number of - buildings within each organisation unit. Note that building - counts are only available for smaller organisation unit areas. - - For "landcover": **Percentage**, **Hectare**, **Acres**: Return - the area covered by each landcover category within each - organisation in different units. + - **Standard deviation**: Returns the standard deviation value in the layer unit. -2. In the **Period** tab + - **Variance**: Returns the variance value in the layer unit. - ![](resources/images/maps_ee_layer_dialog_PERIOD.png) + - **Special cases**: + - For "building footprints": **Count**: Returns the number of buildings within each org + unit. Note that building counts are only available for smaller org unit areas. + - For "landcover": **Percentage**, **Hectare**, **Acres**: Return the area covered by each + landcover category within each org unit in different units. - - Select dataset (if within a period group): Select the period type if - you have multiple sources enabled for **Heat stress**, - **Precipitation**, **Temperature** or **Vegetation**. +#### 2. Period - - Select the period for the data source. The available periods are set by - layer source. Some sources are only available at a single - point in time. +![](resources/images/maps_ee_layer_dialog_PERIOD.png) -3. In the **Organisation Units** tab: +- Select the period type (if multiple sources are enabled for **Heat stress**, **Precipitation**, + **Temperature**, or **Vegetation**). - ![](resources/images/maps_ee_layer_dialog_ORG_UNITS.png) +- Select the period for the data source. The available periods are set by the layer source. Some + sources are only available at a single point in time. - - Select the organisation units you where you want to see aggregated data values. - It is possible to select either +#### 3. Org units - - One or more specific organisation units, organisation unit levels in - the hierarchy, organisation unit groups, or +![](resources/images/maps_ee_layer_dialog_ORG_UNITS.png) - - A relative level in the organisation unit hierarchy, with - respect to the user. By selecting a **User organisation - unit** the map data will appear differently for users at - different levels in the organisation unit hierarchy. +- Select the org units where you want to see aggregated data values. It is possible to select + either - - **Use associated geometry**: This dropdown will only show if there - are any additional geometry available for your organisation units. - This is typically used to calculate values for facility catchment areas. + - One or more specific org units, org unit levels in the hierarchy, org unit groups, or -4. In the **Style** tab + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. - ![](resources/images/maps_ee_layer_dialog_STYLE.png) +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to calculate values for facility catchment + areas. - - Modify the parameters specific to the layer type. +#### 4. Style - - Adjust the legend range, steps and colors, as desired. +![](resources/images/maps_ee_layer_dialog_STYLE.png) - - If you select organisation units having a single point coordinate - (facilities) you can set a radius buffer to calculate the - data value within. A radius of 5000 meters will aggregate all - values available within a 5 km distance from a facility. Buffer - option is not available if associated geometry is used. +- Adjust the legend **Min**, **Max**, number of **Classes**, and color map, as desired. -5. Click **Add layer**. +- **Buffer**: If you select org units with a single point coordinate (facilities), you can set a + radius buffer to calculate the data value within. A radius of 5000 meters will aggregate all + values available within a 5 km distance from a facility. Buffer option is not available if + associated geometry is used. -Click on the map regions or facilities to see the aggregation result for that -organisation unit. +- **Count org units without coordinates**: Org units without coordinates are counted and shown in + a **Data quality** section of the legend. They also appear in the data table. -### Listing of data values +Click **Add layer**. -Earth Engine layers have a **Show/hide data table** option that can be toggled on or -off from the layer card. +Click an org unit or facility on the map to see the aggregation result. -![](resources/images/maps_ee_layer_data_table.png) +### Modify an Earth Engine layer -The data table displays all the aggregated values for the organisation units selected. +1. In the layer panel, click the edit (pencil) icon on the Earth Engine layer card. -- Clicking on the up/down button will sort the table based on that column; - toggling between ascending and descending. +2. Modify the settings on the **Data**, **Period**, **Org units**, and **Style** tabs as desired. -- Entering text or expressions into the filter fields below the titles - will apply those filters to the data, and the display will adjust - according to the filter. The filters are applied as follows: +3. Click **Update layer**. - - NAME +### Filter values in an Earth Engine layer - filter by name containing the given text +Earth Engine layers have a **Show/hide data table** option that can be toggled on or off from the +layer card. - - ID +![](resources/images/maps_ee_layer_data_table.png) - filter by IDs containing the given text +The data table displays all the aggregated values for the selected org units. Click the arrow +buttons in a column header to sort by that column. Type in the filter fields below each column +header to filter the displayed rows. - - TYPE +There is one column for each selected aggregation type. These numeric columns support comparison +operators: `>`, `<`, `>=`, and `<=`, with `,` for OR and `&` for AND logic — for example: `2,>3&<8`. - filter by GIS display types containing the given text +> **Note** +> +> Data table filters are temporary and are not saved with the map. - - AGGREGATION VALUES ("Sum" and "Mean" in the example above) +### Open org unit profile - there is one column for each of the aggregation types selected - numeric data values can be filtered by given numbers, and/or ranges, for example: 2,\>3&\<8 +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: -> **Note** -> -> Data table filters are temporary and are not saved with the map layers. +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. +3. Click an org unit row in the **data table**. + +### Remove an Earth Engine layer + +To remove an Earth Engine layer from the map, in the layer card to the left, click the _more +actions_ (three dots) icon and then click **Remove layer**. ## Add external map layers { #using_maps_external_map_layers } ![](resources/images/maps_terrain_imagery.png) @@ -1457,18 +1145,17 @@ External map layers are represented as either basemaps or overlays. > > The [**Maps app administrator**](#maps_app_administrator) can add external map layers. -- Basemaps +- **Basemaps** - These are available in the **basemap** card in the layers panel and - are selected as any other basemap. + These are available in the **basemap** card in the layers panel and are selected as any other + basemap. -- Overlays +- **Overlays** - These are available in the **Add layer** selection. Unlike basemaps, - overlays can be placed above or below any other overlay layers. + These are available in the **Add layer** selection. Unlike basemaps, overlays can be placed + above or below any other overlay layers. -Overlay layers are represented by additional layer _cards_ in the layer -panel such as: +Overlay layers are represented by additional layer _cards_ in the layer panel. Along the top of the overlay card from left to right are: @@ -1476,7 +1163,7 @@ Along the top of the overlay card from left to right are: - The title of the external map layer -- An arrow symbol to collapse and expand the overlay card +- An arrow symbol to collapse or expand the overlay card In the middle of the card is a legend if the layer has one. @@ -1484,8 +1171,7 @@ Along the bottom of the overlay card from left to right are: - A slider for modifying the layer transparency -- A delete (trash can) icon to remove the layer from the current - thematic map. +- A delete icon to remove the layer from the current map ### GeoJSON external layers @@ -1493,61 +1179,57 @@ If you add a GeoJSON external layer to your map, you will have a few style choic ![](resources/images/maps_geojson_external_layer_style.png) -Once the GeoJSON layer has been displayed, you can view the data table +Once the GeoJSON layer is displayed, you can view its data table: ![](resources/images/maps_geojson_external_layer_data_table.png) -As with other layers, you can sort and filter the data. If you want to view the data for one row, click on the row to open the Feature Profile: +As with other layers, you can sort and filter the data. If you want to view the data for one row, +click the row to open the **Feature Profile**: ![](resources/images/maps_geojson_external_layer_feature_profile.png) - -## Organisation unit profile { #using_maps_org_unit_profile } +## Org unit profile { #using_maps_org_unit_profile } ![](resources/images/maps_org_unit_profile.png) -The organisation unit profile shows detailed information about -each organisation unit. You can open the profile from org unit, facility -and thematic layers. - -You can open the organisation unit profile in three ways: +The org unit profile shows detailed information about each org unit. You can open the profile from +org unit layers, facility layers, thematic layers, and Earth Engine layers. -1. Click on any of the organisasjon units shown on the map, and click - the **View profile** button in the popup. +You can open the org unit profile in three ways: -2. Right-click one of the organisation units on the map, and select **View profile** - from the menu. +1. Click an org unit on the map, then click the **View profile** button in the popup. -3. Click on an organisation unit row in the **data table**. +2. Right-click one of the org units on the map, and select **View profile** from the menu. -The profile will show on the right side of the map. The profile contents is -set by the system administrator. +3. Click an org unit row in the **data table**. +The profile will show on the right side of the map. The profile content is set by the system +administrator. ## File menu { #using_maps_file_menu } ![](resources/images/maps_file_menu.png) -Use the **File menu** to manage your maps. Several menu items will be -disabled until you open or save a map. +Use the **File menu** to manage your maps. Several menu items will be disabled until you open or +save a map. -Saving your maps makes it easy to restore them later. It also gives you -the opportunity to share them with other users as an interpretation or -put it on the dashboard. You can save all types of layer configurations -as a saved map. +Saving your maps makes it easy to restore them later. It also gives you the opportunity to share +them with other users as an interpretation or add them to a dashboard. You can save all types of +layer configurations as a saved map. ### Create a new map Click **File** \> **New**. -NB\! This will clear the current map layers you have without saving. +> **Note** +> +> This will discard the current map without saving. -### Open a new map +### Open a map 1. Click **File** \> **Open**. A dialog box opens with a list of maps. -2. Find the saved map you want to open. You can either use \< and \> or - the search field to find a saved map. The list is filtered on every - character that you enter. You can filter the list by selecting - **Show all**, **Created by me** or **Created by others**. +2. Find the saved map you want to open. You can either use \< and \> or the search field to find a + saved map. The list is filtered on every character that you enter. You can filter the list by + selecting **Show all**, **Created by me** or **Created by others**. 3. Click the name of the map you want to open. @@ -1557,8 +1239,7 @@ When you have created a map it is convenient to save it for later use: 1. Click **File** \> **Save**. -2. Enter a **Name** (required) and a **Description** (optional) the - first time you save a map. +2. Enter a **Name** (required) and a **Description** (optional) the first time you save a map. 3. Click **Save**. @@ -1566,8 +1247,7 @@ When you have created a map it is convenient to save it for later use: 1. Click **File** \> **Save as...** -2. Enter a **Name** (required) and a **Description** (optional) for the - map. +2. Enter a **Name** (required) and a **Description** (optional) for the map. 3. Click **Save**. @@ -1583,37 +1263,37 @@ When you have created a map it is convenient to save it for later use: 1. Click **File** \> **Translate**. -2. Select the **Locale** (language) your translation. +2. Select the **Locale** (language) for your translation. -3. Enter a translated **Name** and **Description**. The original text - will show below the field. +3. Enter a translated **Name** and **Description**. The original text will show below the field. 4. Click **Save**. ### Modify sharing settings for a map -After you have created a map and saved it, you can share the map with -everyone or a user group. To modify the sharing settings: +After you have created a map and saved it, you can share the map with everyone or a user group. To +modify the sharing settings: 1. Click **File** \> **Share**. The sharing settings dialog opens. -2. **Give access to a user or group**: In the text box, search for the name of the - user or group you want to share your saved map with and select it. +2. **Give access to a user or group**: In the text box, search for the name of the user or group + you want to share your saved map with and select it. - Select the access level and click on **Give access**. + Select the access level and click **Give access**. Repeat the step to add more users or groups. -3. **Users and groups that currently have access**: For each user or group, choose the - access level. The options are: +3. **Users and groups that currently have access**: For each user or group, choose the access + level. The options are: - - No access: The public won't have access to the map. This setting is only applicable to All users. + - **No access**: The public won't have access to the map. This setting is only applicable to + All users. - - View only + - **View only**: Users can view but not edit the map. - - View and edit + - **View and edit**: Users can view and edit the map. - - Remove access: Remove the access for groups or individuals. + - **Remove access**: Remove the access for groups or individuals. 4. Click **Close** to close the dialog. @@ -1627,15 +1307,13 @@ everyone or a user group. To modify the sharing settings: 1. Click **File** \> **Delete**. A confirmation dialog is displayed. -2. Click **DELETE** to confirm that you want to delete the saved map. - Your map is deleted and the layers are cleared from the view. - +2. Click **Delete** to confirm that you want to delete the saved map. Your map is deleted and the + layers are cleared from the view. ## Map interpretations and details { #mapsInterpretation } -An interpretation is a description of a map at a given period. This -information is also visible in the **Dashboard app**. Click -**Interpretations and details** in the top right of the workspace to open the -interpretations panel. The button is only clickable if the map is saved. +An interpretation is a description of a map for a given period. This information is also visible in +the **Dashboard app**. Click **Interpretations and details** in the top right of the workspace to +open the interpretations panel. The button is only available when the map has been saved. ![](resources/images/maps_interpretations_panel.png) @@ -1645,35 +1323,31 @@ To view interpretations for relative periods, such as a year ago: 1. Open a saved map with interpretations. -2. Click **Interpretations and details** in the top right of the workspace to open - the interpretations panel. +2. Click **Interpretations and details** in the top right of the workspace to open the + interpretations panel. -3. Click on **See interpretation**. Your map displays the data and the date - based on when the interpretation was created. To view other - interpretations, click them. +3. Click **See interpretation**. Your map displays the data and the date based on when the + interpretation was created. To view other interpretations, click them. ![](resources/images/maps_interpretations_modal.png) ### Write interpretation for a map -To create an interpretation, you first need to create a map and save it. -If you've shared your map with other people, the interpretation you -write is visible to those people. +To create an interpretation, you first need to create a map and save it. If you've shared your map +with other people, the interpretation you write is visible to those people. 1. Open a saved map. -2. Click **Interpretations and details** in the top right of the workspace to open - the interpretations panel. +2. Click **Interpretations and details** in the top right of the workspace to open the + interpretations panel. -3. A text field will appear with a placeholder "Write an interpretation" for users - that have read access to the saved map. +3. A text field appears where you can write an interpretation. -4. In the text field, type a comment, question or interpretation. You - can also mention other users with '@username'. Start by typing '@' - plus the first letters of the username or real name and a mentioning - bar will display the available users. Mentioned users will receive - an internal DHIS2 message with the interpretation or comment. You - can see the interpretation in the **Dashboard app**. +4. In the text field, type a comment, question or interpretation. You can also mention other users + with '@username'. Start by typing '@' followed by the first letters of the username or real + name, and a list of matching users will appear. Mentioned users will receive an internal DHIS2 + message with the interpretation or comment. You can see the interpretation in the **Dashboard + app**. 5. Click **Post interpretation** to save the interpretation. @@ -1681,106 +1355,114 @@ write is visible to those people. 1. Click an interpretation (see how to view an interpretation above). -2. Click the share icon below the interpretation. The sharing settings - dialog opens. +2. Click the share icon below the interpretation. The sharing settings dialog opens. -3. Search for and add a users and user groups that you want to share - your map with, and set the access level. Click on **Give access**. +3. Search for and add users and user groups that you want to share your map with, and set the + access level. Click **Give access**. 4. Change the access level for the users you want to modify: - - **View and edit**: Everyone can view and edit the object. + - **No access**: The public won't have access to the map. This setting is only applicable to + All users. - - **View only**: Everyone can view the object. + - **View only**: Users can view but not edit the map. - - **No access**: The public won't have access to the object. This - setting is only applicable to All users. + - **View and edit**: Users can view and edit the map. - **Remove access**: Remove the access for groups or individuals. 5. Click **Close** when sharing settings are updated. ![](resources/images/maps_interpretations_sharing.png) - ## Save a map as an image { #using_maps_image_export } -You can download your map as an image by clicking on the Download button in the top menu +You can download your map as an image by clicking the **Download** button in the top menu. ![](resources/images/maps_download.png) -You will enter a "download mode" where you can adjust the map layout before you -download the image. The left column gives you the following options: - -- **Show map name**: Select if you want to include the map name or not. This option - is only available if the map is saved. To change the name, exit download mode and - select _File_ > _Rename_. -- **Show map description**: Select if you want to include the map description or not. - This option is only available if a map description was added when the map was saved. - To change the map description, exit download mode and select _File_ > _Rename_. -- **Show legend**: Select if you want to include the map legend. If the map includes - more than one layer, you can select the visibility for each legend. -- **Show overview map**: Select if you want to include an overview map (often named - inset map). This option will be disabled if there is not enough room for it in the - right column. -- **Show north arrow**: Select to include a north arrow on the map. The default - position is the lower right corner of the map, but you can change it to another - corner. -- Click **Download** to download your map. - -Resize your browser window to change the map dimensions. You can also reposition -both the main map and the overview map. - -Map download is not supported in Internet Explorer or Safari. We recommend using Google Chrome or Firefox. - +You will enter **Download mode** where you can adjust the map layout before you download the image. +The left column gives you the following options: + +- **Show map name**: Select if you want to include the map name or not. This option is only + available if the map is saved. To change the name, exit download mode and select **File** \> + **Rename**. +- **Show map description**: Select if you want to include the map description or not. This option + is only available if a map description was added when the map was saved. To change the map + description, exit download mode and select **File** \> **Rename**. +- **Show legend**: Select if you want to include the map legend. If the map includes more than one + layer, you can select the visibility for each legend. +- **Show overview map**: Select if you want to include an overview map (often named inset map). + This option will be disabled if there is not enough room for it in the right column. +- **Show north arrow**: Select to include a north arrow on the map. The default position is the + lower right corner of the map, but you can change it to another corner. + +Click **Download** to download your map. + +Resize your browser window to change the map dimensions. You can also reposition both the main map +and the overview map. ## Search for a location { #using_maps_search } -The place search function allows you to search for almost any location -or address. This function is useful in order to locate for example -sites, facilities, villages or towns on the map. +The place search function allows you to search for almost any location or address. This is useful to +locate sites, facilities, villages or towns on the map. ![](resources/images/maps_place_search.png) 1. On the right side of the Maps window, click the magnifier icon. -2. Type the location you're looking. +2. Type the location you're looking for. A list of matching locations appear as you type. -3. From the list, select a location. A pin indicates the location on - the map. - +3. From the list, select a location. A pin indicates the location on the map. ## Measure distances and areas in a map { #using_maps_measure_distance } -1. In the upper left part of the map, put the cursor on the **Measure - distances and areas** (ruler) icon and click **Create new - measurement**. +1. In the upper left part of the map, put the cursor on the **Measure distances and areas** (ruler) + icon and click **Create new measurement**. 2. Add points to the map. 3. Click **Finish measurement**. ![](resources/images/maps_measure_distance.png) - ## Get the latitude and longitude at any location { #using_maps_latitude_longitude } -Right-click a point on the map and select **Show longitude/latitude**. -The values display in a pop-up window. - +Right-click a point on the map and select **Show longitude/latitude**. The values are displayed in a +popup window. ## Maps app administrator { #maps_app_administrator } -A **Maps** app administrator can be defined by the system administrator assigning the `F_EXTERNAL_MAP_LAYER_PUBLIC_ADD` authority. +A **Maps** app administrator can be defined by the system administrator assigning the +`F_EXTERNAL_MAP_LAYER_PUBLIC_ADD` authority. The **Maps** app administrator is able to: -- Select the sources for Google Earth Engine layers available to other users via the Manage available layer sources button. +- Select the sources for Google Earth Engine layers available to other users via the **Manage + available layer sources** button. ![](resources/images/maps_admin_managesources_button.png) - Add new external layer sources via the Maintenance app. ![](resources/images/maps_admin_externallayer.png) - ## See also -- [Manage - legends](https://docs.dhis2.org/master/en/user/html/manage_legend.html) +- Configuration: + + - [Configure DHIS2 Maps](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/maps.html) + - [Accessing map layers from Google Earth Engine](https://docs.dhis2.org/en/topics/tutorials/google-earth-engine-sign-up.html#accessing-map-layers-from-google-earth-engine) + - [Geo-enabled microplanning](https://docs.dhis2.org/en/implement/health/immunization/immunization-campaigns/use.html?h=microplanning#geoenabled-microplanning), + including details about facility catchment areas + +- Settings: + + - [Infrastructural indicators / Infrastructural data elements / Infrastructural period type](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=Infrastructural%20indicators) + - [Use centroids for organisation unit polygons in event analytics / Org unit group set in facility map layers / Org unit level in facility map layers / Default basemap](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=Use%20centroids%20for%20organisation%20unit%20polygons%20in%20event%20analytics) + - [Google Maps / Bing / Azure API keys](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API) + +- Metadata management: + + - [Manage legends](https://docs.dhis2.org/master/en/user/html/manage_legend.html) + - [Aggregation operators](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/metadata.html#create_data_element:~:text=Aggregation%20operators) + +- Training: + - [Trainer's Guide to Maps](https://docs.dhis2.org/en/topics/training-docs/analytics-tools-academy/maps/traineraposs-guide-to-maps.html) + - [Learner's Guide to Maps](https://docs.dhis2.org/en/topics/training-docs/analytics-tools-academy/maps/learneraposs-guide-to-maps.html) diff --git a/docs/resources/images/maps_ee_layer_dialog_DATA.png b/docs/resources/images/maps_ee_layer_dialog_DATA.png index a7b0eae65..b27cf556b 100644 Binary files a/docs/resources/images/maps_ee_layer_dialog_DATA.png and b/docs/resources/images/maps_ee_layer_dialog_DATA.png differ diff --git a/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png index fc477d7d4..a91d7b780 100644 Binary files a/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png and b/docs/resources/images/maps_ee_layer_dialog_ORG_UNITS.png differ diff --git a/docs/resources/images/maps_ee_layer_dialog_PERIOD.png b/docs/resources/images/maps_ee_layer_dialog_PERIOD.png index 44133bda5..aa968fed0 100644 Binary files a/docs/resources/images/maps_ee_layer_dialog_PERIOD.png and b/docs/resources/images/maps_ee_layer_dialog_PERIOD.png differ diff --git a/docs/resources/images/maps_ee_layer_dialog_STYLE.png b/docs/resources/images/maps_ee_layer_dialog_STYLE.png index e2ddaec26..157faf799 100644 Binary files a/docs/resources/images/maps_ee_layer_dialog_STYLE.png and b/docs/resources/images/maps_ee_layer_dialog_STYLE.png differ diff --git a/docs/resources/images/maps_event_layer_dialog_DATA.png b/docs/resources/images/maps_event_layer_dialog_DATA.png index adcbf11c8..413ecef31 100644 Binary files a/docs/resources/images/maps_event_layer_dialog_DATA.png and b/docs/resources/images/maps_event_layer_dialog_DATA.png differ diff --git a/docs/resources/images/maps_event_layer_dialog_FILTER.png b/docs/resources/images/maps_event_layer_dialog_FILTER.png index 43e2584c5..c10f2fbf0 100644 Binary files a/docs/resources/images/maps_event_layer_dialog_FILTER.png and b/docs/resources/images/maps_event_layer_dialog_FILTER.png differ diff --git a/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png index 70df86d59..ab4357547 100644 Binary files a/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png and b/docs/resources/images/maps_event_layer_dialog_ORG_UNITS.png differ diff --git a/docs/resources/images/maps_event_layer_dialog_PERIOD.png b/docs/resources/images/maps_event_layer_dialog_PERIOD.png index 5e7c5cc7c..0bf2c9138 100644 Binary files a/docs/resources/images/maps_event_layer_dialog_PERIOD.png and b/docs/resources/images/maps_event_layer_dialog_PERIOD.png differ diff --git a/docs/resources/images/maps_event_layer_dialog_STYLE.png b/docs/resources/images/maps_event_layer_dialog_STYLE.png index c4e676182..0b0d29fab 100644 Binary files a/docs/resources/images/maps_event_layer_dialog_STYLE.png and b/docs/resources/images/maps_event_layer_dialog_STYLE.png differ diff --git a/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png index d54361496..cd84a942f 100644 Binary files a/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png and b/docs/resources/images/maps_facility_layer_dialog_ORG_UNITS.png differ diff --git a/docs/resources/images/maps_facility_layer_dialog_STYLE.png b/docs/resources/images/maps_facility_layer_dialog_STYLE.png index 01b743892..4b974a2a2 100644 Binary files a/docs/resources/images/maps_facility_layer_dialog_STYLE.png and b/docs/resources/images/maps_facility_layer_dialog_STYLE.png differ diff --git a/docs/resources/images/maps_geojson_external_layer_style.png b/docs/resources/images/maps_geojson_external_layer_style.png index 5c7ab619b..c42d6629d 100644 Binary files a/docs/resources/images/maps_geojson_external_layer_style.png and b/docs/resources/images/maps_geojson_external_layer_style.png differ diff --git a/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png index f3fd40bd8..4f4fc1669 100644 Binary files a/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png and b/docs/resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png differ diff --git a/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png b/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png index f3b540d14..7e1b088b1 100644 Binary files a/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png and b/docs/resources/images/maps_org_unit_layer_dialog_STYLE.png differ diff --git a/docs/resources/images/maps_thematic_layer_dialog_STYLE.png b/docs/resources/images/maps_thematic_layer_dialog_STYLE.png index a4c7e0dc2..c7276f640 100644 Binary files a/docs/resources/images/maps_thematic_layer_dialog_STYLE.png and b/docs/resources/images/maps_thematic_layer_dialog_STYLE.png differ diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png b/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png index 87855a803..d3f9ba5e4 100644 Binary files a/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png and b/docs/resources/images/maps_tracked_entity_layer_dialog_DATA.png differ diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png b/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png index 74dc10794..da67c8d66 100644 Binary files a/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png and b/docs/resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png differ diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png b/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png index fcf8fff16..95054224a 100644 Binary files a/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png and b/docs/resources/images/maps_tracked_entity_layer_dialog_PERIOD.png differ diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png b/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png index e0dd54038..435692586 100644 Binary files a/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png and b/docs/resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png differ diff --git a/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png b/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png index bfe07effb..7b41880af 100644 Binary files a/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png and b/docs/resources/images/maps_tracked_entity_layer_dialog_STYLE.png differ diff --git a/docs/src/00-header.md b/docs/src/00-header.md new file mode 100644 index 000000000..45092e9bd --- /dev/null +++ b/docs/src/00-header.md @@ -0,0 +1 @@ +# Using the Maps app { #using_maps } diff --git a/docs/src/01-about.md b/docs/src/01-about.md new file mode 100644 index 000000000..d7b0a4f26 --- /dev/null +++ b/docs/src/01-about.md @@ -0,0 +1,84 @@ +## About the Maps app { #about_maps } + +The Maps app was introduced in release 2.29 as a replacement for the original GIS app, offering a +more intuitive and user-friendly interface. Since version 2.34, the mapping engine is based on WebGL +technology, capable of showing thousands of features on a map simultaneously. + +> **Note** +> +> The Maps app requires WebGL. Visit [get.webgl.org](https://get.webgl.org) to verify that WebGL is +> working in your browser or to troubleshoot display issues. + +With the Maps app, you can overlay multiple layers and choose from different basemaps. Supported +layer types include thematic maps, events, tracked entities, facilities, org unit boundaries, and +Earth Engine data such as population, elevation, or climate indicators. You can label features, +search and filter data, and save or share maps with other users, or download them as an image. Saved +maps can be added to dashboards in the **Dashboard** app. Thematic layers also integrate with the +**Data Visualizer** app, letting you open the same data as a chart. + +> **Note** +> +> To use predefined legends in the **Maps** app, you need to create them first in the +> **Maintenance** app. + +![](../resources/images/maps_main.png) + +### Layers panel + +The **layer panel** on the left side of the workspace shows an overview of the layers for the +current map: + +- As layers are added, using the **(+) Add layer** button, they are arranged and managed in this + panel. + +- The **basemap** card is always shown at the bottom of the panel. See + [Basemaps](#using_maps_basemaps) for available options. + +- The small arrow button to the right of the layer panel, at the top, allows the panel to be + hidden or shown. + +Each layer is represented by a card in the panel. Along the top of the card are a grab handle for +reordering layers with the mouse, the layer title, and an arrow to collapse or expand the card. The +middle of the card shows the layer legend where applicable. Along the bottom of the card from left +to right are: + +- An edit (pencil) button opens the layer configuration dialog. + +- An eye symbol toggles the visibility of the layer. + +- A slider modifies the layer transparency. + +- A more actions (three dots) button provides additional options, including showing or hiding the + data table, downloading the layer data, and removing the layer. + +### Map controls + +- The **+** and **-** buttons on the map allow you to zoom in and out of the map respectively. The + mouse scroll wheel zoom is continuous, allowing you to fit the map perfectly to your content. + +- The **rotate map** button (triangle arrows) allows you to rotate and tilt the map to enhance the + view of your data. Press and hold the button (or hold the Control key on your keyboard) while + moving your mouse to change the map view. Click the button again to reset the view. + +- **Fullscreen** (four arrows) allows you to view the map in fullscreen. To exit fullscreen, click + the button again or press the escape key on your keyboard. + +- **Zoom to content** (bounded magnifying glass symbol) automatically adjusts the zoom level and + map center position to put the data on your map in focus. + +- **Search** (magnifying glass symbol) allows searching for and jumping to a location on the map. + +- The **ruler** button allows you to measure distances and areas on the map. + +- Right-click on the map to display the longitude and latitude of that location. + +### File menu + +- The **File** button near the top left allows you to open and save maps. See + [using the maps file menu](#using_maps_file_menu) for more detailed information. + +- The **Download** button next to the File button allows you to download the current map as a PNG + image. + +- The **Interpretations** button at top right opens an interpretations panel on the right side of + the workspace. See [viewing interpretations](#mapsInterpretation) for more information. diff --git a/docs/src/02-create-map.md b/docs/src/02-create-map.md new file mode 100644 index 000000000..264d959c2 --- /dev/null +++ b/docs/src/02-create-map.md @@ -0,0 +1,35 @@ +## Create a new map { #using_maps_create_map } + +When you open the Maps app, you start with an empty map canvas and the default basemap selected. If +a map is already open, start a new one using **File** > **New**. You can change the basemap at any +time from the basemap card in the layer panel (see [Basemaps](#using_maps_basemaps)). + +To add a layer, click the **(+) Add layer** button in the top left. The layer selection dialog +opens: + +![](../resources/images/maps_layer_selection.png) + +Available layer types are: + +- [**Thematic**](#using_maps_thematic_layer): Visualize data values (indicators or data elements) + aggregated by org unit. +- [**Events**](#using_maps_event_layer): Display individual events from event or tracker programs. +- [**Tracked entities**](#using_maps_tracked_entity_layer): Display tracked entities and their + relationships on the map. +- [**Facilities**](#using_maps_facility_layer): Display facilities as icons based on their + coordinates. +- [**Org units**](#using_maps_org_unit_layer): Display org unit boundaries. + +In addition, several layers may be provided by [Google Earth Engine](#using_maps_gee) (such as +population, elevation, or climate indicators) and +[other external services](#using_maps_external_map_layers). Various Google Earth Engine layer +sources are available if the Google Earth Engine API key has been set up (see +[documentation](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API)). + +> **Note** +> +> The [**Maps app administrator**](#maps_app_administrator) can: +> +> - Select the sources for Google Earth Engine layers available to other users via the **Manage +> available layer sources** button. +> - Add external layer sources in the Maintenance app. diff --git a/docs/src/03-basemaps.md b/docs/src/03-basemaps.md new file mode 100644 index 000000000..a1cea92ab --- /dev/null +++ b/docs/src/03-basemaps.md @@ -0,0 +1,36 @@ +## Basemaps { #using_maps_basemaps } + +A basemap provides the background map on which your data layers are displayed. You can select and +configure the basemap from the **basemap** card at the bottom of the layer panel. + +The following basemaps are available by default: + +- **OSM Light**: A minimal, light-colored map based on OpenStreetMap data. This is the default + basemap. +- **OSM Detailed**: Contains more map features and place names. +- **Sentinel-2 EOX**: Cloud-free satellite imagery showing natural-color views of the Earth's + surface at 10m resolution. + +If a Bing Maps or Azure Maps API key has been configured by a system administrator, four additional +basemaps become available from each provider. Both providers offer the same four styles, prefixed +with the provider name — for example, **Bing Road** and **Azure Road**: + +- **Road**: Shows roads, borders and places. +- **Dark**: A dark-themed road map. Useful when the colors on your data layers are bright. +- **Aerial**: Satellite and detailed aerial imagery. +- **Aerial Labels**: Aerial imagery with place name labels. + +A [**Maps app administrator**](#maps_app_administrator) can also add external basemaps via the +Maintenance app. These appear in the basemap card alongside the default basemaps. + +Basemap layers are represented by a card in the layer panel. The card shows the list of available +basemaps with the current one highlighted. Controls at the bottom allow you to toggle the basemap +visibility and adjust its transparency. + +![](../resources/images/maps_basemap_card.png) + +> **Note** +> +> Bing Maps is being retired. See the [Bing Maps Blog](https://aka.ms/BMERetirementAnnouncement) for +> the retirement announcement. For migration to Azure Maps, consult the +> [Bing Maps Migration Overview](https://learn.microsoft.com/azure/azure-maps/migrate-bing-maps-overview). diff --git a/docs/src/04-thematic-layer.md b/docs/src/04-thematic-layer.md new file mode 100644 index 000000000..442c1dd35 --- /dev/null +++ b/docs/src/04-thematic-layer.md @@ -0,0 +1,237 @@ +## Manage thematic layers { #using_maps_thematic_layer } + +_Thematic maps_ represent spatial variation of geographic distributions. They display aggregated +data values for a selected data item (such as an indicator or data element), period and org unit +level. Org units with coordinates and matching data values will appear on the map. + +> **Note** +> +> You must generate the DHIS2 analytics tables to have aggregated data values available. + +![](../resources/images/maps_thematic_mapping.png) + +Thematic layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the value ranges displayed on the layer. The more actions (three dots) button +includes options to show or hide the data table, download the data, and open the data as a chart in +the Data Visualizer app via **Open as chart**. + +### Create a thematic layer + +To create a thematic layer, choose **Thematic** on the **Add layer** selection. This opens the +Thematic layer configuration dialog. + +#### 1. Data + +![](../resources/images/maps_thematic_layer_dialog_DATA.png) + +- Select a data item. + +- Select a value from the **Aggregation type** field for the data values to be shown on the map. + By default, "By data element" is selected. Alternative values are: Count, Average, Sum, Standard + deviation, Variance, Min, Max. See also + [Aggregation operators](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/metadata.html#create_data_element:~:text=Aggregation%20operators). + +- **Only show completed events**: Includes only completed events in the aggregation process. This + is useful when you want to exclude partial events in indicator calculations. Available for + indicators, program indicators and event data items. + +#### 2. Period + +![](../resources/images/maps_thematic_layer_dialog_PERIOD.png) + +Select the time span over which the thematic data is mapped. + +- **Period display mode**: Select how the selected periods will be visualized on the map: + + - _Single_ (default): Displays all selected periods as a single combined layer with aggregated + data. Required when only one period is selected or when using start–end dates. + + - _Timeline_: Displays multiple periods as an interactive timeline ordered chronologically. + Multiple timeline layers can be added to a map (they will all share the same periods). + + - _Split_: Displays multiple periods side by side for comparison. Supports up to 12 periods + (including multi-period presets) and can only be combined with other split layers (they will + all share the same periods). + +- After selecting a display mode, choose how to define the periods: + + - **Choose from presets**: Available for all display modes. You can combine one or more + relative and fixed periods. + + - _Relative period_: Select **Relative periods**, then the **Period type** (**Years**, + **Months**, etc.) and choose one or more relative periods, such as **This year** and + **Last year** or **Last 12 months**. A **default relative period for analysis** can be + set in the **System Settings** app. + + - _Fixed period_: Select **Fixed periods**, then choose the **Period type** (**Yearly**, + **Monthly**, etc.) and choose one or more fixed periods, such as **2024** or **January + 2025** and **February 2025**. + + - **Define start–end dates**: Available only when the Single display mode is selected. Specify + exact start and end dates. Both dates are inclusive and will be reflected in the outputs. + +#### 3. Org units + +![](../resources/images/maps_thematic_layer_dialog_ORG_UNITS.png) + +- Select the org units you want to include in the layer. It is possible to select either + + - One or more specific org units, org unit levels in the hierarchy, org unit groups, or + + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. + +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. + +#### 4. Filter + +![](../resources/images/maps_thematic_layer_dialog_FILTER.png) + +- Click **Add filter** and select an available data item to add a new filter to the data set. + + - Select a data dimension from the dropdown box. You can reduce the number of dimensions shown + by using the search field. Click the name to select a dimension. + + - When a dimension is selected you get a second dropdown with dimension items. Check the items + you want to include in the filter. + + Multiple filters may be added. Click the trash button on the right of the filter to remove it. + +#### 5. Style { #using_maps_thematic_layer_style } + +![](../resources/images/maps_thematic_layer_dialog_STYLE.png) + +- Select either **Choropleth** or **Bubble map**. + + - A choropleth map assigns a color to each org unit shape according to the data value. This is + the recommended technique if the data is normalized (per capita). + + - A bubble map shows data values as proportional circles. Use this technique if the data is + not normalized (absolute numbers). The circles are placed in the center of each org unit. + Set the **Low radius** and **High radius** for the proportional circles. The circles will be + scaled between low and high radius according to the data value. The radius must be between 0 + and 50 pixels. + +- **Show labels**: Show org unit names and/or values on the layer. Select **Name**, **Name and + value**, or **Value**. Font size, weight, style and color can also be modified. + +- **Count org units without coordinates**: Org units without map coordinates are counted and shown + in a **Data quality** section of the legend. They also appear in the data table. These org units + may or may not have data. + +- Select the legend type: + + - **Automatic color legend**: A legend is automatically created based on the classification + method, number of classes and color scale you select. Set **Classification** to one of: + + - _Equal intervals_: Divides the value range into equally-sized intervals, each spanning + (highest value − lowest value) ÷ number of classes. + - _Equal counts_: Org units are distributed as evenly as possible across classes (also + known as quantile classification). Some datasets cannot be evenly partitioned, + particularly when values are heavily repeated or the number of distinct values is small. + - _Natural breaks (intervals)_ and _Natural breaks (clusters)_: Class boundaries are + placed at the largest gaps in the data distribution, based on the + [ckmeans](https://simple-statistics.github.io/docs/#ckmeans) algorithm. Both methods + group values similarly; _intervals_ produces contiguous class ranges, while _clusters_ + may leave gaps between classes where no values fall. + - _Pretty breaks_: Break points are rounded to clean, human-readable numbers. Based on R's + [pretty](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/pretty) + algorithm. + - _Logarithmic scale_: Uses a logarithmic scale. Values must be positive; zero or negative + values are left unclassified. + - _Standard deviation_: Classes are defined as multiples of standard deviations from the + mean. The number of standard deviations per class depends on the number of classes + chosen; values further from the mean are left unclassified. + + **Decimal places**: Number of decimal places shown in legend labels. **Auto** lets the app + decide based on the data range, or choose a fixed value from **0** to **6** (also available + for single color legends). + + **Isolated class**: Define a value range (min–max) with a fixed color and optional label. + Org units in that range are shown separately and excluded from automatic classification. + + - **Predefined color legend**: Select from the predefined legends. + + - **Single color legend**: Select the color of the bubbles or circles. Only available for + bubble maps. + +- **Include unclassified org units**: Org units whose values fall outside all classification + ranges are shown with a configurable color and label (default: "Unclassified"). + +- **Include org units with no data**: Org units with no data value are shown with a configurable + color and label (default: "No data"). + +> **Note**: All legend items and their counts - including **No data** and **Unclassified** - only +> include org units with coordinates. + +> **Note** +> +> Most classes use half-open intervals (`startValue ≤ value < endValue`): a value sitting exactly on +> a boundary belongs to the upper class, not the one whose label ends there. The exceptions - where +> the upper bound is inclusive - are the last class, isolated classes, single-value classes, and +> clusters (natural breaks). +> +> If the exact class a boundary value belongs to matters for your analysis, use **Show labels** to +> overlay values directly on each feature. If it still matters after that, consider whether a +> different legend, maybe with more classes or higher decimal precision, is the right tool for the +> decision you are trying to make. + +Click **Add layer**. + +### Modify a thematic layer + +1. In the layer panel, click the edit (pencil) icon on the thematic layer card. + +2. Modify the settings on any of the tabs as desired. + +3. Click **Update layer**. + +### Filter values in a thematic layer + +Thematic layers have a **Show/hide data table** option that can be toggled on or off from the +thematic layer card. + +![](../resources/images/maps_thematic_layer_data_table.png) + +The data table displays the data associated with the thematic layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. + +The name filter field is an effective way to search for individual org units. + +For numeric columns, you can filter using comparison operators: `>`, `<`, `>=`, and `<=`. Use `,` +for OR logic and `&` for AND logic — for example: `2,>3&<8` matches the value 2 or any value greater +than 3 and less than 8. + +> **Note** +> +> Data table filters are temporary and are not saved with the map. + +### Open org unit profile + +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: + +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. + +3. Click an org unit row in the **data table**. + +### Navigate between org unit hierarchies + +When there are visible org units on the map, you can easily navigate up and down in the hierarchy +without changing the org unit selection. + +1. Right-click one of the org units. + +2. Select **Drill up one level** or **Drill down one level**. + + The drill down option is disabled if you are on the lowest level or if there are no coordinates + available on the level below. Likewise, the drill up option is disabled from the highest level. + +### Remove a thematic layer + +To remove a thematic layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. diff --git a/docs/src/05-event-layer.md b/docs/src/05-event-layer.md new file mode 100644 index 000000000..0e6d75f46 --- /dev/null +++ b/docs/src/05-event-layer.md @@ -0,0 +1,214 @@ +## Manage event layers { #using_maps_event_layer } + +The event layer displays the geographical location of events recorded in DHIS2 programs. When events +have associated point or polygon coordinates, you can drill down from aggregated data in thematic +layers to the underlying individual events or cases. Alternative coordinate fields also let you plot +events using locations other than the event itself, such as the org unit or enrollment location. + +To display aggregated event statistics at the org unit level, use a thematic layer with event data +items instead. + +![](../resources/images/maps_event_layer.png) + +Event layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the styling of the layer. The more actions (three dots) button includes options to +show or hide the data table and to download the data in GeoJSON format. + +### Create an event layer { #maps_create_event_layer } + +To create an event layer, choose **Events** on the **Add layer** selection. This opens the Events +layer configuration dialog. + +#### 1. Data + +![](../resources/images/maps_event_layer_dialog_DATA.png) + +- Select a program and then select a program stage. The **Stage** field is only shown once a + program is selected. + + If there is only one stage available for the selected program, the stage is automatically + selected. + +- Select a value from the **Coordinate field** to determine which positions are displayed on the + map. By default, "Event location" is selected. You can also choose "Org unit location". + Depending on the selected program, additional options may include "Tracked entity location", + "Enrollment location", and coordinate or org unit type data elements or attributes, such as + "Household location" or "Referral facility". The number of events represented on the map may + vary depending on the selected option and the availability of coordinates. Org units are + represented by their centroids. + +- By default, all events with coordinates are shown on the map. Use the **Event status** field to + only show events having one status: Active, Completed, Schedule, Overdue, or Skipped. + +#### 2. Period + +![](../resources/images/maps_event_layer_dialog_PERIOD.png) + +- Select the time span for when the events took place. You can select either a fixed period or a + relative period. + + - _Relative period_: Select one of the relative periods, for example **This month** or **Last + year**. A **default relative period for analysis** can be set in the **System Settings** + app. + + - _Fixed period_: Select **Start/end dates** and fill in a start date and an end date. + +#### 3. Org units + +![](../resources/images/maps_event_layer_dialog_ORG_UNITS.png) + +- Select the org units you want to include in the layer. It is possible to select either + + - One or more specific org units, or + + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. + +#### 4. Filter + +![](../resources/images/maps_event_layer_dialog_FILTER.png) + +- Click **Add filter** and select an available data item to add a new filter to the data set. + + - For data item of type _option set_, you can select any of the options from the dropdown box, + or type to filter. + + - For data item of type _number_, you can select operators like equal, not equal, greater than + or less than. + + - For data item of type _boolean_ (yes/no), you can check the box if the condition should be + true. + + - For data item of type _text_, select **Contains** (matches any value containing the search + text) or **Is exact** (matches only identical values). + + Multiple filters may be added. Click the trash button on the right of the filter to remove it. + +#### 5. Style + +![](../resources/images/maps_event_layer_dialog_STYLE.png) + +- Select **Group events** to group nearby events (cluster), or **View all events** to display + events individually. + + - Select a **color** and **radius** (between 1 and 20) for the event or cluster points. + + - Select **Show buffer** to display a visual buffer around each event. The radius of the + buffer can be modified here. Only available when **View all events** is selected. + +- **Count events without coordinates**: Events without coordinates are counted and shown in a + **Data quality** section of the legend. They also appear in the data table. These events may or + may not have data. + +- Select **Style by data item** (data element or attribute) to colorize the events according to a + data value. If events are grouped, clusters are displayed as small donut charts showing the + distribution of the data values. The available options vary for different data types: + + - **Option sets**: Select a color for each option in an option set. You can set default colors + for an option in the Maintenance app. + + - **Numbers**: You can style a numeric data item in + [the same way as thematic layers](#using_maps_thematic_layer_style) using automatic or + predefined legends. + + - **Booleans**: Select a color for true/yes and another for false/no. + + **Include unclassified events**: Events whose values fall outside all classification ranges are + shown with a configurable color and label (default: "Unclassified"). + + **Include events with no data**: Events with no data value are shown with a configurable color + and label (default: "No data"). + +> **Note**: All legend items and their counts - including **No data** and **Unclassified** - only +> include events with coordinates. + +Click **Add layer**. + +### Modify an event layer + +1. In the layer panel, click the edit (pencil) icon on the event layer card. + +2. Modify the settings on the **Data**, **Period**, **Filter**, **Org units** and **Style** tabs as + desired. + +3. Click **Update layer**. + +### Filter events + +Event layers have a **Show/hide data table** option that can be toggled on or off from the event +layer card. + +![](../resources/images/maps_event_layer_data_table.png) + +The data table displays the data associated with the event layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. + +Additional columns appear for data elements configured to display in reports, and for any data item +used to style the events — both the data value and the color can be filtered in those columns. +Numeric columns support comparison operators: `>`, `<`, `>=`, and `<=`, with `,` for OR and `&` for +AND logic — for example: `2,>3&<8`. + +> **Note** +> +> Data table filters are temporary and are not saved with the map. + +### Modify information in event data table and popups + +If you have access to the selected program in the Maintenance app, you can modify the information +displayed in the event popup window. + +![](../resources/images/maps_eventlayer_eventinfopopup.png) + +1. Open the **Maintenance** app. + +2. Select **Program**. + +3. Click the program you want to modify and select **(2) Assign data elements**. + +4. For every data element you want to display in the popup window, select corresponding **Display + in reports**. + +5. Click **Save**. + +### Download raw event layer data + +The raw data for event layers can be downloaded in GeoJSON format for more advanced geo-analytics +and processing in desktop GIS software such as [QGIS](https://www.qgis.org/). The downloaded data +includes all individual events as GeoJSON features, including attributes for each data element +selected for **Display in reports**. + +![](../resources/images/maps_data_download_dialog.png) + +- In the layer card to the left, click the _more actions_ (three dots) icon and then click + **Download data**. + +- Select the **ID format** to use as the key for data element values in the downloaded GeoJSON + file: + + - **ID**: Use the unique ID of the data element. + - **Name**: Use the human-friendly name of the data element (translated). + - **Code**: Use the code of the data element. + +- Select whether or not to **Use human-readable keys** for other event attributes, such as Program + Stage, Latitude, Longitude, Event Data, and Org Unit ID, Name, and Code. When this option is + **not** selected, these values will be computer-friendly IDs instead of human-readable + (translated) names. + +- Click the **Download** button to generate and download a GeoJSON file. The data will be + requested from the DHIS2 server and processed by the maps application. This operation may take + several minutes to complete. + +- Once the GeoJSON file has been downloaded, it can be imported into most standard GIS software. + +> **Note** +> +> The downloaded data does not include style information as it is not natively supported by the +> GeoJSON format. Styles can optionally be recreated in external GIS applications using the +> attributes of each feature. + +### Remove an event layer + +To remove an event layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. diff --git a/docs/src/06-tracked-entity-layer.md b/docs/src/06-tracked-entity-layer.md new file mode 100644 index 000000000..682eb1833 --- /dev/null +++ b/docs/src/06-tracked-entity-layer.md @@ -0,0 +1,109 @@ +## Manage tracked entity layers { #using_maps_tracked_entity_layer } + +The tracked entity layer displays the geographical location of tracked entities registered in DHIS2. +Tracked entities with associated point or polygon coordinates appear on the map. + +![](../resources/images/maps_tracked_entity_layer.png) + +Tracked entity layers are represented by layer cards in the layer panel. The middle of the card +shows a legend indicating the styling of the layer. + +### Create a tracked entity layer { #maps_create_tracked_entity_layer } + +To create a tracked entity layer, choose **Tracked entities** on the **Add layer** selection. This +opens the Tracked entity layer configuration dialog. + +#### 1. Data + +![](../resources/images/maps_tracked_entity_layer_dialog_DATA.png) + +- Select the **Tracked entity type** you want to show on the map. + +- Select a **Program** to filter tracked entities by enrollment. + +- Use the **Program status** field to select the enrollment status of tracked entities to include: + All, Active, Completed, or Cancelled. + +- Filter by the **Follow-up** flag to include only tracked entities marked for follow-up. + +#### 2. Relationships + +![](../resources/images/maps_tracked_entity_layer_dialog_RELATIONSHIPS.png) + +> **Caution** +> +> Displaying tracked entity relationships in Maps is an experimental feature. + +- Select the **Display tracked entity relationships** checkbox to show relationships on the map. + +- Select the **Relationship type** to display from the dropdown list. Only relationships defined + for the selected tracked entity type are available. + +#### 3. Period + +![](../resources/images/maps_tracked_entity_layer_dialog_PERIOD.png) + +- If no program is selected, you can set start and end dates for when the tracked entities were + last updated. + +- If a program is selected, you can set the period when tracked entities were last updated or when + they were enrolled in the program. + +#### 4. Org units + +![](../resources/images/maps_tracked_entity_layer_dialog_ORG_UNITS.png) + +- Select the org units you want to include in the layer. Three selection modes are available: + + - **Selected only**: Include tracked entities belonging to selected org units only. + + - **Selected and below**: Include tracked entities in and right below selected org units. + + - **Selected and all below**: Include tracked entities in and all below selected org units. + +#### 5. Style + +![](../resources/images/maps_tracked_entity_layer_dialog_STYLE.png) + +- Select a **Color** for tracked entity points and polygons. + +- Select the **Point size** (radius between 1 and 20) for the points. + +- Select **Buffer** to display a visual buffer around each tracked entity. The buffer distance in + meters can be modified here. + +- If a relationship type has been selected on the Relationships tab, you can select a **Color** + and **Point size** for related tracked entities and a **Line color** for the relationship lines. + +Click **Add layer**. + +### Modify a tracked entity layer + +1. In the layer panel, click the edit (pencil) icon on the tracked entity layer card. + +2. Modify the settings on the **Data**, **Relationships**, **Period**, **Org units** and **Style** + tabs as desired. + +3. Click **Update layer**. + +### Modify information in tracked entity popups + +If you have access to the selected program in the Maintenance app, you can modify the information +displayed in the tracked entity popup window. + +![](../resources/images/maps_eventlayer_eventinfopopup.png) + +1. Open the **Maintenance** app. + +2. Select **Program**. + +3. Click the program you want to modify and select **(3) Attributes**. + +4. For every attribute you want to display in the popup window, enable **Display in list**. + +5. Click **Save**. + +### Remove a tracked entity layer + +To remove a tracked entity layer from the map, in the layer card to the left, click the _more +actions_ (three dots) icon and then click **Remove layer**. diff --git a/docs/src/07-facility-layer.md b/docs/src/07-facility-layer.md new file mode 100644 index 000000000..d505b6237 --- /dev/null +++ b/docs/src/07-facility-layer.md @@ -0,0 +1,98 @@ +## Manage facility layers { #using_maps_facility_layer } + +The facility layer displays icons representing types of facilities. Only point-type org units are +shown - polygon org units such as districts or regions are not displayed. + +![](../resources/images/maps_facility_layer.png) + +Facility layers are represented by layer cards in the layer panel. The middle of the card shows a +legend indicating the group set representation. The more actions (three dots) button includes +options to show or hide the data table and to download the data in GeoJSON format. + +### Create a facility layer + +To create a facility layer, choose **Facilities** on the **Add layer** selection. This opens the +Facility layer configuration dialog. + +#### 1. Org units + +![](../resources/images/maps_facility_layer_dialog_ORG_UNITS.png) + +- Select org unit levels and/or groups from the selection fields on the right-hand side. + +- Select the org units you want to include in the layer. It is possible to select either + + - One or more specific org units, or + + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. + +- The system administrator can set the default org unit level containing facilities in the + **System Settings** app. + +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. + +#### 2. Style + +![](../resources/images/maps_facility_layer_dialog_STYLE.png) + +- **Labels**: Allows labels to be shown on the layer. Font size, weight and color can be modified + here. + +- **Buffer**: Displays a visual buffer around each facility. The radius of the buffer can be + modified here. Not available if associated geometry is used. + +- **Count org units without a point location**: Org units without point coordinates are counted + and shown in a **Data quality** section of the legend. They also appear in the data table. + +- Facilities with a point location can be styled with an **org unit group set** using different + icons. Select a group set from the list of org unit group sets defined for your DHIS2 instance. + The system administrator can set the default org unit group set in the **System Settings** app. + + **Include unclassified org units**: Org units not belonging to any group in the selected group + set are shown with a configurable color and label (default: "Unclassified"). + +- If no group set is selected, the facilities will be shown as filled circles. The color and + radius can be changed. + +Click **Add layer**. + +### Modify a facility layer + +1. In the layer panel, click the edit (pencil) icon on the facility layer card. + +2. Modify the settings on the **Org units** and **Style** tabs as desired. + +3. Click **Update layer**. + +### Filter values in a facility layer + +Facility layers have a **Show/hide data table** option that can be toggled on or off from the +facility layer card. + +![](../resources/images/maps_facility_layer_data_table.png) + +The data table displays the data associated with the facility layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. The name filter field is an effective way to search for individual facilities. + +> **Note** +> +> Data table filters are temporary and are not saved with the map. + +### Open org unit profile + +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: + +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. + +3. Click an org unit row in the **data table**. + +### Remove a facility layer + +To remove a facility layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. diff --git a/docs/src/08-org-unit-layer.md b/docs/src/08-org-unit-layer.md new file mode 100644 index 000000000..9d1842dbd --- /dev/null +++ b/docs/src/08-org-unit-layer.md @@ -0,0 +1,106 @@ +## Manage org unit layers { #using_maps_org_unit_layer } + +The org unit layer displays the borders and locations of your org units. This layer is particularly +useful if you are offline and don't have access to background maps. + +![](../resources/images/maps_org_unit_layer.png) + +Org unit layers are represented by layer cards in the layer panel. The more actions (three dots) +button includes options to show or hide the data table and to download the data in GeoJSON format. + +### Create an org unit layer + +To create an org unit layer, choose **Org units** on the **Add layer** selection. This opens the Org +unit layer configuration dialog. + +#### 1. Org units + +![](../resources/images/maps_org_unit_layer_dialog_ORG_UNITS.png) + +- Select org unit levels and/or groups from the selection fields on the right-hand side. + +- Select the org units you want to include in the layer. It is possible to select either + + - One or more specific org units, or + + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. + +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to show facility catchment areas. + +#### 2. Style + +![](../resources/images/maps_org_unit_layer_dialog_STYLE.png) + +- **Labels**: Allows labels to be shown on the layer. Font style can be modified here. + +- **Boundary color**: Allows the boundary or outline color of the org units to be changed. + +- **Point radius**: Sets the base radius when point type elements, such as facilities, are + presented on the org unit layer. + +- **Count org units without coordinates**: Org units without coordinates are counted and shown in + a **Data quality** section of the legend. They also appear in the data table. + +- Org units with coordinates can be styled with an **org unit group set** using different colors. + Select a group set from the list of org unit group sets defined for your DHIS2 instance. + + **Include unclassified org units**: Org units not belonging to any group in the selected group + set are shown with a configurable color and label (default: "Unclassified"). + +Click **Add layer**. + +### Modify an org unit layer + +1. In the layer panel, click the edit (pencil) icon on the org unit layer card. + +2. Modify the settings on the **Org units** and **Style** tabs as desired. + +3. Click **Update layer**. + +### Filter values in an org unit layer + +Org unit layers have a **Show/hide data table** option that can be toggled on or off from the org +unit layer card. + +![](../resources/images/maps_bound_layer_data_table.png) + +The data table displays the data associated with the org unit layer. Click the arrow buttons in a +column header to sort by that column. Type in the filter fields below each column header to filter +the displayed rows. The name filter field is an effective way to search for individual org units. + +The level column supports numeric filtering using comparison operators: `>`, `<`, `>=`, and `<=`, +with `,` for OR and `&` for AND logic — for example: `2,>3&<8`. + +> **Note** +> +> Data table filters are temporary and are not saved with the map. + +### Open org unit profile + +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: + +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. + +3. Click an org unit row in the **data table**. + +### Navigate between org unit hierarchies + +When there are visible org units on the map, you can navigate up and down in the hierarchy without +changing the org unit selection. + +1. Right-click one of the org units. + +2. Select **Drill up one level** or **Drill down one level**. + + The drill down option is disabled if you are on the lowest level. Likewise, the drill up option + is disabled from the highest level. + +### Remove an org unit layer + +To remove an org unit layer from the map, in the layer card to the left, click the _more actions_ +(three dots) icon and then click **Remove layer**. diff --git a/docs/src/09-earth-engine-layer.md b/docs/src/09-earth-engine-layer.md new file mode 100644 index 000000000..34ce7e64e --- /dev/null +++ b/docs/src/09-earth-engine-layer.md @@ -0,0 +1,217 @@ +## Manage Earth Engine layers { #using_maps_gee } + +![](../resources/images/maps_ee_layer.png) + +Google Earth Engine layers are enabled if a Google Earth Engine API key has been configured for your +system. Contact your system administrator if you need access to these layers. + +The layers from Google Earth Engine let you display and aggregate external data for your org units. +Aggregated values can be viewed either in popups or in the data table. + +Earth Engine layers are represented by layer cards in the layer panel. The more actions (three dots) +button includes an option to show or hide the data table. + +![](../resources/images/maps_ee_layer_types.png) + +> **Note** +> +> The [**Maps app administrator**](#maps_app_administrator) can configure available layer sources. + +The following layer sources are supported (sources marked with an asterisk "\*" are available by +default): + +- **Population (group)**: Detailed population data from WorldPop. Estimates are provided annually + and include current, historical, and projected population values. Available between 2015 + and 2030. + + - **Population** \*: Total population count. + - **Population age groups** \*: Population broken down by age and gender. + +- **Building footprints** \*: The outlines of buildings derived from high-resolution satellite + imagery. Only for sub-Saharan Africa, South and Southeast Asia, Latin America and the Caribbean. + +- **Elevation** \*: Elevation above sea level. + +- **Heat stress (group)**: Universal Thermal Climate Index (UTCI), a measure of the thermal stress + experienced by a person in a given environment. Available from 1950. + + - **Heat stress daily**. + - **Heat stress weekly** (derived from daily dataset). + - **Heat stress monthly** (derived from daily dataset). + +- **Humidity (group)**: Relative humidity is the amount of water vapour present in air. Available + from 1950. + + - **Humidity daily**. + - **Humidity weekly** (derived from daily dataset). + - **Humidity monthly**. + +- **Precipitation (group)**: Accumulated water that falls to the surface. Combines model data with + observations from across the world. Two sources are available: + + - ERA5-Land. Available from 1950. + - **Precipitation daily**. + - **Precipitation weekly** (derived from daily dataset). + - **Precipitation monthly** \*. + - CHIRPS. Available from 1981. + - **Precipitation daily**. + - **Precipitation weekly** (derived from daily dataset). + - **Precipitation monthly** (derived from daily dataset). + +- **Temperature (group)**: Temperature at 2m above the surface. Combines model data with + observations from across the world. Available from 1950. + + - **Temperature daily**. + - **Temperature weekly** (derived from daily dataset). + - **Temperature monthly** \*. + +- **Land cover** \*: 17 distinct landcover types collected from satellites by NASA. Available + yearly, between 2001 and 2022. + +- **Vegetation**: Normalized difference vegetation index (NDVI) and Enhanced Vegetation Index + (EVI), used to quantify vegetation greenness. Collected from satellites by NASA. Available at + 16-day intervals, from 2000. + - **Vegetation 16-day** + - **Vegetation weekly** (derived from 16-day dataset). + - **Vegetation monthly** (derived from 16-day dataset). + +### Create an Earth Engine layer + +To create an Earth Engine layer, choose the desired layer from the **Add layer** selection. This +opens the layer configuration dialog. + +#### 1. Data + +![](../resources/images/maps_ee_layer_dialog_DATA.png) + +- **Dataset** (if within a data group): + + - For **Population** you can select either the **Population** or the **Population age group** + dataset. + +- **Data subset**: + + - For **Population age groups** you can select the age/gender **groups** you would like to + include when aggregating the data. + - For **Temperature** or **Heat stress** you can select the **temporal aggregation method** + you want to use (Mean, Min, Max). + - For **Vegetation** you can select the **index** you want to use (NDVI or EVI). + +- Select the **spatial aggregation methods** to use when calculating values for the selected org + units. This only affects results in popups and the data table (some options might not be + available depending on the layer source). + + - **Sum**: Calculates the total number within each org unit. Recommended to use for the + population layers. + + - **Min**: Returns the minimum value in the layer unit displayed below the selection. For + population layers it will be the minimum _people per hectare_. For the elevation layer it + will return the lowest elevation (meters above sea level). + + - **Max**: Returns the maximum value in the layer unit. For population layers it will be the + maximum _people per hectare_. For the elevation layer it will return the highest elevation + for each org unit. + + - **Mean**: Returns the mean value in the layer unit. For population layers it will be the + mean _people per hectare_. For the precipitation layer it will be the mean rainfall in + millimeters across the org unit. + + - **Median**: Returns the median value in the layer unit. For population layers it will be the + median _people per hectare_. For the temperature layer it will be the median °C across the + org unit. + + - **Standard deviation**: Returns the standard deviation value in the layer unit. + + - **Variance**: Returns the variance value in the layer unit. + + - **Special cases**: + - For "building footprints": **Count**: Returns the number of buildings within each org + unit. Note that building counts are only available for smaller org unit areas. + - For "landcover": **Percentage**, **Hectare**, **Acres**: Return the area covered by each + landcover category within each org unit in different units. + +#### 2. Period + +![](../resources/images/maps_ee_layer_dialog_PERIOD.png) + +- Select the period type (if multiple sources are enabled for **Heat stress**, **Precipitation**, + **Temperature**, or **Vegetation**). + +- Select the period for the data source. The available periods are set by the layer source. Some + sources are only available at a single point in time. + +#### 3. Org units + +![](../resources/images/maps_ee_layer_dialog_ORG_UNITS.png) + +- Select the org units where you want to see aggregated data values. It is possible to select + either + + - One or more specific org units, org unit levels in the hierarchy, org unit groups, or + + - A relative level in the org unit hierarchy, with respect to the user. By selecting a **User + org unit** the map data will appear differently for users at different levels in the org + unit hierarchy. + +- **Use associated geometry**: This dropdown will only show if there are any additional geometries + available for your org units. This is typically used to calculate values for facility catchment + areas. + +#### 4. Style + +![](../resources/images/maps_ee_layer_dialog_STYLE.png) + +- Adjust the legend **Min**, **Max**, number of **Classes**, and color map, as desired. + +- **Buffer**: If you select org units with a single point coordinate (facilities), you can set a + radius buffer to calculate the data value within. A radius of 5000 meters will aggregate all + values available within a 5 km distance from a facility. Buffer option is not available if + associated geometry is used. + +- **Count org units without coordinates**: Org units without coordinates are counted and shown in + a **Data quality** section of the legend. They also appear in the data table. + +Click **Add layer**. + +Click an org unit or facility on the map to see the aggregation result. + +### Modify an Earth Engine layer + +1. In the layer panel, click the edit (pencil) icon on the Earth Engine layer card. + +2. Modify the settings on the **Data**, **Period**, **Org units**, and **Style** tabs as desired. + +3. Click **Update layer**. + +### Filter values in an Earth Engine layer + +Earth Engine layers have a **Show/hide data table** option that can be toggled on or off from the +layer card. + +![](../resources/images/maps_ee_layer_data_table.png) + +The data table displays all the aggregated values for the selected org units. Click the arrow +buttons in a column header to sort by that column. Type in the filter fields below each column +header to filter the displayed rows. + +There is one column for each selected aggregation type. These numeric columns support comparison +operators: `>`, `<`, `>=`, and `<=`, with `,` for OR and `&` for AND logic — for example: `2,>3&<8`. + +> **Note** +> +> Data table filters are temporary and are not saved with the map. + +### Open org unit profile + +You can open the [org unit profile](#using_maps_org_unit_profile) in three ways: + +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. + +3. Click an org unit row in the **data table**. + +### Remove an Earth Engine layer + +To remove an Earth Engine layer from the map, in the layer card to the left, click the _more +actions_ (three dots) icon and then click **Remove layer**. diff --git a/docs/src/10-external-map-layers.md b/docs/src/10-external-map-layers.md new file mode 100644 index 000000000..94fc8bde2 --- /dev/null +++ b/docs/src/10-external-map-layers.md @@ -0,0 +1,52 @@ +## Add external map layers { #using_maps_external_map_layers } + +![](../resources/images/maps_terrain_imagery.png) + +External map layers are represented as either basemaps or overlays. + +> **Note** +> +> The [**Maps app administrator**](#maps_app_administrator) can add external map layers. + +- **Basemaps** + + These are available in the **basemap** card in the layers panel and are selected as any other + basemap. + +- **Overlays** + + These are available in the **Add layer** selection. Unlike basemaps, overlays can be placed + above or below any other overlay layers. + +Overlay layers are represented by additional layer _cards_ in the layer panel. + +Along the top of the overlay card from left to right are: + +- A grab field to allow dragging and re-ordering layers with the mouse + +- The title of the external map layer + +- An arrow symbol to collapse or expand the overlay card + +In the middle of the card is a legend if the layer has one. + +Along the bottom of the overlay card from left to right are: + +- A slider for modifying the layer transparency + +- A delete icon to remove the layer from the current map + +### GeoJSON external layers + +If you add a GeoJSON external layer to your map, you will have a few style choices: + +![](../resources/images/maps_geojson_external_layer_style.png) + +Once the GeoJSON layer is displayed, you can view its data table: + +![](../resources/images/maps_geojson_external_layer_data_table.png) + +As with other layers, you can sort and filter the data. If you want to view the data for one row, +click the row to open the **Feature Profile**: + +![](../resources/images/maps_geojson_external_layer_feature_profile.png) diff --git a/docs/src/11-org-unit-profile.md b/docs/src/11-org-unit-profile.md new file mode 100644 index 000000000..84a59f3b4 --- /dev/null +++ b/docs/src/11-org-unit-profile.md @@ -0,0 +1,17 @@ +## Org unit profile { #using_maps_org_unit_profile } + +![](../resources/images/maps_org_unit_profile.png) + +The org unit profile shows detailed information about each org unit. You can open the profile from +org unit layers, facility layers, thematic layers, and Earth Engine layers. + +You can open the org unit profile in three ways: + +1. Click an org unit on the map, then click the **View profile** button in the popup. + +2. Right-click one of the org units on the map, and select **View profile** from the menu. + +3. Click an org unit row in the **data table**. + +The profile will show on the right side of the map. The profile content is set by the system +administrator. diff --git a/docs/src/12-file-menu.md b/docs/src/12-file-menu.md new file mode 100644 index 000000000..af0bd51b6 --- /dev/null +++ b/docs/src/12-file-menu.md @@ -0,0 +1,105 @@ +## File menu { #using_maps_file_menu } + +![](../resources/images/maps_file_menu.png) + +Use the **File menu** to manage your maps. Several menu items will be disabled until you open or +save a map. + +Saving your maps makes it easy to restore them later. It also gives you the opportunity to share +them with other users as an interpretation or add them to a dashboard. You can save all types of +layer configurations as a saved map. + +### Create a new map + +Click **File** \> **New**. + +> **Note** +> +> This will discard the current map without saving. + +### Open a map + +1. Click **File** \> **Open**. A dialog box opens with a list of maps. + +2. Find the saved map you want to open. You can either use \< and \> or the search field to find a + saved map. The list is filtered on every character that you enter. You can filter the list by + selecting **Show all**, **Created by me** or **Created by others**. + +3. Click the name of the map you want to open. + +### Save a map + +When you have created a map it is convenient to save it for later use: + +1. Click **File** \> **Save**. + +2. Enter a **Name** (required) and a **Description** (optional) the first time you save a map. + +3. Click **Save**. + +### Save a copy of a map + +1. Click **File** \> **Save as...** + +2. Enter a **Name** (required) and a **Description** (optional) for the map. + +3. Click **Save**. + +### Rename a map + +1. Click **File** \> **Rename**. + +2. Enter a new **Name** and/or **Description** for your map. + +3. Click **Rename**. The map is updated. + +### Translate a map + +1. Click **File** \> **Translate**. + +2. Select the **Locale** (language) for your translation. + +3. Enter a translated **Name** and **Description**. The original text will show below the field. + +4. Click **Save**. + +### Modify sharing settings for a map + +After you have created a map and saved it, you can share the map with everyone or a user group. To +modify the sharing settings: + +1. Click **File** \> **Share**. The sharing settings dialog opens. + +2. **Give access to a user or group**: In the text box, search for the name of the user or group + you want to share your saved map with and select it. + + Select the access level and click **Give access**. + + Repeat the step to add more users or groups. + +3. **Users and groups that currently have access**: For each user or group, choose the access + level. The options are: + + - **No access**: The public won't have access to the map. This setting is only applicable to + All users. + + - **View only**: Users can view but not edit the map. + + - **View and edit**: Users can view and edit the map. + + - **Remove access**: Remove the access for groups or individuals. + +4. Click **Close** to close the dialog. + +### Get the link to a map + +1. Click **File** \> **Get link**. A link dialog opens. + +2. Copy the link. + +### Delete a map + +1. Click **File** \> **Delete**. A confirmation dialog is displayed. + +2. Click **Delete** to confirm that you want to delete the saved map. Your map is deleted and the + layers are cleared from the view. diff --git a/docs/src/13-interpretations.md b/docs/src/13-interpretations.md new file mode 100644 index 000000000..7607f11c3 --- /dev/null +++ b/docs/src/13-interpretations.md @@ -0,0 +1,65 @@ +## Map interpretations and details { #mapsInterpretation } + +An interpretation is a description of a map for a given period. This information is also visible in +the **Dashboard app**. Click **Interpretations and details** in the top right of the workspace to +open the interpretations panel. The button is only available when the map has been saved. + +![](../resources/images/maps_interpretations_panel.png) + +### View interpretations based on relative periods + +To view interpretations for relative periods, such as a year ago: + +1. Open a saved map with interpretations. + +2. Click **Interpretations and details** in the top right of the workspace to open the + interpretations panel. + +3. Click **See interpretation**. Your map displays the data and the date based on when the + interpretation was created. To view other interpretations, click them. + +![](../resources/images/maps_interpretations_modal.png) + +### Write interpretation for a map + +To create an interpretation, you first need to create a map and save it. If you've shared your map +with other people, the interpretation you write is visible to those people. + +1. Open a saved map. + +2. Click **Interpretations and details** in the top right of the workspace to open the + interpretations panel. + +3. A text field appears where you can write an interpretation. + +4. In the text field, type a comment, question or interpretation. You can also mention other users + with '@username'. Start by typing '@' followed by the first letters of the username or real + name, and a list of matching users will appear. Mentioned users will receive an internal DHIS2 + message with the interpretation or comment. You can see the interpretation in the **Dashboard + app**. + +5. Click **Post interpretation** to save the interpretation. + +### Change sharing settings for an interpretation + +1. Click an interpretation (see how to view an interpretation above). + +2. Click the share icon below the interpretation. The sharing settings dialog opens. + +3. Search for and add users and user groups that you want to share your map with, and set the + access level. Click **Give access**. + +4. Change the access level for the users you want to modify: + + - **No access**: The public won't have access to the map. This setting is only applicable to + All users. + + - **View only**: Users can view but not edit the map. + + - **View and edit**: Users can view and edit the map. + + - **Remove access**: Remove the access for groups or individuals. + +5. Click **Close** when sharing settings are updated. + +![](../resources/images/maps_interpretations_sharing.png) diff --git a/docs/src/14-image-export.md b/docs/src/14-image-export.md new file mode 100644 index 000000000..b78b6f3c7 --- /dev/null +++ b/docs/src/14-image-export.md @@ -0,0 +1,26 @@ +## Save a map as an image { #using_maps_image_export } + +You can download your map as an image by clicking the **Download** button in the top menu. + +![](../resources/images/maps_download.png) + +You will enter **Download mode** where you can adjust the map layout before you download the image. +The left column gives you the following options: + +- **Show map name**: Select if you want to include the map name or not. This option is only + available if the map is saved. To change the name, exit download mode and select **File** \> + **Rename**. +- **Show map description**: Select if you want to include the map description or not. This option + is only available if a map description was added when the map was saved. To change the map + description, exit download mode and select **File** \> **Rename**. +- **Show legend**: Select if you want to include the map legend. If the map includes more than one + layer, you can select the visibility for each legend. +- **Show overview map**: Select if you want to include an overview map (often named inset map). + This option will be disabled if there is not enough room for it in the right column. +- **Show north arrow**: Select to include a north arrow on the map. The default position is the + lower right corner of the map, but you can change it to another corner. + +Click **Download** to download your map. + +Resize your browser window to change the map dimensions. You can also reposition both the main map +and the overview map. diff --git a/docs/src/15-search.md b/docs/src/15-search.md new file mode 100644 index 000000000..e4e940fd1 --- /dev/null +++ b/docs/src/15-search.md @@ -0,0 +1,14 @@ +## Search for a location { #using_maps_search } + +The place search function allows you to search for almost any location or address. This is useful to +locate sites, facilities, villages or towns on the map. + +![](../resources/images/maps_place_search.png) + +1. On the right side of the Maps window, click the magnifier icon. + +2. Type the location you're looking for. + + A list of matching locations appear as you type. + +3. From the list, select a location. A pin indicates the location on the map. diff --git a/docs/src/16-measure-distance.md b/docs/src/16-measure-distance.md new file mode 100644 index 000000000..40cb865ed --- /dev/null +++ b/docs/src/16-measure-distance.md @@ -0,0 +1,10 @@ +## Measure distances and areas in a map { #using_maps_measure_distance } + +1. In the upper left part of the map, put the cursor on the **Measure distances and areas** (ruler) + icon and click **Create new measurement**. + +2. Add points to the map. + +3. Click **Finish measurement**. + +![](../resources/images/maps_measure_distance.png) diff --git a/docs/src/17-latitude-longitude.md b/docs/src/17-latitude-longitude.md new file mode 100644 index 000000000..53eb298c2 --- /dev/null +++ b/docs/src/17-latitude-longitude.md @@ -0,0 +1,4 @@ +## Get the latitude and longitude at any location { #using_maps_latitude_longitude } + +Right-click a point on the map and select **Show longitude/latitude**. The values are displayed in a +popup window. diff --git a/docs/src/18-administrator.md b/docs/src/18-administrator.md new file mode 100644 index 000000000..ee60775fb --- /dev/null +++ b/docs/src/18-administrator.md @@ -0,0 +1,15 @@ +## Maps app administrator { #maps_app_administrator } + +A **Maps** app administrator can be defined by the system administrator assigning the +`F_EXTERNAL_MAP_LAYER_PUBLIC_ADD` authority. + +The **Maps** app administrator is able to: + +- Select the sources for Google Earth Engine layers available to other users via the **Manage + available layer sources** button. + +![](../resources/images/maps_admin_managesources_button.png) + +- Add new external layer sources via the Maintenance app. + +![](../resources/images/maps_admin_externallayer.png) diff --git a/docs/src/19-see-also.md b/docs/src/19-see-also.md new file mode 100644 index 000000000..510a3ffe5 --- /dev/null +++ b/docs/src/19-see-also.md @@ -0,0 +1,23 @@ +## See also + +- Configuration: + + - [Configure DHIS2 Maps](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/maps.html) + - [Accessing map layers from Google Earth Engine](https://docs.dhis2.org/en/topics/tutorials/google-earth-engine-sign-up.html#accessing-map-layers-from-google-earth-engine) + - [Geo-enabled microplanning](https://docs.dhis2.org/en/implement/health/immunization/immunization-campaigns/use.html?h=microplanning#geoenabled-microplanning), + including details about facility catchment areas + +- Settings: + + - [Infrastructural indicators / Infrastructural data elements / Infrastructural period type](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=Infrastructural%20indicators) + - [Use centroids for organisation unit polygons in event analytics / Org unit group set in facility map layers / Org unit level in facility map layers / Default basemap](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=Use%20centroids%20for%20organisation%20unit%20polygons%20in%20event%20analytics) + - [Google Maps / Bing / Azure API keys](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/system-settings.html#system_server_settings:~:text=com/analytics.-,Google%20Maps%20API%20key,-Defines%20the%20API) + +- Metadata management: + + - [Manage legends](https://docs.dhis2.org/master/en/user/html/manage_legend.html) + - [Aggregation operators](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/configuring-the-system/metadata.html#create_data_element:~:text=Aggregation%20operators) + +- Training: + - [Trainer's Guide to Maps](https://docs.dhis2.org/en/topics/training-docs/analytics-tools-academy/maps/traineraposs-guide-to-maps.html) + - [Learner's Guide to Maps](https://docs.dhis2.org/en/topics/training-docs/analytics-tools-academy/maps/learneraposs-guide-to-maps.html) diff --git a/package.json b/package.json index 96dc22f9d..47fd031a8 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,9 @@ "validate-commit": "d2-style check --staged", "validate-push": "yarn test", "cy:open": "start-server-and-test 'yarn start' http://localhost:3000 'yarn cypress open --e2e'", - "cy:run": "start-server-and-test 'yarn start' http://localhost:3000 'yarn cypress run'" + "cy:run": "start-server-and-test 'yarn start' http://localhost:3000 'yarn cypress run'", + "docs:build": "yarn docs:format && node scripts/build-docs.js", + "docs:format": "prettier --write --prose-wrap always --print-width 100 'docs/src/*.md'" }, "devDependencies": { "@dhis2/cli-app-scripts": "^12.11.0", diff --git a/scripts/build-docs.js b/scripts/build-docs.js new file mode 100644 index 000000000..15d3cd1b7 --- /dev/null +++ b/scripts/build-docs.js @@ -0,0 +1,17 @@ +const fs = require('node:fs') +const path = require('node:path') + +const srcDir = path.resolve(__dirname, '../docs/src') +const output = path.resolve(__dirname, '../docs/maps.md') + +const files = fs + .readdirSync(srcDir) + .filter((f) => f.endsWith('.md')) + .sort() +const content = files + .map((f) => fs.readFileSync(path.join(srcDir, f), 'utf8')) + .join('') + .replaceAll('../resources/images/', 'resources/images/') + +fs.writeFileSync(output, content) +console.log('Built docs/maps.md')