Charts

remapp.interface.chart_functions.calc_facet_rows_and_height(df, facet_col_name, facet_col_wrap)

Calculates the required total chart height and the number of facet rows. Each row has a hard-coded height of 500 pixels.

Parameters

  • df – Pandas DataFrame containing the data

  • facet_col_name – string containing the DataFrame column name containing the facet names

  • facet_col_wrap – int representing the number of subplots to have on each row

Returns

two-element list containing the chart height in pixels (int) and the number of facet rows (int)

remapp.interface.chart_functions.calc_histogram_bin_data(df, value_col_name, n_bins=10)

Calculates histogram bin label text, bin boundaries and bin mid-points

Parameters

  • df – the Pandas DataFrame containing the data

  • value_col_name – (string )name of the DataFrame column that contains the values

  • n_bins – (int) the number of bins to use

Returns

a three element list containing the bin labels, bin boundaries and bin mid-points

remapp.interface.chart_functions.calculate_colour_sequence(scale_name='RdYlBu', n_colours=10)

Calculates a sequence of n_colours from the matplotlib colourmap scale_name

Parameters

  • scale_name – string containing the name of the matplotlib colour scale to use

  • n_colours – int representing the number of colours required

Returns

list of hexadecimal colours from a matplotlib colormap

remapp.interface.chart_functions.construct_over_time_charts(df, params, group_by_physician=None)

Construct a Plotly line chart of average values over time, optionally grouped by performing physician name. For “boxplot” a plotly boxplot of values over time is returned instead of an plotly line chart.

Parameters

  • df – the Pandas DataFrame containing the data

  • params – a dictionary of processing parameters

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["name_title"] – (string) name title

  • params["df_value_col"] – (string) DataFrame column containing values

  • params["value_title"] – (string) y-axis title

  • params["df_date_col"] – (string) DataFrame column containing dates

  • params["date_title"] – (string) date title

  • params["facet_title"] – (string) subplot title

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["average_choices"] – list of strings containing requred averages (“mean”, “median”, “boxplot”)

  • params["time_period"] – string containing the time period to average over; “A” (years), “Q” (quarters), “M” (months), “W” (weeks), “D” (days)

  • params["grouping_choice"] – (string) “series” or “system”

  • params["colourmap"] – (string) colourmap to use

  • params["filename"] – (string) default filename to use for plot bitmap export

  • params["facet_col_wrap"] – (int) number of subplots per row

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • group_by_physician – boolean flag to set whether to group by physician name

Returns

a dictionary containing a combination of [“mean”], [“median”] and [“boxplot”] entries, each of which contains a Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if params[“return_as_dict”] is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.create_dataframe(database_events, field_dict, data_point_name_lowercase=None, data_point_name_remove_whitespace_padding=None, data_point_value_multipliers=None, char_wrap=500, uid=None)

Creates a Pandas DataFrame from the supplied database records. names fields are made categorical to save system memory Any missing (na) values in names fields are set to Blank

Parameters

  • database_events – the database events

  • field_dict – a dictionary of lists, each containing database field names to include in the DataFrame. The dictionary should include “names”, “values”, “dates”, “times” and optionally “system” items

  • data_point_name_lowercase – boolean flag to determine whether to make all “names” field values lower case

  • data_point_name_remove_whitespace_padding – boolean flag to determine whether to strip whitespace

  • data_point_value_multipliers – list of float valuse to multiply each “values” field value by

  • uid – string containing database field name which contains a unique identifier for each record

Returns

a Pandas DataFrame with a column per required field

remapp.interface.chart_functions.create_dataframe_aggregates(df, df_name_cols, df_agg_col, stats_to_use=None)

Creates a Pandas DataFrame with the specified statistics (mean, median, count, for example) grouped by x-ray system name and by the list of provided df_name_cols.

Parameters

  • df – Pandas DataFrame containing the raw data; it must have an “x_ray_system_name” column

  • df_name_cols – list of strings representing the DataFrame column names to group by

  • df_agg_col – string containing the DataFrame column over which to calculate the statistics

  • stats_to_use – list of strings containing the statistics to calculate, such as “mean”, “median”, “count”

