Appointments table

The appointments table is the primary output of the scheduler.
It integrates patient demographics, slot schedules, and simulated outcomes to create a realistic record of outpatient activity.

Each row corresponds to one appointment, containing demographic, temporal, and behavioral information.
For most analytical use cases (attendance rates, waiting times, utilization), this table can be used independently.

---

Overview

• File name: appointments.csv

• Generated by: AppointmentScheduler.generate_appointments()

• Schema: One row per scheduled appointment

• Linked to:

  • patients via patient_id

  • slots via slot_id

---

Core columns

Column	Type	Description
appointment_id	string	Unique sequential identifier for each appointment.
slot_id	string	Links the appointment to a generated slot (see slots table).
patient_id	string	Identifier of the assigned patient (see patients table).
scheduling_date	date	Date when the appointment was booked (see Booking dynamics).
scheduling_interval	int	Days between scheduling and appointment date, also known as lead time (see Booking dynamics).
appointment_date	date	Scheduled appointment date, derived from slot configuration.
appointment_time	time	Scheduled start time of the appointment (see Calendar structure).
status	string	Outcome of the appointment (attended, cancelled, did not attend, unknown) (see Attendance behavior).
sex	string	Patient’s sex, inherited from demographic data (see Patient demographics).
age	int	Patient age at the time of appointment, computed from dob.
age_group	string	Age bin derived from age (5-year intervals).
check_in_time	time	Actual arrival time for attended visits (see Appointment timing).
start_time	time	Time the consultation began (see Appointment timing).
end_time	time	Time the consultation ended (see Appointment timing).
waiting_time	float	Minutes between check-in and start (see Appointment timing).
appointment_duration	float	Duration of the consultation in minutes (see Appointment timing).

---

Generation logic

The appointment generation process integrates parameters from the patient, slot, and behavioral models.

1️⃣ Slot selection

Appointments are assigned to slots from the calendar grid:

• Governed by fill_rate, booking_horizon, and median_lead_time (Booking dynamics).

• The scheduler ensures the latest slot extends beyond ref_date + booking_horizon (Date ranges and reference date).

2️⃣ Patient assignment

Patients are drawn from the synthetic population:

• Population structure from Patient demographics.

• Visit frequency and first-attendance ratio from Patient flow.

• Demographic fields (sex, dob) are propagated into this table.

• age and age_group are computed dynamically based on appointment_date.

3️⃣ Attendance and outcomes

Appointment results follow status_rates (Attendance behavior):

• Default NHS-based proportions: 77.3% attended, 16.4% cancelled, 5.9% did not attend, 0.4% unknown.

• Cancelled visits may be rebooked depending on rebook_category (min, med, max).

4️⃣ Timing and punctuality

Temporal details are simulated according to operational studies (Appointment timing):

• check_in_time_mean defines early arrival (default -10 min).

• Start time accounts for operational delays and prior backlog.

• Duration is drawn from a Beta(1.48, 3.6) distribution (mean ≈ 17 min).

• Waiting time = start − check-in; duration = end − start.

---

Example

from medscheduler import AppointmentScheduler

sched = AppointmentScheduler(seed=42)
sched.generate()
appointments = sched.appointments_df.head(5)
print(appointments)

appointment_id	slot_id	patient_id	appointment_date	appointment_time	status	sex	age	waiting_time	appointment_duration
A000001	S000004	00002	2024-01-01	08:45:00	attended	Male	62	6.5	17.4
A000002	S000010	00005	2024-01-01	10:15:00	did not attend	Female	58	NaN	NaN
A000003	S000018	00003	2024-01-01	12:45:00	attended	Female	49	9.1	16.3
A000004	S000024	00001	2024-01-01	14:45:00	cancelled	Female	37	NaN	NaN
A000005	S000025	00004	2024-01-01	15:00:00	attended	Male	72	7.8	18.2

---

Related parameters

Parameter	Description	Reference
fill_rate	Proportion of booked slots.	Booking dynamics
booking_horizon, median_lead_time	Control scheduling distance and timing behavior.	Booking dynamics
status_rates, rebook_category	Determine appointment outcomes and rebooking rules.	Attendance behavior
check_in_time_mean	Controls average early arrival.	Appointment timing
appointments_per_hour, working_days, working_hours	Define time resolution of available slots.	Calendar structure
visits_per_year, first_attendance	Regulate patient flow and recurrence.	Patient flow
age_gender_probs, lower_cutoff, upper_cutoff	Define demographic composition.	Patient demographics
seed, noise	Control randomness and reproducibility.	Randomness and variability

---

Next steps

• Explore Slots table to see how appointments map to available calendar slots.

• Review Patients table to understand how appointments link to individual patients.

• For further customization, see Randomness and variability and Attendance behavior.