Patient flow#

The parameters first_attendance and visits_per_year describe how frequently patients interact with the system and how new versus returning attendances are distributed.
Together, they control the flow of patients through the appointment cycle, determining whether visits correspond to new or follow-up encounters and how often each patient is expected to appear.

visits_per_year#

Defines the average number of appointments per patient per year.
This parameter controls overall encounter frequency and scales the generated patient pool relative to total appointment volume.

Format#

Type: float
Default: 1.2
Typical range: 0.5–4.0
Maximum allowed: 12.0 (as defined in constants.py)

Validation rules#

  • Must be a positive float ≤ MAX_VISITS_PER_YEAR.

  • Values greater than 12 trigger a ValueError since they imply unrealistic contact frequency for outpatient settings.

  • If omitted, the default value (1.2) is applied.

How it works#

This parameter determines how many total appointments are expected per patient per simulated year.
Higher values increase patient revisit probability, while lower values simulate populations with fewer follow-ups.
In combination with first_attendance, it shapes the balance between new and returning encounters.

The default value of 1.2 visits per year reflects contemporary trends in primary care visit rates in the United States, as reported by Rao et al. (2019) [1].
That study found a national decline in average visits per person—from 1.5 in 2008 to 1.2 in 2015—indicating reduced face-to-face utilization over time.

Examples#

Use the default rate (1.2 visits per year)

from medscheduler import AppointmentScheduler

sched = AppointmentScheduler(visits_per_year=1.2)
sched.generate()

Simulate a population with more frequent visits

sched = AppointmentScheduler(visits_per_year=3.0)
sched.generate()

first_attendance#

Defines the proportion of appointments that correspond to first attendances (i.e., new patients).
This determines the fraction of visits that originate from new patients rather than follow-up encounters.

Format#

Type: float
Default: 0.325 (32.5%)
Source: Derived from NHS England Hospital Outpatient Activity 2023–24, Summary Report 2 (stored in constants.py).

Validation rules#

  • Must be a float in the range [0, 1].

  • Values outside this range raise a ValueError.

  • If None, defaults to the NHS-derived proportion (0.325).

How it works#

During simulation, each generated appointment is tagged as either first attendance or follow-up according to this ratio.
A higher value produces more new patient records and a broader simulated cohort; lower values favor repeat visits.
The scheduler uses this proportion to control both patient generation and re-identification across cycles.

For example:

  • With first_attendance = 0.3, approximately 30% of appointments represent new patients.

  • The remaining 70% are attributed to previously seen individuals, preserving continuity and realism.

Examples#

Use the default NHS first attendance rate

from medscheduler import AppointmentScheduler

sched = AppointmentScheduler(first_attendance=0.325)
sched.generate()

Simulate a specialist clinic with mostly follow-ups

sched = AppointmentScheduler(first_attendance=0.1)
sched.generate()

References#

[1] Rao, A., Shi, Z., Ray, K. N., Mehrotra, A., & Ganguli, I. (2019).
National Trends in Primary Care Visit Use and Practice Capabilities, 2008–2015.
Annals of Family Medicine, 17(6), 538–544.
https://doi.org/10.1370/afm.2474

[2] NHS England (2024). Hospital Outpatient Activity 2023–24: Summary Report 2.
https://files.digital.nhs.uk/34/18846B/hosp-epis-stat-outp-rep-tabs-2023-24-tab.xlsx

Next steps#

On this page
Show Source