Returns

Pandas DataFrame containing the grouped aggregate data

remapp.interface.chart_functions.create_dataframe_time_series(df, df_name_col, df_value_col, df_date_col='study_date', time_period='M', average_choices=None, group_by_physician=None)

Creates a Pandas DataFrame time series of average values grouped by x_ray_system_name and df_name_col

Parameters

  • df – the Pandas DataFrame containing the raw data

  • df_name_col – string containing the DataFrame columnn name used to group the data

  • df_value_col – string containing the DataFrame column containing the values to be averaged

  • df_date_col – string containing the DataFrame column containing the dates

  • time_period – string containing the time period to average over; “A” (years), “Q” (quarters), “M” (months), “W” (weeks), “D” (days)

  • average_choices – list of strings containing one or both of “mean” and “median”

  • group_by_physician – boolean flag to set whether to group by physician

Returns

Pandas DataFrame containing the time series of average values grouped by system and name

remapp.interface.chart_functions.create_dataframe_weekdays(df, df_name_col, df_date_col='study_date')

Creates a Pandas DataFrame of the number of events in each day of the week, and in hour of that day.

Parameters

  • df – Pandas DataFrame containing the raw data; it must have a “study_time” and “x_ray_system_name” column

  • df_name_col – string containing the df column name to group the results by

  • df_date_col – string containing the df column name containing dates

Returns

Pandas DataFrame containing the number of studies per day and hour grouped by name

remapp.interface.chart_functions.create_freq_sorted_category_list(df, df_name_col, sorting)

Create a sorted list of categories for frequency charts. Makes use of Pandas DataFrame sort_values (https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.sort_values.html).

sorting[0] sets sort direction

sorting[1] used to determine field to sort on: “name” sorts by df_name_col; otherwise sorted by “x_ray_system_name”

Parameters

  • df – Pandas DataFrame containing the data

  • df_name_col – DataFrame column containing the category names

  • sorting – 2-element list. [0] sets sort direction, [1] used to determine which field to sort on

Returns

dictionary with key df_name_col and a list of sorted categories as the value

remapp.interface.chart_functions.create_sorted_category_list(df, df_name_col, df_value_col, sorting)

Create a sorted list of categories for scatter and over-time charts. The data is grouped by df_name_col and the mean and count calculated for each. The grouped DataFrame is then sorted according to the provided sorting. Makes use of Pandas DataFrame sort_values (https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.sort_values.html).

sorting[0] sets sort direction

sorting[1] used to determine sort order: “name” sorts by df_name_col; otherwise sorted by “x_ray_system_name”

Parameters

  • df – Pandas DataFrame containing the data

  • df_name_col – DataFrame column containing the category names. Used to group the data

  • df_value_col – DataFrame column containing values to count and calculate the mean

  • sorting – 2-element list. [0] sets sort direction, [1] used to determine which field to sort on

Returns

dictionary with key df_name_col and a list of sorted categories as the value

remapp.interface.chart_functions.csv_data_barchart(fig, params)

Calculates a Pandas DataFrame containing chart data to be used for csv download

Parameters

  • fig – Plotly figure containing the data to extract

  • params – a dictionary of parameters

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["name_axis_title"] – (string) title for the name data

  • params["value_axis_title"] – (string) title for the value data

  • params["facet_col"] – (string) DataFrame column used to split data into subgroups

Returns

DataFrame containing the data for download

remapp.interface.chart_functions.csv_data_frequency(fig, params)

Calculates a Pandas DataFrame containing chart data to be used for csv download

Parameters

  • fig – Plotly figure containing the data to extract

  • params – a dictionary of parameters; must include “x_axis_title”

Returns

DataFrame containing the data for download

Adapted from: https://discuss.streamlit.io/t/heres-a-download-function-that-works-for-dataframes-and-txt/4052

Generates a link to download the given object_to_download.

object_to_download (str, pd.DataFrame): The object to be downloaded. download_filename (str): filename and extension of file. e.g. mydata.csv, some_txt_output.txt download_link_text (str): Text to display for download link.

Examples:

