# medscheduler
**medscheduler** is a lightweight Python library for generating **fully synthetic**, **statistically plausible** outpatient appointment data. It simulates daily clinic calendars, patient cohorts, and appointment outcomes with healthcare‑aware defaults and strict validation.
Typical uses:
- Teaching and training in healthcare data science
- Prototyping dashboards, capacity planning, and scheduling models
- Reproducible experiments and benchmarks without PHI/PII risks
---
## Features
- Configurable clinic calendars (date ranges, working days/hours, capacity per hour)
- Patient cohort with realistic age–sex distributions
- Probabilistic scheduling: fill rate, first attendances, rebooking behavior
- Attendance outcomes with sensible defaults (attended, DNA, cancelled, unknown)
- Punctuality and check‑in time simulation
- Clear validation and informative error messages
- Minimal dependencies; optional plotting helpers
---
## Installation
From PyPI:
```bash
pip install medscheduler
```
Optional plots (Matplotlib):
```bash
pip install "medscheduler[viz]"
```
Requires Python 3.9 or newer.
---
## Quickstart
```python
from medscheduler import AppointmentScheduler
# Instantiate with defaults (seed for reproducibility)
sched = AppointmentScheduler(seed=42)
# Generate the three core tables
slots_df, appts_df, patients_df = sched.generate()
# Optionally export to CSV
sched.to_csv(
slots_path="slots.csv",
patients_path="patients.csv",
appointments_path="appointments.csv",
)
```
---
## Core concepts (overview)
- **Calendar & capacity:** `date_ranges`, `working_days`, `working_hours`, `appointments_per_hour`
- **Demand & booking:** `fill_rate`, `booking_horizon`, `median_lead_time`, `rebook_category`
- **Outcomes:** `status_rates` (attended / did not attend / cancelled / unknown)
- **Demographics:** `age_gender_probs`, `bin_size`, `lower_cutoff`, `upper_cutoff`, `truncated`
- **First attendances:** `first_attendance` (ratio)
- **Punctuality:** `check_in_time_mean` and related timing fields
- **Reproducibility:** `seed` controls the RNG
All defaults are overrideable at instantiation time.
---
## Outputs
`generate()` returns three pandas DataFrames:
- **slots** — canonical calendar of available appointment slots
Columns include: `slot_id`, `appointment_date`, `appointment_time`, `is_available`, …
- **appointments** — scheduled visits with status and timing fields
Columns include: `appointment_id`, `slot_id`, `status`, `scheduling_date`, `check_in_time`, `start_time`, `end_time`, …
- **patients** — synthetic cohort linked to appointments
Columns include: `patient_id`, `sex`, `age` (or `dob` and `age_group`), plus any custom columns you add
---
## 📊 Plotting Examples (optional)
If you installed the visualization extra (`pip install "medscheduler[viz]"`), you can generate quick diagnostic plots.
All functions return a Matplotlib `Axes` object. In Jupyter/Colab, plots are displayed automatically; in scripts, call `plt.show()`.
```python
import matplotlib.pyplot as plt
from medscheduler import AppointmentScheduler
from medscheduler.utils.plotting import (
plot_past_slot_availability,
plot_future_slot_availability,
plot_monthly_appointment_distribution,
plot_weekday_appointment_distribution,
plot_population_pyramid,
plot_appointments_by_status,
plot_appointments_by_status_future,
plot_status_distribution_last_days,
plot_status_distribution_next_days,
plot_scheduling_interval_distribution,
plot_appointment_duration_distribution,
plot_waiting_time_distribution,
plot_arrival_time_distribution
)
# Generate synthetic data
sched = AppointmentScheduler(seed=42)
slots_df, appts_df, patients_df = sched.generate()
# Weekday distribution of appointments
ax = plot_weekday_appointment_distribution(appts_df)
plt.show()
# Monthly distribution of appointments
ax = plot_monthly_appointment_distribution(appts_df)
plt.show()
# Age–sex pyramid for patients
ax = plot_population_pyramid(appts_df)
plt.show()
```
## Documentation & examples
A tutorial series of Jupyter notebooks (Quickstart, Core Calendar, Fill Rate & Rebooking, Status Rates, Check‑in Time, Age/Gender, Seasonality, Scenarios, Validation) will be published as project documentation.
For now, see the Quickstart above and the docstrings of `AppointmentScheduler` and utilities.
---
## Testing (for contributors)
```bash
pip install -e .[dev]
pytest -q
```
---
## License
MIT License. See `LICENSE` for details.
---
## Citation
If this library is helpful in your work, please cite:
> Carolina González Galtier. *medscheduler: A synthetic outpatient appointment simulator*, 2025.
> GitHub: https://github.com/carogaltier/medscheduler
Raw data
{
"_id": null,
"home_page": null,
"name": "medscheduler",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "healthcare, synthetic-data, appointments, scheduling, outpatient, simulation",
"author": "Carolina Gonz\u00e1lez Galtier",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b7/28/7e12fe745c4a4e391a9c69c91e28c13e89faffc294415ac636f627444901/medscheduler-0.1.7.tar.gz",
"platform": null,
"description": "# medscheduler\r\n\r\n**medscheduler** is a lightweight Python library for generating **fully synthetic**, **statistically plausible** outpatient appointment data. It simulates daily clinic calendars, patient cohorts, and appointment outcomes with healthcare\u2011aware defaults and strict validation.\r\n\r\nTypical uses:\r\n\r\n- Teaching and training in healthcare data science\r\n- Prototyping dashboards, capacity planning, and scheduling models\r\n- Reproducible experiments and benchmarks without PHI/PII risks\r\n\r\n---\r\n\r\n## Features\r\n\r\n- Configurable clinic calendars (date ranges, working days/hours, capacity per hour)\r\n- Patient cohort with realistic age\u2013sex distributions\r\n- Probabilistic scheduling: fill rate, first attendances, rebooking behavior\r\n- Attendance outcomes with sensible defaults (attended, DNA, cancelled, unknown)\r\n- Punctuality and check\u2011in time simulation\r\n- Clear validation and informative error messages\r\n- Minimal dependencies; optional plotting helpers\r\n\r\n---\r\n\r\n## Installation\r\n\r\nFrom PyPI:\r\n\r\n```bash\r\npip install medscheduler\r\n```\r\n\r\nOptional plots (Matplotlib):\r\n\r\n```bash\r\npip install \"medscheduler[viz]\"\r\n```\r\n\r\nRequires Python 3.9 or newer.\r\n\r\n---\r\n\r\n## Quickstart\r\n\r\n```python\r\nfrom medscheduler import AppointmentScheduler\r\n\r\n# Instantiate with defaults (seed for reproducibility)\r\nsched = AppointmentScheduler(seed=42)\r\n\r\n# Generate the three core tables\r\nslots_df, appts_df, patients_df = sched.generate()\r\n\r\n# Optionally export to CSV\r\nsched.to_csv(\r\n slots_path=\"slots.csv\",\r\n patients_path=\"patients.csv\",\r\n appointments_path=\"appointments.csv\",\r\n)\r\n```\r\n\r\n---\r\n\r\n## Core concepts (overview)\r\n\r\n- **Calendar & capacity:** `date_ranges`, `working_days`, `working_hours`, `appointments_per_hour`\r\n- **Demand & booking:** `fill_rate`, `booking_horizon`, `median_lead_time`, `rebook_category`\r\n- **Outcomes:** `status_rates` (attended / did not attend / cancelled / unknown)\r\n- **Demographics:** `age_gender_probs`, `bin_size`, `lower_cutoff`, `upper_cutoff`, `truncated`\r\n- **First attendances:** `first_attendance` (ratio)\r\n- **Punctuality:** `check_in_time_mean` and related timing fields\r\n- **Reproducibility:** `seed` controls the RNG\r\n\r\nAll defaults are overrideable at instantiation time.\r\n\r\n---\r\n\r\n## Outputs\r\n\r\n`generate()` returns three pandas DataFrames:\r\n\r\n- **slots** \u2014 canonical calendar of available appointment slots \r\n Columns include: `slot_id`, `appointment_date`, `appointment_time`, `is_available`, \u2026\r\n- **appointments** \u2014 scheduled visits with status and timing fields \r\n Columns include: `appointment_id`, `slot_id`, `status`, `scheduling_date`, `check_in_time`, `start_time`, `end_time`, \u2026\r\n- **patients** \u2014 synthetic cohort linked to appointments \r\n Columns include: `patient_id`, `sex`, `age` (or `dob` and `age_group`), plus any custom columns you add\r\n\r\n---\r\n\r\n## \ud83d\udcca Plotting Examples (optional)\r\n\r\nIf you installed the visualization extra (`pip install \"medscheduler[viz]\"`), you can generate quick diagnostic plots. \r\nAll functions return a Matplotlib `Axes` object. In Jupyter/Colab, plots are displayed automatically; in scripts, call `plt.show()`.\r\n\r\n```python\r\nimport matplotlib.pyplot as plt\r\nfrom medscheduler import AppointmentScheduler\r\nfrom medscheduler.utils.plotting import (\r\n plot_past_slot_availability,\r\n plot_future_slot_availability,\r\n plot_monthly_appointment_distribution,\r\n plot_weekday_appointment_distribution,\r\n plot_population_pyramid,\r\n plot_appointments_by_status,\r\n plot_appointments_by_status_future,\r\n plot_status_distribution_last_days,\r\n plot_status_distribution_next_days,\r\n plot_scheduling_interval_distribution,\r\n plot_appointment_duration_distribution,\r\n plot_waiting_time_distribution,\r\n plot_arrival_time_distribution\r\n)\r\n\r\n# Generate synthetic data\r\nsched = AppointmentScheduler(seed=42)\r\nslots_df, appts_df, patients_df = sched.generate()\r\n\r\n# Weekday distribution of appointments\r\nax = plot_weekday_appointment_distribution(appts_df)\r\nplt.show()\r\n\r\n# Monthly distribution of appointments\r\nax = plot_monthly_appointment_distribution(appts_df)\r\nplt.show()\r\n\r\n# Age\u2013sex pyramid for patients\r\nax = plot_population_pyramid(appts_df)\r\nplt.show()\r\n```\r\n\r\n## Documentation & examples\r\n\r\nA tutorial series of Jupyter notebooks (Quickstart, Core Calendar, Fill Rate & Rebooking, Status Rates, Check\u2011in Time, Age/Gender, Seasonality, Scenarios, Validation) will be published as project documentation. \r\nFor now, see the Quickstart above and the docstrings of `AppointmentScheduler` and utilities.\r\n\r\n---\r\n\r\n## Testing (for contributors)\r\n\r\n```bash\r\npip install -e .[dev]\r\npytest -q\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT License. See `LICENSE` for details.\r\n\r\n---\r\n\r\n## Citation\r\n\r\nIf this library is helpful in your work, please cite:\r\n\r\n> Carolina Gonz\u00e1lez Galtier. *medscheduler: A synthetic outpatient appointment simulator*, 2025. \r\n> GitHub: https://github.com/carogaltier/medscheduler\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Synthetic outpatient scheduling dataset generator (slots, patients, appointments).",
"version": "0.1.7",
"project_urls": {
"bug_tracker": "https://github.com/carogaltier/medscheduler/issues",
"repository": "https://github.com/carogaltier/medscheduler"
},
"split_keywords": [
"healthcare",
" synthetic-data",
" appointments",
" scheduling",
" outpatient",
" simulation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4fff6c6bc491a2e66079ad7c0af6f0b0dd7fab171dcb34e14fbfa3b9805ef6c7",
"md5": "31fb4bc037a126f4a7dae4b9f629d9de",
"sha256": "95808f6fa039af1f8b1276e268f6236240945ea121efd796e72426d8088d83a2"
},
"downloads": -1,
"filename": "medscheduler-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31fb4bc037a126f4a7dae4b9f629d9de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 45682,
"upload_time": "2025-09-11T16:27:44",
"upload_time_iso_8601": "2025-09-11T16:27:44.858451Z",
"url": "https://files.pythonhosted.org/packages/4f/ff/6c6bc491a2e66079ad7c0af6f0b0dd7fab171dcb34e14fbfa3b9805ef6c7/medscheduler-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b7287e12fe745c4a4e391a9c69c91e28c13e89faffc294415ac636f627444901",
"md5": "bf54937eff281bc6835965e3c5f87da6",
"sha256": "5106bc4a1221127085a2869b92052caf9d324ac1d4bac9faede7155716bf947d"
},
"downloads": -1,
"filename": "medscheduler-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "bf54937eff281bc6835965e3c5f87da6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45987,
"upload_time": "2025-09-11T16:27:46",
"upload_time_iso_8601": "2025-09-11T16:27:46.875533Z",
"url": "https://files.pythonhosted.org/packages/b7/28/7e12fe745c4a4e391a9c69c91e28c13e89faffc294415ac636f627444901/medscheduler-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 16:27:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "carogaltier",
"github_project": "medscheduler",
"github_not_found": true,
"lcname": "medscheduler"
}
JSON
