Merge pull request #57 from matt-graham/mmg/notebooks-in-docs

Include notebooks in generated documentation site

Author: zmek

docs/api.md

@@ -1,11 +1,3 @@
 # API reference
 
-`patientflow` provides a comprehensive set of tools for predicting short-term hospital bed demand using real-time data. This API reference documents all public modules, classes, and functions available in the PatientFlow package.
-
-Each function and class is documented with usage examples, parameter descriptions, and return value information to help you implement effective patient flow monitoring and prediction systems.
-
-Getting Started
-
-For common usage, we recommend starting with the notebooks section, which provides step-by-step examples. This API reference serves as a comprehensive technical resource once you're familiar with the basic concepts.
-
 ::: patientflow

docs/notebooks/0_Set_up_your_environment.md

@@ -0,0 +1,88 @@
+# Set up your environment
+
+Skip this notebook if you are just browsing.
+
+In this notebook I will explain where the code looks for data and saves models and media by default, and suggest how to set up your environment. There are two README files that may be useful:
+
+- [Repository README](https://github.com/UCL-CORU/patientflow#) in the root of the repository
+- [Notebooks README](README.md) in this folder
+
+## Set notebook to reload functions every time a cell is fun
+
+This is useful if you make any changes to any underlying code
+
+```python
+# Reload functions every time
+%load_ext autoreload
+%autoreload 2
+```
+
+## Check that the patientflow package has been installed
+
+```python
+try:
+   import patientflow
+   print(f"✓ patientflow {patientflow.__version__} imported successfully")
+except ImportError:
+   print("❌ patientflow not found - please check installation instructions in README")
+   print("   pip install -e '.[test]'")
+except Exception as e:
+   print(f"❌ Error: {e}")
+```
+
+    ✓ patientflow 0.1.0 imported successfully
+
+## Set project_root variable
+
+The variable called project_root tells the notebooks where the patientflow repository resides on your computer. All paths in the notebooks are set relative to project_root. There are various ways to set it, which are described in the notebooks [README](README.md).
+
+```python
+from patientflow.load import set_project_root
+project_root = set_project_root()
+```
+
+    Inferred project root: /Users/zellaking/Repos/patientflow
+
+## Set file paths
+
+Now that you have set the project root, you can specify where the data will be loaded from, where images and models are saved, and where to load the config file from. By default, a function called `set_file_paths()` sets these as shown here.
+
+```python
+# Basic checks
+print(f"patientflow version: {patientflow.__version__}")
+print(f"Repository root: {project_root}")
+
+# Verify data access
+data_folder_name = 'data-synthetic'
+data_file_path = project_root / data_folder_name
+if data_file_path.exists():
+    print("✓ Synthetic data found")
+else:
+    print("Synthetic data not found - check repository structure")
+```
+
+    patientflow version: 0.1.0
+    Repository root: /Users/zellaking/Repos/patientflow
+    ✓ Synthetic data found
+
+The function will set file paths to default values, as shown here. You can override these as required.
+
+```python
+from patientflow.load import set_file_paths
+data_file_path, media_file_path, model_file_path, config_path = set_file_paths(project_root,
+               data_folder_name=data_folder_name)
+```
+
+    Configuration will be loaded from: /Users/zellaking/Repos/patientflow/config.yaml
+    Data files will be loaded from: /Users/zellaking/Repos/patientflow/data-synthetic
+    Trained models will be saved to: /Users/zellaking/Repos/patientflow/trained-models/synthetic
+    Images will be saved to: /Users/zellaking/Repos/patientflow/trained-models/synthetic/media
+
+## Summary
+
+In this notebook you have seen
+
+- how to configure your environment to run these notebooks
+- where the notebooks expect to find data, and where they will save models and media, by default
+
+Now you are ready to explore the data that has been provided with this repository

docs/notebooks/1_Meet_the_users_of_our_predictions.md

@@ -0,0 +1,70 @@
+# Introducing our users
+
+This repository offers predictive modelling to support the management of patient flow in hospitals.
+
+## What is patient flow?
+
+Hospitals refer to the streams of patients arriving and leaving as ‘patient flow’. Unplanned admissions create the ‘emergency’ flow, and the hospital must accommodate that flow alongside a flow of ‘elective’ or planned admissions. Sometimes outflows are reduced because patients are waiting for care to become available in another setting.
+
+There are various ways people are admitted to a hospital specialty:
+
+- via the Accident & Emergency Department, which is referred to by hospitals as the ED (Emergency Department). Some patients are admitted after visiting Same Day Emergency Care (SDEC). Here, we refer to the combined flows from ED and SDEC as coming via the ED
+- as planned (or elective) admissions
+- as an emergency admission via another route, like a transfer from another hospital
+- as an internal transfer from another specialty in the same hospital
+
+And various ways people leave a hospital specialty:
+
+- as a discharge from hospital, to home or another care setting
+- as an internal transfer to another specialty within the same hospital
+- as a death
+
+If patient flow works well, each patient will receive timely and appropriate care from the right specialty team, without undue delays. An example of poor patient flow is when incoming patients experience delays to admission because inpatients are not being discharged.
+
+Due to imbalances in admissions and discharges, pressures can build up in certain parts of the hospital, while other parts remain relatively less pressured. When one specialty is under pressure, new patients may be housed in the wrong ward - ie a ward that is not dedicated to the specialty they are under. In this case they are referred to as 'outliers'. Outlying is not ideal; evidence indicates it can lead to worse clinical outcomes and longer stays in hospitals.
+
+Hospitals strive to keep patient flow going, across all specialties, so far as they are able to.
+
+## Who is responsible for managing patient flow?
+
+All hospital staff share responsibility for patient flow, but a team of bed managers takes primary responsibility for managing it. Bed managers are usually senior nurses with a good understanding of each patient's likely care needs. Their work involves responding to rapidly changing situations caused by delays in patient care, infection outbreaks, excess demand for beds, and other incidents.
+
+To keep track of the changing situation, bed managers convene "flow huddles" three times a day. In these huddles, staff from the emergency department and from each ward meet with bed managers to discuss patients coming in (as either emergency or planned admissions), and review which inpatients are likely to be discharged. The flow huddles provide a picture of likely areas of pressure on beds.
+
+If bed pressures are anticipated, bed managers can take action by trying to accelerate discharges, or opening up temporary beds and finding staff to cover them, or temporarily divert ambulances to another hospital. These decisions have consequences for patients, staff and other hospitals.
+
+## What information do bed managers use to manage patient flow?
+
+Bed managers' decisions depend on having a clear picture of current capacity and imminent pressures. They like to know how many beds will be needed for new patients by the end of the day or shift, and how many will become available during that time. To predict how many beds will be needed today, they assume the number will be the same as yesterday. To work out how many patients will leave, they apply a simple rule based on patients' expected dates of discharge.
+
+These are simple rules of thumb, that are based on static information. Many hospitals have Electronic Health Records (EHRs), into which data are being entered all the time. That up-to-date information could provide a better view; bed managers' understanding of the current situation, and their projection of how it will develop, could be refreshed as new information comes into the EHR.
+
+## What modelling is useful to bed managers?
+
+I'm [Zella King](https://github.com/zmek/), a health data scientist in the Clinical Operational Research Unit (CORU) at University College London. I started working with University College London Hospital (UCLH) in 2020 because the hospital wanted to make better use of the data streaming into its EHR. My colleague Prof Sonya Crowe led a small project to create a prototype of a predictive model of emergency demand that used real-time data. Through that project, and over the subsequent years, we have come to understand the needs of bed managers from predictive modelling.
+
+_What bed managers want from predictive models_
+
+- **Predictions issued at the times of day they need them:**
+  Our users have a routine where they prepare a situation report of hospital capacity five times each day, and have flow huddles three times a day. They wanted predictions of bed demand to be available to them in the preparation of the reports, and at the flow huddles.
+
+- **Predictions over a rolling window:**
+  The current heuristics used widely across the NHS rely on daily averages, which means that a patient flow meeting will focus on projections up to midnight that day. A rolling prediction of 8 to 12 hours is more useful, because it enables conversation about what needs to be done during the current day or night shift, in order to head off pressures later.
+
+- **Output at aggregate level rather than individual:**
+  It is common for researchers using statistics or Machine Learning to produce models that predict each patient's probability of admission. However, this is not useful for bed managers because, when managing capacity, they are mainly interested in overall numbers of beds needed, rather than whether any particular patient will be admitted.
+
+- **Predictions that are based on real-time data from the Electronic Health Record (EHR):**
+  Predictive models can be trained on historical patterns of admissions and discharges. However, if they can make use of real-time data from the EHR, bed managers will have a better sense of today's demand, rather than that of a typical day.
+
+- **A breakdown of demand by specialty:**
+  Knowing that the whole hospital is going to be short of beds is somewhat useful and does give a sense of the scale of the problem. More precise information - about which specialties are most affected - makes it easier to pinpoint where action is needed.
+
+- **Some sense of the uncertainty of predictions:**
+  Simple heuristics give bed managers a single number to work with. For example, if 50 patients were admitted yesterday, they might plan for 50 today. This doesn't show how likely the number 50 is; could it be 46 or 54? A good model will give a sense of uncertainty around the suggested number of beds. Ironically, knowing the spread of the uncertainty gives a more certain picture.
+
+## What are the elements of patient flow?
+
+Above, I said that bed managers want a breakdown of demand by specialty. Let's break down the sources of that demand.
+
+I intend that this repository will show how to model all of these flows eventually.