download_link(YOUR_DF, 'YOUR_DF.csv', 'Click here to download data!')

download_link(YOUR_STRING, 'YOUR_STRING.txt', 'Click here to download your text!')

remapp.interface.chart_functions.empty_dataframe_msg(params=None)

Returns a string containing an HTML DIV with a message warning that the DataFrame is empty

Parameters

params – parameters which may contain a custom_msg_line

Returns

string containing an html div with the empty DataFrame message

remapp.interface.chart_functions.failed_chart_message_div(custom_msg_line, e)

Returns a string containing an HTML DIV with a failed chart message

Parameters

  • custom_msg_line – string containing a custom line to add to the message

  • e – Python error object

Returns

string containing the message in an HTML DIV

remapp.interface.chart_functions.global_config(filename, height_multiplier=1.0, height=1080, width=1920)

Creates a Plotly global configuration dictionary. The parameters all relate to the chart bitmap that can be saved by the user.

Parameters

  • filename – string containing the file name to use if the user saves the chart as a graphic file

  • height_multiplier – floating point value used to scale the chart height

  • height – int value for the height of the chart graphic file

  • width – int value for the width of the chart graphic file

Returns

a dictionary of Plotly options

remapp.interface.chart_functions.plotly_barchart(df, params, csv_name='OpenREM chart data.csv')

Create a plotly bar chart

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["average_choice"] – (string) DataFrame column containing values (“mean” or “median”)

  • params["value_axis_title"] – (string) y-axis title

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["name_axis_title"] – (string) x-axis title

  • params["facet_col"] – (string) DataFrame column used to create subplots

  • params["facet_col_wrap"] – (int) number of subplots per row

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["colourmap"] – (string) colourmap to use

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • params["filename"] – (string) default filename to use for plot bitmap export

  • csv_name – (string) default filename to use for plot csv export

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if params[“return_as_dict”] is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_barchart_weekdays(df, df_name_col, df_value_col, name_axis_title='', value_axis_title='', colourmap='RdYlBu', filename='OpenREM_workload_chart', facet_col_wrap=3, sorting_choice=None, return_as_dict=False)

Create a plotly bar chart of event workload

Parameters

  • df – Pandas DataFrame containing the data

  • df_name_col – (string) DataFrame column containing categories

  • df_value_col – (string) DataFrame column containing values

  • name_axis_title – (string) x-axis title

  • value_axis_title – (string) y-axis title

  • colourmap – (string) colourmap to use

  • filename – (string) default filename to use for plot bitmap export

  • facet_col_wrap – (int) number of subplots per row

  • sorting_choice – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • return_as_dict – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if “return_as_dict” is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_binned_statistic_barchart(df, params)

Create a plotly binned statistic bar chart

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_category_col"] – (string) DataFrame column containing categories

  • params["df_facet_col"] – (string) DataFrame column used to create subplots

  • params["facet_title"] – (string) Subplot title

  • params["facet_col_wrap"] – (int) number of subplots per row

  • params["user_bins"] – list of ints containing bin edges for binning

  • params["df_category_col"] – (string) DataFrame column containing categories

  • params["df_x_value_col"] – (string) DataFrame column containing x data

  • params["df_y_value_col"] – (string) DataFrame column containing y data

  • params["x_axis_title"] – (string) Title for x-axis

  • params["y_axis_title"] – (string) Title for y-axis

  • params["stat_name"] – (string) “mean” or “median”

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["colourmap"] – (string) colourmap to use

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • params["filename"] – (string) default filename to use for plot bitmap export

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if params[“return_as_dict”] is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_boxplot(df, params)

Produce a plotly boxplot

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_value_col"] – (string) DataFrame column containing values

  • params["value_axis_title"] – (string) x-axis title

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["name_axis_title"] – (string) y-axis title

  • params["df_facet_col"] – (string) DataFrame column used to create subplots

  • params["df_facet_col_wrap"] – (int) number of subplots per row

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["colourmap"] – (string) colourmap to use

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if params[“return_as_dict”] is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_frequency_barchart(df, params, csv_name='OpenREM chart data.csv')

