more documentation additions

Author: Russell-Shean

docs/_quarto.yml

@@ -37,7 +37,7 @@ quartodoc:
 
   sections:
     - title: Power Bpy
-      desc: Python functions for building Power BI dashboards
+      desc: The first thing you should create is an instance of the Dashboard class. Then use the `add_page()` or `load_page()` functions to attach instances of the internal `_Page` class. All methods are attached to either dashboards or pages. Click below to see which methods are attached to which. For more details about how to build dashboards, see the test dashboard [tutorial](https://www.russellshean.com/powerbpy/example_dashboards/Test%20Dashboard/Testing%20Dashboard.html) section of this website.
       contents:
         # the functions being documented in the package.
         # you can refer to anything: class methods, modules, etc..

docs/example_dashboards/Sanky Chart and Table/chart_and_table.qmd

@@ -1,13 +1,13 @@
 ---
-Title: "WOW Power BI 2025 week 13 demonstration"
+title: "WOW Power BI 2025 week 13 demonstration"
 date: 2025-12-11
 description: Let's add a table and a sanky chart to a dashboard.
 image: "https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sanky_screenshot.png"
 ---
 
 # Sanky Chart and Table      
 I used the PowerBpy python module to recreate an <a href="https://workout-wednesday.com/pbi-2025-w13/">sanky chart and table</a> dashboard from the <a href="https://workout-wednesday.com/">Workout Wednesday Group</a> challenge. Here's a screenshot of the original dashboard (top) and the dashboard I recreated using Power Bpy (bottom). (It appears that the data has changed since the original author created his dashboard, so my version and his look a bit different because the data is a bit different, but the overall format is pretty similiar). The rest of the blog will describe key parts of the code I used to make the dashboard. The full code is available [here](https://github.com/Russell-Shean/powerbpy-demos/tree/main/WOW/2025/13).      
-![my sanky](https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sanky_screenshot.png)       
+<img id="my-sanky-img" src="https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/sanky_screenshot.png" style="margin-bottom:10px">      
 ![wow sanky](https://github.com/Russell-Shean/powerbpy/raw/main/docs/assets/images/WOW_sanky.png)
 
 ## Assumptions
@@ -82,8 +82,6 @@ store_names = (
                .reset_index(drop=True)
                )
 
-
-
 # Makes sure OrderDate is a date
 sales["OrderDate"] = pd.to_datetime(sales["OrderDate"])
 
@@ -120,8 +118,6 @@ sales_by_store_and_date = (
              # Define a default for if neither condition is matched
              default="middle_period"
 
-
-
         )
     )
 
@@ -134,17 +130,13 @@ sales_by_store_and_date = (
     .assign(
 
         sales_size = lambda df: np.select(
-
-
-
             [
                 df["store_total_sales"] < 1000,
 
                 (df["store_total_sales"] >= 1000) &
                 (df["store_total_sales"] < 5000),
 
                 df["store_total_sales"] >= 5000
-
             ],
 
             [
@@ -153,20 +145,14 @@ sales_by_store_and_date = (
                 "Large"
             ],
         default="Unknown"
-
-
         )
-
-
     )
 
     # Merge the store names onto the dataframe
     .merge(
-
         store_names,
         on = "StoreKey",
         how = "left"
-
     )
 
     # pivot the dataframe to expand the time period and sales size columns wider
@@ -175,7 +161,6 @@ sales_by_store_and_date = (
         columns="time_period",
         values=['store_total_sales', "sales_size"]
     )
-
 )
 
 

docs/example_dashboards/Test Dashboard/Testing Dashboard.qmd

@@ -207,9 +207,38 @@ page1.add_button(label = "Move to page 2",
 ```     
 If the code works you should get two buttons that look like this. The first button should open a new www.google.com tab in your browser. The second button should send you to page 2.     
 
-![image](https://github.com/Russell-Shean/powerbpy/blob/main/docs/assets/images/buttons_demo.gif)
+![image](https://media.githubusercontent.com/media/Russell-Shean/powerbpy/refs/heads/main/docs/assets/images/buttons_demo.gif)
 
 ## Add a choropleth map
 Often we have data that is tied to geographic regions that can be respresented by a polygon such as states, counties, zip codes, or countries. A choropleth map uses color to represent values in the data by shading the polygons according to the value of the data. (If that was way too abstract, see the example below. Basically we're creating a color code map to represent the data.)    
 
-This function does a lot under the hood so you don't have to. It creates measures in the dataset so that bins will automatically adjust when filtering conditions change, it creates the map and adds text boxes for a legend and and a slicer to allow the user to filter the data. I'll describe in more detail below some of the optional method arguments and how they can be used to customize your map. But first, here are the required arguments: 
+This function does a lot under the hood so you don't have to. It creates measures in the dataset so that bins will automatically adjust when filtering conditions change, it creates the map and adds text boxes for a legend and and a slicer to allow the user to filter the data. The method requires you to provide a shape file that corresponds to a variable in your dataset. For example, the dataset could have two columns: US states and average income. In this case you should provide a shapefile of US states.     
+
+The method also give two different options for binning the data and assigning ranges of values to different colors on the map. You can only specify one of the two options at a time. The first option is to provide a static set of breaks that you define yourself. This is ideal if you already know the structure of your data and how you want to assign ranges of values  to different colors. Use the `static_bin_breaks` argument to pass an integer list of break values. The second option is to provide a list of percentiles that you want to use to bin the data into ranges. This option is intended to be used in conjunction with a third variable that you use to filter the data. For example, assume you have a third variable in your dataset of average income by state dataset, maybe age. You could pass age to the `filtering_var` argument to create a slicer attached to the map that filters the dataset by age before rerendering the map. You could then pass the list of percentiles to `percentile_bin_breaks` such as 0, 0.2, 0.4, 0.6, 0.8, 1. This will create breaks between 0% and 20%, 20% and 40%, etc and the bins will be recalculated each time the slicer filters are adjusted. So, for this example, if you selected "young people" in the slicer, the bins will be re-calculated and the map will re-render to show 20, 40, 60 etc, percentiles for just young people. If you provide `percentile_bin_breaks` you must also provide a `filtering_var`; the assumption being that if you don't need dynamic recalculation of bins based on the filtering variable, you'd be better off calculating a static set of breaks for yourself and passing them as a list to `static_bin_breaks`. 
+    
+I'll describe in more detail below some of the optional method arguments and how they can be used to customize your map. But first, here are the required arguments: 
+       
+  1. `visual_id` - Give the button a unique id that you'll remember. This id cannot be the same as any other visual in the dashboard.
+  2. `data_source` - The name of the dataset you want to use to build the map. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.
+  3. `shape_file_path` - A path to a shapefile that you want to use to build the map. This file can be any valid shapefile accepted by power BI. In this example dashboard I use a geojson, but presumably an Arcgis file with a .shp extension would also work. This shape file will be added to the dashboard's registered resources.
+  4. `map_title` - The title you want to put above the map.
+  5. `location_var` - The name of the column in data_source that you want to use for the location variable on the map. This should also correspond to the geography of your shape file.
+  6. color_var: The name of the column in data_source that you want to use for the color variable on the map. This variable should be numeric.
+        filtering_var: str
+            Optional. The name of a column in data source that you want to use to filter the color variable on the map. This must be supplied if providing percentile_bin_breaks. If you want to use percentiles without filtering (ie on static data), you should calculate the percentiles yourself and pass them to static_bin_breaks. Do not provide both static_bin_breaks and a filtering_var.
+        static_bin_breaks: list
+            This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc. A filtering_var cannot be provided if static_bin_breaks is provided. Use percentile bin breaks instead.
+        color_palatte: list
+            A list of hex codes to use to color your data. There should be one fewer than the number of entries in static_bin_breaks
+        add_legend: bool
+            True or False, would you like to add the default legend? (By default legend, I mean this function's default, not the Power BI default)
+        static_bin_breaks: list
+            This should be a list of numbers that you want to use to create bins in your data. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. The function will create bins between the first and second number, second and third, third and fourth, etc.
+        percentile_bin_breaks: list
+            This should be a list of percentiles between 0 and 1 that you want to us to create bins in your data. If provided, a filtering_var must also be provided. This will create power BI measures that dynamically update when the data is filtered by things such as slicers. There should be one more entry in the list than the number of bins you want and therefore the number of colors passed to the color_palette argument. Here's an example use case: to create 5 equal sized bins pass this list: [0,0.2,0.4,0.6,0.8,1]
+        height: int
+            Height of map on the page
+        width: int
+            Width of map on the page
+        x_position: int
+            The x coordinate of where you want to put the map on the page. Origin is page's top left corner.

src/powerbpy/page.py

@@ -554,13 +554,13 @@ def add_shape_map(self,
         data_source: str
             The name of the dataset you want to use to build the map. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.
         shape_file_path: str
-            A path to a shapefile that you want to use to build the map. This shape file will be added to the registered resources.
+            A path to a shapefile that you want to use to build the map. This file can be any valid shapefile accepted by power BI. In this example dashboard I use a geojson, but presumably an Arcgis file with a .shp extension would also work. This shape file will be added to the dashboard's registered resources.
         map_title: str
             The title you want to put above the map.
         location_var: str
-            The name of the column in data_source that you want to use for the location variable on the map
+            The name of the column in data_source that you want to use for the location variable on the map.This should also correspond to the geography of your shape file.
         color_var: str
-            The name of the column in data_source that you want to use for the color variable on the map
+            The name of the column in data_source that you want to use for the color variable on the map. This variable should be numeric.
         filtering_var: str
             Optional. The name of a column in data source that you want to use to filter the color variable on the map. This must be supplied if providing percentile_bin_breaks. If you want to use percentiles without filtering (ie on static data), you should calculate the percentiles yourself and pass them to static_bin_breaks. Do not provide both static_bin_breaks and a filtering_var.
         static_bin_breaks: list

src/powerbpy/shape_map.py

@@ -53,13 +53,13 @@ def __init__(self,
         data_source: str
             The name of the dataset you want to use to build the map. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.
         shape_file_path: str
-            A path to a shapefile that you want to use to build the map. This shape file will be added to the registered resources.
+            A path to a shapefile that you want to use to build the map. This file can be any valid shapefile accepted by power BI. In this example dashboard I use a geojson, but presumably an Arcgis file with a .shp extension would also work. This shape file will be added to the dashboard's registered resources.
         map_title: str
             The title you want to put above the map.
         location_var: str
-            The name of the column in data_source that you want to use for the location variable on the map
+            The name of the column in data_source that you want to use for the location variable on the map. This should also correspond to the geography of your shape file.
         color_var: str
-            The name of the column in data_source that you want to use for the color variable on the map
+            The name of the column in data_source that you want to use for the color variable on the map.This variable should be numeric.
         filtering_var: str
             Optional. The name of a column in data source that you want to use to filter the color variable on the map. This must be supplied if providing percentile_bin_breaks. If you want to use percentiles without filtering (ie on static data), you should calculate the percentiles yourself and pass them to static_bin_breaks. Do not provide both static_bin_breaks and a filtering_var.
         static_bin_breaks: list