Merge pull request #287978 from stevemunk/PowerBI-Data-Bound-Reference-Layer-and-Conditional-Formatting

Power bi data bound reference layer and conditional formatting

Author: v-dirichards

articles/azure-maps/media/power-bi-visual/data-bound-reference-layer/conditional-formatting.png

@@ -100,6 +100,142 @@ The general layer section of the **Format** pane are common settings that apply
 >
 > For more information on the range scaling option, see **Range scaling** in the properties table of the [Add a bubble layer] article.
 
+## Data-Bound Reference Layer
+
+The Data-Bound Reference Layer enables the association of data with specific shapes in the reference layer based on common attributes.
+
+To use the Data-Bound Reference layer, drag the column containing unique identifiers (can be location data or not) to the Location field of the Azure Maps Visual.
+
+:::image type="content" source="media/power-bi-visual/data-bound-reference-layer/location-field.png" alt-text="A screenshot showing the location field in Power BI desktop.":::
+
+Azure Maps matches these identifiers with the corresponding properties in the uploaded spatial file, automatically linking your data to the shapes on the map.
+
+In scenarios with multiple properties, Azure Maps identifies a common property in each shape and compares its value with the selected data column in the Location field. It then uses the property that has the highest number of matches with the selected data column.
+
+:::image type="content" source="media/power-bi-visual/data-bound-reference-layer/data-bound-reference-layer.png"  lightbox="media/power-bi-visual/data-bound-reference-layer/data-bound-reference-layer.png" alt-text="A screenshot showing the Data-Bound Reference Layer example in Power BI desktop.":::
+
+If one or more shapes in the reference layer can't be automatically mapped to any data point, you can manage these unmapped objects by following these steps:
+
+1. Select the **Format visual** tab in the **Visualizations** pane.
+1. Select **Reference layer**.
+1. Select **Unmapped Objects**.
+1. Select the **Show** toggle switch to toggle On/Off. This highlights shapes that aren't mapped to any data points.
+
+Optionally, select the **Use custom colors** toggle switch to toggle On/Off custom fill and border colors for unmapped objects to make them visually distinct on the map.
+
+:::image type="content" source="media/power-bi-visual/data-bound-reference-layer/data-bound-reference-layer-unmapped-objects.png" lightbox="media/power-bi-visual/data-bound-reference-layer/data-bound-reference-layer-unmapped-objects.png" alt-text="A screenshot showing the Data-Bound Reference Layer example in Power BI desktop with unmapped objects showing in a different color.":::
+
+<!----------------------------------------------------------------------------
+### Key matching example
+
+#### Semantic model
+
+| Datapoint   | Country | City     | Office name |
+|-------------|---------|----------|-------------|
+| Datapoint_1 | US      | New York | Office C    |
+| Datapoint_1 | US      | Seattle  | Office A    |
+| Datapoint_1 | US      | LA       | Office B    |
+
+#### Reference layer data (take GeoJSON as an example)
+
+```json
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Office A",
+        "shape": "Shape_1",
+        "id": "Office A"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          ...
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Office B",
+        "shape": "Shape_2",
+        "id": "Office B"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          ...
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Office C",
+        "shape": "Shape_3"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          ...
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Office D",
+        "shape": "Shape_4"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          ...
+        ]
+      }
+    }
+  ]
+}
+```
+
+#### the mapping results
+
+|                 | Location bucket|Mapping result                                                                  |
+|-----------------|----------------|--------------------------------------------------------------------------------|
+| Case 1          | Office name    | Shape_1 ↔ Datapoint_2                                                          |
+|                 |                | Shape_2 ↔ Datapoint_3                                                          |
+|                 |                | Shape_3 ↔ Datapoint_1                                                          |
+|                 |                | Shape_4 ↔ x (Since there’s no datapoint with Office name “Office D”)           |
+| Case 2          | City           | Nothing is mapped, since there’s no property that contains matched City names. |
+
+Note that there is a property “id” also has “Office x” values that is not being used, but instead the property “name” is used for data mapping since it has 3 datapoints matched and “id” only has 2 datapoints matched.
+
+---------------------------------------------------------------------------------------------------------------------------->
+
+## Conditional Formatting
+
+Conditional formatting can be applied to data to dynamically change the appearance of shapes on a map based on the provided data. For instance, gradient colors can visualize various data values such as population density, sales performance, or other metrics. This is a powerful tool for combining spatial and business data to create interactive and visually compelling reports.
+
+:::image type="content" source="media/power-bi-visual/data-bound-reference-layer/conditional-formatting.png" alt-text="A screenshot showing the Conditional Formatting controls for points, lines, polygons, and unmanaged objects in the reference layer control in Power BI desktop.":::
+
+There are several ways to set colors to the shapes. The following table shows the priorities used:
+
+| Priority | Source                        | Description                                                     |
+|----------|-------------------------------|-----------------------------------------------------------------|
+| 1        | Preset style in spatial files | Color and style as defined in the spatial file                  |
+| 2        | Unmapped object colors        | Custom colors used when the geometry isn’t data-bound           |
+| 3        | Legend colors                 | Colors provided by Legend/Series                                |
+| 4        | Conditional formatting colors | Colors provided by conditional formatting                       |
+| 5        | Custom formatting colors      | User defined custom styles in the Reference Layer options in the formatting pane |
+| 6        | Default colors                | Default colors defined in the Azure Maps visual                 |
+
+> [!TIP]
+>
+> The Azure Maps Power BI Visual can only perform geocoding on valid location data such as geographical coordinates, addresses, or place names. If no valid location data is uploaded, data layers that depend on geocoded locations, such as heat maps or bubble layers, won’t display on the map.
+>
+> The Data-Bound Reference Layer will appear on the map as long as the data column contains unique identifiers that match properties in the spatial file, but to ensure correct results, your data column must include valid geographic information.
+
 ## Next steps
 
 Change how your data is displayed on the map: