# 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 {doc}`date_ranges_ref_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 {doc}`appointments_table`), booked slots are marked as unavailable.  
- The proportion of booked slots is governed by the parameter `fill_rate` (see {doc}`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 {doc}`date_ranges_ref_date`).

---

## Example

```python
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. | {doc}`date_ranges_ref_date` |
| `working_days` | Determines which weekdays are active. | {doc}`calendar_structure` |
| `working_hours` | Defines daily start and end times. | {doc}`calendar_structure` |
| `appointments_per_hour` | Sets time granularity of slots. | {doc}`calendar_structure` |
| `fill_rate` | Controls the proportion of slots that become booked. | {doc}`booking_dynamics` |
| `booking_horizon` | Ensures sufficient future slot capacity. | {doc}`booking_dynamics` |
| `seed` | Controls reproducibility of slot ordering. | {doc}`randomness_and_noise` |

---

### Next steps
- Review {doc}`patients_table` to see who occupies generated slots.  
- Learn how to extend patient records with new variables in {doc}`custom_columns`.  
- Explore {doc}`appointments_table` to connect slot capacity with scheduled visits.