Visualizing Upcoming Appointment Outcomes#

Displays the percentage distribution of scheduled and cancelled appointments for dates after the scheduler’s reference date (ref_date). This forward-looking chart helps evaluate upcoming workload and cancellation patterns in the near future.

Function Overview#

Function: medscheduler.utils.plotting.plot_appointments_by_status_future(df, *, scheduler, date_col='appointment_date', status_col='status')

Inputs:

  • df (pd.DataFrame) — Appointment table containing at least the specified date_col and status_col.

  • scheduler (AppointmentScheduler) — Must include a ref_date attribute indicating the start of the forecast window.

  • date_col (str) — Column name with appointment dates. Default: "appointment_date".

  • status_col (str) — Column name with appointment statuses. Default: "status".

Returns: matplotlib.axes.Axes — Vertical bar chart showing the proportion of future appointments by status.

Validation & error handling:

  • Missing columns → raises ValueError("DataFrame must contain columns: …").

  • Scheduler without ref_date → raises ValueError("Scheduler must have a ref_date attribute.").

  • No future rows (date > ref_date) → _empty_plot("No future appointments available after reference date.").

Output Description#

  • X-axis: Appointment statuses (scheduled, cancelled, etc.)

  • Y-axis: Percentage of future appointments.

  • Bars: Color-coded by status using the Medscheduler palette:

    • scheduled = #CD77B6

    • cancelled = #B3C1F2

  • Annotations: Displays percentage values above bars.

  • Style: Compact design optimized for dashboards, with dashed Y-grid, no top/right spines, and left-aligned title.

This visualization provides a concise overview of upcoming clinic activity, enabling quick detection of overbooking, cancellations, or low utilization in the days following the reference date.

Example#

from medscheduler import AppointmentScheduler
from medscheduler.utils.plotting import plot_appointments_by_status_future

# Generate future appointment dataset
sched = AppointmentScheduler()
slots_df, appts_df, patients_df = sched.generate()

# Visualize distribution of future appointments by status
ax = plot_appointments_by_status_future(appts_df, scheduler=sched)
ax.figure.show()  # optional when running interactively

Output preview:
The chart below presents the percentage distribution of future appointments by status, showing scheduled versus cancelled proportions relative to the reference date.

Future Appointments by Status#

Next Steps#

On this page
Show Source