Create a plotly bar chart of event frequency

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_x_axis_col"] – (string) DataFrame column containing categories

  • params["x_axis_title"] – (string) x-axis title

  • params["groupby_cols"] – list of strings with DataFrame columns to group data by

  • params["grouping_choice"] – (string) “series” or “system”

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["legend_title"] – (string) legend title

  • params["facet_col"] – (string) DataFrame column used to create subplots

  • params["facet_col_wrap"] – (int) number of subplots per row

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • params["colourmap"] – (string) colourmap to use

  • params["filename"] – (string) default filename to use for plot bitmap export

  • csv_name – (string) default filename to use for plot csv export

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if “return_as_dict” is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_histogram_barchart(df, params)

Create a plotly histogram bar chart

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_value_col"] – (string) DataFrame column containing values

  • params["value_axis_title"] – (string) y-axis title

  • params["df_facet_col"] – (string) DataFrame column used to create subplots

  • params["df_category_name_list"] – string list of each category name

  • params["df_facet_col_wrap"] – (int) number of subplots per row

  • params["n_bins"] – (int) number of hisgogram bins to use

  • params["colourmap"] – (string) colourmap to use

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["global_max_min"] – (boolean) flag to calculate global max and min or per-subplot max and min

  • params["legend_title"] – (string) legend title

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • params["filename"] – (string) default filename to use for plot bitmap export

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if params[“return_as_dict”] is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_scatter(df, params)

Create a plotly scatter chart

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["df_x_col"] – (string) DataFrame column containing x values

  • params["df_y_col"] – (string) DataFrame column containing y values

  • params["sorting_choice"] – 2-element list. [0] sets sort direction, [1] used to determine which field to sort

  • params["grouping_choice"] – (string) “series” or “system”

  • params["legend_title"] – (string) legend title

  • params["facet_col_wrap"] – (int) number of subplots per row

  • params["colourmap"] – (string) colourmap to use

  • params["x_axis_title"] – (string) x-axis title

  • params["y_axis_title"] – (string) y-axis title

  • params["filename"] – (string) default filename to use for plot bitmap export

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if “return_as_dict” is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.plotly_set_default_theme(theme_name)

A short method to set the plotly chart theme

Parameters

theme_name – the name of the theme

Returns

remapp.interface.chart_functions.plotly_timeseries_linechart(df, params)

Create a plotly line chart of data over time

Parameters

  • df – Pandas DataFrame containing the data

  • params – a dictionary of parameters

  • params["df_facet_col"] – (string) DataFrame column used to create subplots

  • params["df_facet_col_wrap"] – (int) number of subplots per row

  • params["facet_title"] – (string) subplot title

  • params["df_value_col"] – (string) DataFrame column containing values

  • params["value_axis_title"] – (string) y-axis title

  • params["colourmap"] – (string) colourmap to use

  • params["colourmap"] – (string) colourmap to use

  • params["df_date_col"] – (string) DataFrame column containing dates

  • params["df_count_col"] – (string) DataFrame column containing frequency data

  • params["df_name_col"] – (string) DataFrame column containing categories

  • params["legend_title"] – (string) legend title

  • params["name_axis_title"] – (string) x-axis title

  • params["return_as_dict"] – (boolean) flag to trigger return as a dictionary rather than a HTML DIV

  • params["filename"] – (string) default filename to use for plot bitmap export

Returns

Plotly figure embedded in an HTML DIV; or Plotly figure as a dictionary (if “return_as_dict” is True); or an error message embedded in an HTML DIV if there was a ValueError when calculating the figure

remapp.interface.chart_functions.save_fig_as_html_div(fig, filename, active=False)

Saves the Plotly figure as an HTML file containing a single DIV. The file is saved on the OpenREM server in MEDIA_ROOTchartsyyyymmdd. Viewing the saved file requires an active internet connection as the Plotly JavaScript library is not included in the file.

This method is not currently accessible to an OpenREM user or administrator - it is present to assist developers when producing example charts for the OpenREM documentation. It must be manually activated by setting active=True in the method definition.

Parameters

  • fig – a Plotly figure

  • filename – (string )the filename to use

  • active – (boolean) to set whether to save the figure