Medscheduler

Medscheduler is a Python library for generating fully synthetic outpatient scheduling datasets. It creates realistic yet privacy-preserving data for education, research, and prototyping, enabling healthcare operations analysis without privacy concerns.

Introduction

Access to real-world healthcare data is often constrained by privacy regulations, ethical considerations, and administrative barriers. Most clinical records contain sensitive or identifiable information, requiring complex approval processes that can hinder innovation and reproducibility.

Synthetic data provides a practical alternative - artificially generated datasets that replicate the statistical properties of real-world data while containing no identifiable patient information. Medscheduler simulates outpatient appointment systems through a parameterized scheduler that generates plausible demographic distributions, booking behaviors, and attendance patterns. Default configurations are informed by NHS England outpatient statistics and peer-reviewed research on punctuality, rebooking, and visit frequency.

Key features

• End-to-end synthetic scheduling pipeline (slots, patients, appointments)

• Configurable parameters for calendars, slot density, fill rates, rebooking, attendance, and punctuality

• Privacy-preserving by design - safe for sharing and collaboration

• Compatible with pandas and matplotlib for immediate analysis and visualization

• Modular and extensible architecture

Use cases

• Education & Training: Health data science and operational analytics coursework

• Prototyping & Development: Testing scheduling algorithms, dashboards, and predictive models

• Research & Reproducibility: Open research without data access restrictions

Simulation overview

The generator models a synthetic outpatient scheduling system with three core components:

• Slots: Configurable daily calendars with working days, operating hours, and slot density.

• Patients: Synthetic registry with realistic age-sex distributions derived from NHS data.

• Appointments: Booked appointments linking patients to slots with probabilistic attendance, cancellations, and rebooking outcomes.

Outputs are provided as pandas DataFrames with optional CSV export functionality. The modular codebase allows for customization of simulation parameters and behavioral assumptions through class arguments or extended methods, supporting adaptation to various healthcare systems and research requirements.

User Guide

The User Guide introduces the main concepts of medscheduler. It provides step-by-step instructions to install the library, run a quickstart example, and explore the generated outputs. This section also explains key configuration parameters and how to adapt the scheduler to different teaching or research contexts.

• User Guide
  • What is Medscheduler?
  • Installation
  • Quickstart
  • Outputs overview
  • Customization options

API Reference

The API Reference is the technical specification of the package. It contains detailed documentation of the AppointmentScheduler class, its constructor arguments, and all public methods. Utility modules and constants are also documented here, serving as a complete reference for developers who need fine-grained control.

• API Reference
  • AppointmentScheduler
  • Date ranges and reference date
  • Calendar structure
  • Seasonality and weights
  • Booking dynamics
  • Attendance behavior
  • Patient flow
  • Patient demographics
  • Appointment timing
  • Randomness and variability
  • Appointments table
  • Slots table
  • Patients table
  • Adding custom columns

Visualization

The Visualization section focuses on functions that help analyze and display the generated data. It shows how to produce plots of slot availability, patient demographics, and appointment outcomes. These visualizations are useful for dashboards, teaching, and exploratory data analysis.

• Visualization
  • Summarizing Slot Availability
  • Visualizing Past Slot Availability
  • Visualizing Future Slot Availability
  • Visualizing Monthly Appointment Distribution
  • Visualizing Appointment Distribution by Weekday
  • Visualizing Recent Appointment Status Trends
  • Visualizing Upcoming Appointment Status Forecast
  • Visualizing Appointment Outcomes by Status
  • Visualizing Upcoming Appointment Outcomes
  • Visualizing Scheduling Interval Distribution
  • Visualizing Population Distribution by Age and Sex
  • Visualizing Patient Visit Frequency
  • Visualizing First Attendance Distribution
  • Visualizing Appointment Duration Distribution
  • Visualizing Patient Waiting Time Distribution
  • Visualizing Patient Arrival Time Patterns
  • Visualizing Custom Column Distributions

Examples

The Examples section demonstrates practical scenarios using medscheduler. Each example includes code snippets, expected outputs, and guidance on interpreting results. Topics include attendance analysis, cancellations, overbooking strategies, and integration with analytics tools.

• Examples
  • Simulation Windows and Seasonal Activity
  • Calendar Structure and Daily Capacity
  • Booking Dynamics and Utilization Patterns
  • Attendance Behavior and Rebooking Scenarios
  • Patient Flow and Demographic Structure
  • Appointment Timing and Daily Flow
  • Adding Custom Categorical Variables