plots

main.plots

Plots for displaying database data.

Functions

create_bar_plot(title, months, values)

Creates a bar plot with dates versus values.

Parameters:

Name	Type	Description	Default
title	str	plot title	required
months	list[str]	a list of months to display on the x-axis	required
values	list[float]	a list of total charge values for the bar height indicate on the y-axis	required

Returns:

Type	Description
figure	Bokeh figure for the bar chart.

Source code in main/plots.py

def create_bar_plot(title: str, months: list[str], values: list[float]) -> figure:
    """Creates a bar plot with dates versus values.

    Args:
        title: plot title
        months: a list of months to display on the x-axis
        values: a list of total charge values for the bar height indicate on the y-axis

    Returns:
        Bokeh figure for the bar chart.
    """
    source = ColumnDataSource(data=dict(months=months, values=values))
    plot = figure(
        x_range=months,  # type: ignore[arg-type]
        title=title,
        width=1000,
        height=500,
        background_fill_color="#efefef",
    )
    plot.yaxis.axis_label = "Total charge (£)"
    plot.xaxis.axis_label = "Month-Year"
    plot.vbar(x="months", top="values", width=0.5, source=source)

    # Add basic tooltips to show monthly totals
    hover = HoverTool()
    hover.tooltips = [
        ("Month", "@months"),
        ("Total", "£@values"),
    ]
    plot.add_tools(hover)
    return plot

create_capacity_planning_plot(start_date, end_date)

Generates all the time series data and creates the capacity planning plot.

Includes all business days between the selected start and end date, inclusive of the start date. Time for the effort (aggregated over all projects) and capacity (aggregated over all users) are calculated.

Parameters:

Name	Type	Description	Default
start_date	datetime	datetime object representing the start of the plotting period	required
end_date	datetime	datetime object representing the end of the plotting period	required

Returns:

Type	Description
figure	Bokeh figure containing timeseries data.

Source code in main/plots.py

def create_capacity_planning_plot(start_date: datetime, end_date: datetime) -> figure:
    """Generates all the time series data and creates the capacity planning plot.

    Includes all business days between the selected start and end date, inclusive of
    the start date. Time for the effort (aggregated over all projects) and
    capacity (aggregated over all users) are calculated.

    Args:
        start_date: datetime object representing the start of the plotting period
        end_date: datetime object representing the end of the plotting period

    Returns:
        Bokeh figure containing timeseries data.
    """
    effort_timeseries = timeseries.get_effort_timeseries(start_date, end_date)
    capacity_timeseries = timeseries.get_capacity_timeseries(start_date, end_date)
    traces = [
        {
            "timeseries": effort_timeseries,
            "colour": "firebrick",
            "label": "Project effort",
        },
        {"timeseries": capacity_timeseries, "colour": "navy", "label": "Capacity"},
    ]
    plot = create_timeseries_plot(
        title="Project effort and team capacity over time", traces=traces
    )
    return plot

create_cost_recovery_plots()

Creates the cost recovery plot for the last year.

Provides an overview of team capacity over the past year and the project charging.

Returns:

Type	Description
tuple[figure, figure]	Tuple of Bokeh figures containing cost recovery data timeseries data and monthly charges for the past year.

Source code in main/plots.py

def create_cost_recovery_plots() -> tuple[figure, figure]:
    """Creates the cost recovery plot for the last year.

    Provides an overview of team capacity over the past year and the project charging.

    Returns:
        Tuple of Bokeh figures containing cost recovery data timeseries data and
            monthly charges for the past year.
    """
    dates = get_month_dates_for_previous_year()

    # Get start and end date as datetimes for capacity timeseries
    start_date = datetime.combine(dates[0][0], time.min)
    end_date = datetime.combine(dates[-1][1], time.min)

    # Create timeseries plot
    cost_recovery_timeseries, monthly_totals = timeseries.get_cost_recovery_timeseries(
        dates
    )
    capacity_timeseries = timeseries.get_capacity_timeseries(
        start_date=start_date, end_date=end_date
    )
    traces = [
        {
            "timeseries": cost_recovery_timeseries,
            "colour": "gold",
            "label": "Capacity used",
        },
        {"timeseries": capacity_timeseries, "colour": "navy", "label": "Capacity"},
    ]
    timeseries_plot = create_timeseries_plot(
        title=(
            f"Team capacity and project charging from {start_date.strftime('%B')} "
            f"{start_date.year} to {end_date.strftime('%B')} {end_date.year}"
        ),
        traces=traces,
    )

    # Create bar plot for monthly charges
    chart_months = [f"{date[0].strftime('%b')} {date[0].year}" for date in dates]
    bar_plot = create_bar_plot(
        title=(
            f"Monthly charges from {start_date.strftime('%B')} {start_date.year} to "
            f"{end_date.strftime('%B')} {end_date.year}"
        ),
        months=chart_months,
        values=monthly_totals,
    )

    return timeseries_plot, bar_plot

create_timeseries_plot(title, traces)

Creates a generic timeseries plot.

Parameters:

Name	Type	Description	Default
title	str	plot title	required
traces	list[dict[str, Any]]	a list of dictionaries with keys for the 'timeseries' data, 'label' and 'colour'	required

Returns:

Type	Description
figure	Bokeh figure containing timeseries data.

Source code in main/plots.py

def create_timeseries_plot(  # type: ignore[explicit-any]
    title: str,
    traces: list[dict[str, Any]],
) -> figure:
    """Creates a generic timeseries plot.

    Args:
        title: plot title
        traces: a list of dictionaries with keys for the 'timeseries' data, 'label' and
            'colour'

    Returns:
        Bokeh figure containing timeseries data.
    """
    # Create ColumnDataSource from trace data
    df = pd.DataFrame({trace["label"]: trace["timeseries"] for trace in traces})
    df.reset_index(inplace=True)
    source = ColumnDataSource(df)

    plot = figure(
        title=title,
        width=1000,
        height=500,
        background_fill_color="#efefef",
        x_axis_type="datetime",  # type: ignore[call-arg]
        tools="save,xpan,xwheel_zoom,reset",
    )
    plot.yaxis.axis_label = "Value"
    plot.xaxis.axis_label = "Date"
    for trace in traces:
        plot.line(
            "index",
            trace["label"],
            source=source,
            line_width=2,
            color=trace["colour"],
            legend_label=trace["label"],
        )
    plot.legend.click_policy = "hide"  # hides traces when clicked in legend
    return plot

html_components_from_plot(plot, prefix=None)

Generate HTML components from a Bokeh plot that can be added to the context.

Parameters:

Name	Type	Description	Default
plot	figure	Bokeh figure to be added to the context	required
prefix	str | None	optional prefix to use in the context keys	None

Source code in main/plots.py

def html_components_from_plot(
    plot: figure, prefix: str | None = None
) -> dict[str, str]:
    """Generate HTML components from a Bokeh plot that can be added to the context.

    Args:
        plot: Bokeh figure to be added to the context
        prefix: optional prefix to use in the context keys
    """
    script, div = components(plot)
    if prefix:
        return {
            f"{prefix}_script": script,
            f"{prefix}_div": div,
        }

    return {
        "script": script,
        "div": div,
    }