Slots table

The slots table represents the appointment calendar capacity — all potential appointment slots available within the simulation period.
Each row corresponds to one discrete time slot and contains its date, time, and availability status.
It serves as the structural foundation for scheduling and utilization analyses.

---

Overview

• File name: slots.csv

• Generated by: AppointmentScheduler.generate_slots()

• Schema: One row per potential appointment slot

• Linked to: appointments via slot_id

The table is primarily used for:

• Evaluating booking coverage and fill rates

• Studying daily and hourly utilization patterns

• Testing scheduling constraints and overbooking behavior

---

Core columns

Column	Type	Description
slot_id	string	Unique identifier for each generated slot.
appointment_date	date	Date of the available appointment.
appointment_time	time	Start time of the slot.
is_available	bool	Boolean flag (True/False) indicating whether the slot remains unbooked.

Note:
Slots are created independently from actual appointments.
Booked slots are later marked as unavailable when appointments are assigned.

---

Generation logic

Slots are generated according to the active calendar configuration and operational parameters of the scheduler.
The total number and distribution of slots depend on working days, working hours, and the number of appointments per hour.

Step 1 — Calendar structure

• Date ranges: Controlled by Date ranges and reference date.

• Working days: Specified via working_days (default: Monday–Friday).

• Working hours: Defined by working_hours (default: [(8, 18)] → 8:00–18:00).

• Appointments per hour: Controlled by appointments_per_hour (default: 4).

Together, these parameters define the time grid of available slots across the simulation period.

Step 2 — Slot capacity and availability

Each (date, time) combination represents a unique slot identified by slot_id.
Slots are then updated based on booking dynamics:

• Initially, all slots have is_available = True.

• When appointments are generated (see Appointments table), booked slots are marked as unavailable.

• The proportion of booked slots is governed by the parameter fill_rate (see Booking dynamics).

Step 3 — Reference date and future extension

If the latest date range does not extend far enough into the future to cover ref_date + booking_horizon,
the scheduler automatically extends the last range (see Date ranges and reference date).

---

Example

from medscheduler import AppointmentScheduler

sched = AppointmentScheduler(seed=42)
slots = sched.generate_slots()
print(slots.head())

Example output:

slot_id	appointment_date	appointment_time	is_available
S000001	2024-01-01	08:00:00	True
S000002	2024-01-01	08:15:00	True
S000003	2024-01-01	08:30:00	True
S000004	2024-01-01	08:45:00	False
S000005	2024-01-01	09:00:00	True

---

Related parameters

Parameter	Description	Reference
date_ranges, ref_date	Define the temporal window of the calendar.	Date ranges and reference date
working_days	Determines which weekdays are active.	Calendar structure
working_hours	Defines daily start and end times.	Calendar structure
appointments_per_hour	Sets time granularity of slots.	Calendar structure
fill_rate	Controls the proportion of slots that become booked.	Booking dynamics
booking_horizon	Ensures sufficient future slot capacity.	Booking dynamics
seed	Controls reproducibility of slot ordering.	Randomness and variability

---

Next steps

• Review Patients table to see who occupies generated slots.

• Learn how to extend patient records with new variables in Adding custom columns.

• Explore Appointments table to connect slot capacity with scheduled visits.