# 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 {doc}`booking_dynamics`). |
| `scheduling_interval` | int | Days between scheduling and appointment date, also known as *lead time* (see {doc}`booking_dynamics`). |
| `appointment_date` | date | Scheduled appointment date, derived from slot configuration. |
| `appointment_time` | time | Scheduled start time of the appointment (see {doc}`calendar_structure`). |
| `status` | string | Outcome of the appointment (`attended`, `cancelled`, `did not attend`, `unknown`) (see {doc}`attendance_behavior`). |
| `sex` | string | Patient’s sex, inherited from demographic data (see {doc}`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 {doc}`appointment_timing`). |
| `start_time` | time | Time the consultation began (see {doc}`appointment_timing`). |
| `end_time` | time | Time the consultation ended (see {doc}`appointment_timing`). |
| `waiting_time` | float | Minutes between check-in and start (see {doc}`appointment_timing`). |
| `appointment_duration` | float | Duration of the consultation in minutes (see {doc}`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` ({doc}`booking_dynamics`).  
- The scheduler ensures the latest slot extends beyond `ref_date + booking_horizon` ({doc}`date_ranges_ref_date`).  

### 2️⃣ Patient assignment
Patients are drawn from the **synthetic population**:
- Population structure from {doc}`patient_demographics`.  
- Visit frequency and first-attendance ratio from {doc}`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` ({doc}`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 ({doc}`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

```python
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. | {doc}`booking_dynamics` |
| `booking_horizon`, `median_lead_time` | Control scheduling distance and timing behavior. | {doc}`booking_dynamics` |
| `status_rates`, `rebook_category` | Determine appointment outcomes and rebooking rules. | {doc}`attendance_behavior` |
| `check_in_time_mean` | Controls average early arrival. | {doc}`appointment_timing` |
| `appointments_per_hour`, `working_days`, `working_hours` | Define time resolution of available slots. | {doc}`calendar_structure` |
| `visits_per_year`, `first_attendance` | Regulate patient flow and recurrence. | {doc}`patient_flow` |
| `age_gender_probs`, `lower_cutoff`, `upper_cutoff` | Define demographic composition. | {doc}`patient_demographics` |
| `seed`, `noise` | Control randomness and reproducibility. | {doc}`randomness_and_noise` |

---

### Next steps
- Explore {doc}`slots_table` to see how appointments map to available calendar slots.  
- Review {doc}`patients_table` to understand how appointments link to individual patients.  
- For further customization, see {doc}`randomness_and_noise` and {doc}`attendance_behavior`.