PBI_dashboard_creator package¶
Submodules¶
PBI_dashboard_creator.add_ADLS_csv module¶
- PBI_dashboard_creator.add_ADLS_csv.add_csv_from_blob(dashboard_path, account_url, blob_name, data_path, tenant_id=None, use_saved_storage_key=False, SAS_url=None, storage_account_key=None, warnings=True)¶
Add a csv file store in a ADLS blob container to a dashboard
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
account_url (str) – The url to your Azure storage account. It should be in the format of https://<YOUR STORAGE ACCOUNT NAME>.blob.core.windows.net/. You can find it in Azure Storage Explorer by clicking on the storage account and then looking at the blob endpoint field
blob_name (str) – The name of the blob container. In Azure Storage Explorer, click on the storage account, then inside “Blob Containers” will be all your blob containers. Use the node dislay name field.
data_path (str) – The relative path to the file you want to load from the blob. It should be relative to blob_name
tenant_id (str) – The tenant id of the tenant where your storage account is stored. This field is only used with browser authentication. (The default).
use_saved_storage_key (boolean) – This optional argument tells python to look in your system’s default credential manager for an Azure Storage Account token and prompt the user to add one if it’s not there. USE WITH CAUTION, THE STORAGE ACCOUNT TOKENS ALLOW FOR A MASSIVE AMOUNT OF ACCESS. CONSIDER USING SAS URLS OR INTERACTIVE BROWSER AUTHENTICATION INSTEAD.
SAS_url (str) – A limited time single access url scoped to just the file you want to grant read access to. To generate one from Azure Storage Explorer, right click on the file you want and then choose “Get Shared Access Signature”
storage_account_key (str) – Please, Please, Please do not use this when running this function on a local computer. Hardcoding credentials into code is SUPER BAD practice. Please set use_saved_storage_key to true instead. It will store the key securely in your operating system’s credential manger. You should only pass a storage account key to the function if you are running this code in a cloud environment such as databricks and using that cloud platform’s secure secret manager. (Something like Github Secrets or Azure Key Vault)
- Returns:
None
DO NOT HARD CODE CREDENTIALS. Use the use_saved_storage_key option instead.
This function creates custom M code and is therefore more picky than pandas or Power BI desktop. The csv file should probably not have row numbers. (Any column without a column name will be renamed to “probably_an_index_column”) NA values must display as “NA” or “null” not as N/A. If the data is malformed in Power BI, try cleaning it first in python and then rerunning this function.
This function creates a new TMDL file defining the dataset in TMDL format and also in M code. The DiagramLayout and Model.tmdl files are updated to include refrences to the new dataset. Other dumb things: If you get an error when trying to open the .pbip file try changing the combatibility version to 1567 in the semanticmodel > definition > database.tmdl file. Thanks Microsoft for yet again doing a great job with backward compatibility lol. Dashboards created with the create_blank_dashboard() function start with the compatibility version set to 1567, so you should only have this problem with manually created dashboards. I may eventually add an automatic fix for this.
PBI_dashboard_creator.add_background_image module¶
- PBI_dashboard_creator.add_background_image.add_background_img(dashboard_path, page_id, img_path, alpha=100, scaling_method='Fit')¶
Add a background image to a dashboard page
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
page_id (str) – The unique id for the page you want to add the chart to. If you used this package’s functions it will be in the format page1, page2, page3, page4, etc. If you manually created the page it will be a randomly generated UUID. To find a page’s page id, consult the report > definition> pages > page.json file and look in the page order list.
img_path (str) – The path to the image you want to add. (Can be a relative path because the image is copied to the report folder). Allowed image types are whatever PBI allows manually, so probably at least jpeg and png
alpha (int) – The transparency of the background image. Must be a whole integer between 1 and 100.
scaling_method (str) – The method used to scale the image available options include [“Fit”, ]
PBI_dashboard_creator.add_local_csv module¶
- PBI_dashboard_creator.add_local_csv.add_csv(dashboard_path, data_path)¶
Add a locally stored CSV file to a dashboard
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
data_path (str) – The path where the csv file is stored. MUST BE A FULL PATH FOR THE M CODE TO WORK.
- Returns:
dataset_id: A randomly generated UUID that you can use to reference the datset.
The dataset path must be full (not relative path.) If using a relative path for the dashboard_path, the path must be within the current working directory. This function creates custom M code and is therefore more picky than pandas or Power BI desktop. The csv file should probably not have row numbers. (Any column without a column name will be renamed to “probably_an_index_column”) NA values must display as “NA” or “null” not as N/A. If the data is malformed in Power BI, try cleaning it first in python and then rerunning this function.
This function creates a new TMDL file defining the dataset in TMDL format and also in M code. The DiagramLayout and Model.tmdl files are updated to include refrences to the new dataset.
PBI_dashboard_creator.add_shape_map module¶
- PBI_dashboard_creator.add_shape_map.add_shape_map(dashboard_path, page_id, map_id, data_source, shape_file_path, map_title, location_var, color_var, color_breaks, color_palette, height, width, x_position, y_position, add_legend=True, z_position=6000, tab_order=-1001)¶
Add a map to a page
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
page_id (str) – The unique id for the page you want to add the map to. If you used this package’s functions it will be in the format page1, page2, page3, page4, etc. If you manually created the page it will be a randomly generated UUID. To find a page’s page id, consult the report > definition> pages > page.json file and look in the page order list.
map_id (str) – Please choose a unique id to use to identify the map. PBI defaults to using a UUID, but it’d probably be easier if you choose your own id.
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.
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
color_var (str) – The name of the column in data_source that you want to use for the color variable on the map
color_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.
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 color_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)
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.
y_position (int) – The y coordinate of where you want to put the map on the page. Origin is page’s top left corner.
z_position (int) – The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000
tab_order (int) – The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions)
This function creates a new cloropleth map on a page.
PBI_dashboard_creator.add_text_box module¶
- PBI_dashboard_creator.add_text_box.add_text_box(text, dashboard_path, page_id, text_box_id, height, width, x_position, y_position, z_position=6000, tab_order=-1001, text_align='left', font_weight='bold', font_size=32, font_color='#000000', background_color=None)¶
Add a text box to a page
- Parameters:
text (str) – The text you want to display in the box
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
page_id (str) – The unique id for the page you want to add the text box to. If you used this package’s functions it will be in the format page1, page2, page3, page4, etc. If you manually created the page it will be a randomly generated UUID. To find a page’s page id, consult the report > definition> pages > page.json file and look in the page order list.
text_box_id (str) – Please choose a unique id to use to identify the text box. PBI defaults to using a UUID, but it’d probably be easier if you choose your own id.
height (int) – Height of text box on the page
width (int) – Width of text box on the page
x_position (int) – The x coordinate of where you want to put the text box on the page. Origin is page’s top left corner.
y_position (int) – The y coordinate of where you want to put the text box on the page. Origin is page’s top left corner.
z_position (int) – The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000
tab_order (int) – The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions)
text_align (bool) – How would you like the text aligned (available options: “left”, “right”, “center”)
font_weight (str) – This is an option to change the font’s weight. Defaults to bold. Available options include: [“bold”]
font_size (int) – The font size in pts. Must be a whole integer. Defaults to 32 pt
font_color (str) – Hex code for the font color you’d like to use. Defaults to black (#000000)
background_color (str) – Hex code for the background color of the text box. Defaults to None (transparent)
This function creates a new text box on a page.
PBI_dashboard_creator.add_tmdl module¶
- PBI_dashboard_creator.add_tmdl.add_tmdl_dataset(dashboard_path, data_path=None, add_default_datetable=True)¶
Add a locally stored TMDL file to the dashboard
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
data_path (str) – The path where the tmdl file is stored.
add_default_datetable (boolean) – Do you want the TMDL file you add to be our team’s custom date table? This will allow you to create your own date heirarchies instead of using time intelligence
TMDL is a data storage format automatically created by power BI consisting of a table and column definitions and the M code used to generate the dataset. In practice this means that you can copy datasets between dashboards. You can use this function to automatically copy the TMDL files at scale Potential pitfalls: M needs full paths to load data. If the new dashboard doesn’t have access to the same data as the old dashboard, the data copying may fail.
PBI_dashboard_creator.create_blank_dashboard module¶
- PBI_dashboard_creator.create_blank_dashboard.create_new_dashboard(parent_dir, report_name)¶
Create a new dashboard in the specified folder
param str parent_dir: The path to the directory where you want to store the new dashboard param str report_name: Name of the report.
This function creates a power BI report in the specified parent directory. The dashboard can be opened and edited in Power BI desktop like normal, or be further modified progromatically using other functions in this package. The function creates a folder with the name report_name inside parent_dir with all the dashboard’s files. The dashboard uses a .pbip/.pbir format with TMDL enabled. To publish this type of dashboard you will need to either use git enabled workspaces OR convert to a .pbit template and then to a .pbix file before publishing These annoyances are worth it because the .pbir + TMDL format is the only one that allows real version control and programatic manipulation of the report using these functions. (.pbip uses mimified json by default and throws an error when it’s given unpacked json).
This dashboard turns off time intelligence and relationship autodection off by default
If you have the option I would recommend looking into a different web development framework (shiny, flask, etc) for building dashboards. Only use this package if you have to :D
PBI_dashboard_creator.create_date_hrcy module¶
- PBI_dashboard_creator.create_date_hrcy.create_date_hr(col_name, dataset_name, report_name, dashboard_path)¶
PBI_dashboard_creator.create_new_chart module¶
- PBI_dashboard_creator.create_new_chart.add_chart(dashboard_path, page_id, chart_id, chart_type, data_source, chart_title, x_axis_title, y_axis_title, x_axis_var, y_axis_var, y_axis_var_aggregation_type, x_position, y_position, height, width, tab_order=-1001, z_position=6000)¶
This function adds a new chart to a page in a power BI dashboard report.
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
page_id (str) – The unique id for the page you want to add the background image to. If you used this package’s functions it will be in the format page1, page2, page3, page4, etc. If you manually created the page it will be a randomly generated UUID. To find a page’s page id, consult the report > definition> pages > page.json file and look in the page order list.
chart_id (str) – Please choose a unique id to use to identify the chart. PBI defaults to using a UUID, but it’d probably be easier if you choose your own id.
chart_type (str) – The type of chart to build on the page. Known available types include: [“columnChart”,”barChart”, “clusteredBarChart”, ]
data_source (str) – The name of the dataset you want to use to build the chart. This corresponds to the dataset_name field in the add data functions. You must have already loaded the data to the dashboard.
chart_title (str) – Give your chart an informative title!:D
x_axis_title (str) – Text to display on the x axis
y_axis_title (str) – Text to display on the y axis
x_axis_var (str) – Column name of a column from data_source that you want to use for the x axis of the chart
y_axis_var (str) – Column name of a column from data_source that you want to use for the y axis of the chart
y_axis_var_aggregation_type (str) – Type of aggregation method you want to use to summarize y axis variable. Available options include” [“Sum”, “Count”, “Average”]
x_position (int) – The x coordinate of where you want to put the chart on the page. Origin is page’s top left corner.
y_position (int) – The y coordinate of where you want to put the chart on the page. Origin is page’s top left corner.
height (int) – Height of chart on the page
width (int) – Width of chart on the page
tab_order (int) – The order which the screen reader reads different elements on the page. Defaults to -1001 for now. (I need to do more to figure out what the numbers correpond to. It should also be possible to create a function to automatically order this left to right top to bottom by looping through all the visuals on a page and comparing their x and y positions)
z_position (int) – The z index for the visual. (Larger number means more to the front, smaller number means more to the back). Defaults to 6000
PBI_dashboard_creator.create_new_page module¶
- PBI_dashboard_creator.create_new_page.add_new_page(dashboard_path, page_name, title=None, subtitle=None)¶
Create a new blank dashboard page
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
page_name (str) – The display name for the page you just created. This is differnt from the page_id which is only used internally.
title (str) – Title to put at the top of the page. This under the hood calls the add_text_box() function. If you would like more control over the title’s appearance use that function instead.
sub_title (str) – Title to put at the top of the page. This under the hood calls the add_text_box() function. If you would like more control over the title’s appearance use that function instead.
- Returns:
new_page_id: The unique id for the page you just created. If you used this function it will be in the format page1, page2, page3, page4, etc. If you manually create a page it will be a randomly generated UUID. To find a page’s page id, consult the report > definition> pages > page.json file and look in the page order list.
PBI_dashboard_creator.create_tmdl module¶
- PBI_dashboard_creator.create_tmdl.create_tmdl(dashboard_path, dataset_name, dataset_id, dataset)¶
An internally called function that creates a TMDL file from a pandas dataframe
- Parameters:
dashboard_path (str) – The path where the dashboard files are stored. (This is the top level directory containing the .pbip file and Report and SemanticModel folders).
dataset_name (str) – The name of the dataset. This should be the basename of the original file without the extension. For example if you loaded “%userprofile%/documents/datasets/birds.csv”, the dataset name would be “birds”.
dataset_id (str) – The dataset’s UUID, this will be generated by the outer level function that calls create_tmdl().
dataset (DataFrame) – This is a pandas dataframe of the csv’s content. The pd.read_csv() function is called by the outer level function that calls create_tmdl().
- Returns:
col_attributes: A dictionary containing the name and type of all the columns in the dataset. This is needed to get the M code in the outer level function to work.
This function loops through all the dataframe’s columns, checks the column’s type (text, number, date), and generates the appropriate TMDL column definition for that type. Dates will only be recocognized as dates if they are in the format (YYYY-MM-DD) i.e. (1999-12-31). If your date is in another format please change in python before calling the add_csv functions.
PBI_dashboard_creator.update_diagramLayout module¶
- PBI_dashboard_creator.update_diagramLayout.update_diagramLayout(dashboard_path, dataset_name, dataset_id)¶
This is an internal function to add a dataset to the diagramLayout file when a new dataset is added.
:param str dashboard_path The path to the top level folder where you store all the report’s files. :param str dataset_name The name of the dataset you are adding :param str dataset_id The unique uuid that microsoft uses for the dataset. This is generated automatically within the add_data functions. return None
PBI_dashboard_creator.update_model_file module¶
- PBI_dashboard_creator.update_model_file.update_model_file(dashboard_path, dataset_name)¶
This is an internal function to add a dataset to the model.tmdl file when a new dataset is added. It assumes you want the new dataset to be loaded last.
:param str dashboard_path The path to the top level folder where you store all the report’s files. :param str dataset_name The name of the dataset you are adding return None