Patient State Module

Patient state management for AMD treatment simulation.

This module implements a state machine for tracking individual patient progression through AMD treatment protocols. It maintains all clinical and treatment-related state information and handles state transitions during clinic visits.

Key Concepts

  1. State Machine: - Tracks disease state (NAIVE, ACTIVE, INACTIVE, ATROPHIC) - Manages treatment phases (loading, maintenance, etc.) - Handles transitions between states based on clinical outcomes

  2. Clinical Tracking: - Visual acuity measurements (ETDRS letters 0-85) - Treatment history (injections, visits, responses) - Disease progression over time

  3. Visit Processing: - Handles different visit types and actions - Updates state based on clinical model outputs - Maintains complete visit history

Classes

PatientState

Core state machine class tracking all patient attributes and history

Key Methods

process_visit()

Main entry point for processing clinic visits and updating state

Examples

Basic Usage: >>> model = ClinicalModel() >>> patient = PatientState(“123”, “treat_and_extend”, 70, datetime.now()) >>> visit_data = patient.process_visit( … datetime.now(), … [“vision_test”, “injection”], … model … ) >>> print(f”Vision change: {visit_data[‘vision_change’]} letters”)

Advanced Usage: >>> # Custom treatment protocol with phase transitions >>> patient = PatientState(“456”, “custom_protocol”, 65, datetime.now()) >>> while patient.visits < 24: … visit_data = patient.process_visit( … datetime.now(), … [“vision_test”, “oct_scan”, “injection”], … model … ) … if visit_data[“vision_change”] < -5: … patient.update_phase(“intensified_treatment”)

Notes

  • Visual acuity measurements use ETDRS letters (0-85 range)

  • Disease states follow ClinicalModel definitions

  • Visit intervals are clamped between 4-52 weeks

  • All state changes are recorded in visit_history

class simulation.patient_state.PatientState(patient_id, protocol_name, initial_vision, start_time)[source]

Bases: object

Manages patient state and history throughout the simulation.

This class maintains the complete state of a patient including their treatment history, vision measurements, disease state, and scheduled visits. It provides methods for processing clinic visits and updating patient state based on treatments and disease progression.

Parameters:

  • patient_id (str) – Unique identifier for the patient

  • protocol_name (str) – Name of the treatment protocol

  • initial_vision (float) – Baseline visual acuity (ETDRS letters)

  • start_time (datetime) – Time when patient enters the simulation

Variables:

  • MAX_TREATMENTS_IN_PHASE (int) – Maximum allowed treatments in a phase (default: 1000)

  • patient_id (str) – Unique identifier for the patient

  • state (Dict) – Dictionary containing all patient state information including: - protocol: Treatment protocol name - current_step: Current treatment phase - visits: Total number of visits - injections: Total number of injections - baseline_vision: Initial visual acuity - current_vision: Current visual acuity - disease_state: Current disease state - last_visit_date: Date of last visit - next_visit_interval: Weeks until next visit - treatment_start: Date treatment began - visit_history: List of all visits - best_vision_achieved: Highest vision recorded - last_treatment_response: Most recent treatment response - treatment_response_history: List of all responses - weeks_since_last_injection: Weeks since last injection - last_injection_date: Date of last injection

Notes

The state dictionary maintains a complete record of the patient’s: - Treatment history and responses - Vision measurements over time - Disease progression - Visit schedule and history

__init__(patient_id, protocol_name, initial_vision, start_time)[source]
Parameters:

  • patient_id (str)

  • protocol_name (str)

  • initial_vision (float)

  • start_time (datetime)

process_visit(visit_time, actions, clinical_model)[source]

Process a clinic visit and update patient state.

This is the main state transition method that handles all visit processing and state updates. It coordinates vision testing, treatment administration, and disease state transitions.

Parameters:

  • visit_time (datetime) – Time of the visit (must be timezone-naive UTC)

  • actions (List[str]) – List of actions performed during the visit

  • clinical_model (ClinicalModel) – ClinicalModel instance for simulating vision changes and disease progression

Returns:

Dictionary containing detailed visit results:

  • baseline_vision: float - Vision before treatment

  • new_vision: float - Vision after treatment

  • actions_performed: List[str] - Completed actions

  • disease_state: str - Updated disease state

  • visit_type: str - Classification of visit

  • treatment_status: Dict - Current treatment status

Return type:

Dict[str, Any]

discontinue_treatment(visit_time, reason='protocol_decision')[source]

Discontinue active treatment and set up monitoring schedule.

Parameters:

  • visit_time (datetime) – Time when treatment is discontinued

  • reason (str, optional) – Reason for discontinuation (default: “protocol_decision”)

Return type:

None

Notes

Updates treatment status to inactive and sets up monitoring schedule.

resume_treatment()[source]

Resume treatment after discontinuation. :rtype: None

Notes

Called when recurrence is detected and treatment needs to be resumed.

Return type:

None

set_monitoring_schedule(weeks)[source]

Set the monitoring schedule for a patient after treatment discontinuation.

Parameters:

weeks (int) – Number of weeks between monitoring visits

Return type:

None

update_phase(new_phase)[source]

Update treatment phase.

Parameters:

new_phase (str) – Name of the new treatment phase

set_next_visit_interval(weeks)[source]

Set interval until next scheduled visit.

Parameters:

weeks (int) – Number of weeks until next visit

Notes

Interval is clamped between 4 and 52 weeks.

property visit_history: List[Dict]

Get patient’s visit history.

Returns:

List of visit records in chronological order

Return type:

List[Dict]

property current_vision: float

Get patient’s current visual acuity.

Returns:

Current vision in ETDRS letters

Return type:

float

property last_visit_date: datetime

Get date of patient’s last visit.

Returns:

Date and time of the most recent visit

Return type:

datetime

property next_visit_interval: int

Get weeks until next scheduled visit.

Returns:

Number of weeks until next scheduled visit

Return type:

int