Dev

_quarto.yml

@@ -66,6 +66,7 @@ website:
           - pages/guide/setup/environment.qmd
           - pages/guide/setup/package.qmd
           - pages/guide/setup/code_structure.qmd
+          - pages/guide/setup/conceptual.qmd
         - section: "Model inputs"
           contents:
           - pages/guide/inputs/input_modelling.qmd

index.qmd

@@ -33,7 +33,7 @@ The material is designed for analysts, researchers, and students in health and o
 
 ::: {.pale-blue}
 
-"The DES RAP Book was a valuable resource in our transition to open-source DES modelling. It provided us with a step-by-step structure to follow and guidance on best practice for writing code, tests and documentation for our package. Our model is being using in the Midlands, and beyond, for understanding future demand and capacity within Kidney Replacement Therapy." - **Lucy Morgan, Analytics Manager at The Strategy Unit**.
+"The DES RAP Book was a valuable resource in our transition to open-source DES modelling. It provided us with a step-by-step structure to follow and guidance on best practice for writing code, tests and documentation for our package. [Our model](https://www.strategyunitwm.nhs.uk/news/planning-rising-renal-demand-simulating-capacity-across-care-system) is being using in the Midlands, and beyond, for understanding future demand and capacity within Kidney Replacement Therapy." - **Lucy Morgan, Analytics Manager at The Strategy Unit**.
 
 :::
 
@@ -50,6 +50,12 @@ After working through this resource, you will be able to:
 * Improve **style, documentation, and automation** with linting, docstrings, and GitHub Actions.
 * **Collaborate and share** your work effectively, including code review, licensing, citation, changelogs, and archiving.
 
+::: {.pale-blue}
+
+"The DES RAP Book is a phenomenal resource that is being used extensively to enhance the training content of the national Health Service Modelling Associates (HSMA) Programme.  It provides clear, well-structured instructions and easy to follow examples that will ensure the approaches we teach to the next generation of health data scientists are reproducible, rigorous and transparent.  As well as informing the content of the training we will be signposting to this book as an invaluable reference for our students as they take their first steps into the world of Discrete Event Simulation" - **Dr Daniel Chalk, Senior Research Fellow at the University of Exeter**.
+
+:::
+
 > If you use the DES RAP book in your teaching, research, or training, we'd love to hear about it. Please [get in touch](/pages/guide/further_info/feedback.qmd) to share how you've used the material, suggest improvements, or point us to example models or case studies that others might find helpful.
 >
 > Educators and trainers can adopt the book as a complete syllabus for a short course or reuse individual chapters as standalone teaching units (for example, sessions on RAP, testing, packaging, or sharing models),  and should cite the resource when they do so in line with the provided citation below. The accompanying code is released under an MIT licence, and the text is available under a CC BY-SA 4.0 licence, allowing reuse and adaptation with appropriate attribution.

pages/guide/further_info/conclusion.qmd

@@ -53,14 +53,7 @@ Remember, these are **examples**, not prescriptions. They're not perfect, and th
 
 ### Make your own model
 
-The best way to solidify what you've learned is to apply it. When planning your model, remember that a good simulation starts with **conceptual modelling**. As defined in Robinson (2007):
-
-> "The conceptual model is a non-software specific description of the simulation model that is to be developed, describing the objectives, inputs, outputs, content, assumptions and simplifications of the model."
-
-Some good resources on conceptual modelling include:
-
-* Robinson, Stewart. 2007. "Chapter 5: Conceptual Modelling." In Simulation: The Practice of Model Development and Use, 63–75. John Wiley & Sons.
-* Robinson, Stewart. 2007. "Chapter 6: Developing the Conceptual Model." In Simulation: The Practice of Model Development and Use, 77–93. John Wiley & Sons.
+The best way to solidify what you've learned is to apply it. When planning your model, remember that a good simulation starts with [conceptual modelling](/pages/guide/setup/conceptual.qmd).
 
 <br>
 

pages/guide/model/patients.qmd

@@ -58,11 +58,7 @@ library(simmer)
 
 ## Preparation: conceptual modelling
 
-Before writing any code, it's important that you have defined a conceptual model of the process, as this will guide the design of your simulation. You also need to have defined all the necessary parameters. With these essentials in place, the process of building the simulation can start.
-
-We will not describe how to design conceptual models in this book, but there are lots of resources available online, such as:
-
-> Chwif, L., Banks, J., de Moura Filho, J. P., & Santini, B. (2013). A framework for specifying a discrete-event simulation conceptual model. Journal of Simulation, 7(1), 50–60. <https://doi.org/10.1057/jos.2012.18>.
+Before writing any code, it's important that you have defined a [conceptual model](/pages/guide/setup/conceptual.qmd) of the process, as this will guide the design of your simulation. You also need to have defined all the necessary parameters. With these essentials in place, the process of building the simulation can start.
 
 In this book, we will building a simple model where patients arrive, wait to see a doctor, and then leave.
 

pages/guide/setup/conceptual.qmd

@@ -0,0 +1,167 @@
+---
+title: Conceptual modelling
+bibliography: conceptual_resources/references.bib
+date: "2026-05-19T10:26:08+00:00"
+---
+
+<!-- Hide as no python-content or r-content blocks -->
+<style>
+      #quarto-announcement {
+        display: none !important;
+      }
+</style>
+
+::: {.pale-blue}
+
+**Learning objectives:**
+
+* Decide when discrete-event simulation is an **appropriate technique** for a problem.
+* Understand what a **conceptual model** is and identify the key components of a conceptual model.
+* Apply **model simplification** strategies to build the simplest model that meets study objectives.
+
+**Acknowledgements:** This page was written with reference to the excellent content on conceptual modelling in @Robinson2014.
+
+:::
+
+## What is a conceptual model?
+
+A **conceptual model** is a description of the simulation to be developed. It sits between the real-world problem and the computer implementation, capturing *what* the model needs to do before *how* it will be coded (@Robinson2014).
+
+Developing a conceptual model involves:
+
+1. Determining whether simulation is the appropriate modelling approach.
+2. Describing the model itself - its purpose, boundaries, data, and assumptions.
+
+This description serves as a reference point during model development, for [verification](/pages/guide/verification_validation/verification_validation.qmd), and for any future collaborators or users of the model.
+
+## Is DES the right approach?
+
+Before designing your DES, it is worth asking whether it is the right approach.
+
+The ISPOR Simulation Modeling Emerging Good Practices Task Force developed the **SIMULATE checklist** to assist in deciding whether simulation methods are appropriate to address specific health system problems (@Marshall2015):
+
+| SIMULATE | Does your problem require: |
+| - | --- |
+| **S**ystem | Modeling multiple *events, relationships, and stakeholders* representing health care delivery *processes*? |
+| **I**nteractions | Including *nonlinear* or *spatial* relationships among stakeholders and their context that influence *behaviors* and make *outcomes* in the system difficult to anticipate? |
+| **M**ultilevel | Modeling a health care delivery problem from strategic, tactical, or operational perspectives? |
+| **U**nderstanding | Modeling a complex problem to improve patient-centered care that cannot be solved *analytically*? |
+| **L**oops | Modeling *feedback* loops that change the behavior of *future interactions* and the consequences for the delivery system? |
+| **A**gents | Modeling multiple stakeholders with *behavioral* properties that *interact* and *change* the performance of the system? |
+| **T**ime | *Time-dependent* and *dynamic transitions* in a health care delivery system, either between or within health care *system levels* or in *health status* change? |
+| **E**mergence | Considering the *intended and unintended* consequences of health system interventions to address *policy resistance* and achieve target outcomes? |
+
+<br>
+
+If you answer **yes** to several of these, some form of dynamic simulation is likely justified. The checklist doesn't tell you which method to use. There are three main options, and the simplest way to distinguish them is to consider what the unit of interest is...
+
+| Method | You are modelling... |
+| - | -- |
+| **Discrete-event simulation** | Individual entities (e.g., patients, calls, vehicles) moving through a process and competing for resources |
+| **System dynamics** | Aggregate quantities and how they influence each other over time through feedback loops | 
+| **Agent-based simulation** | Individuals whose behaviour adapts based on what others around them are doing |
+
+For most healthcare operational problems (e.g., scheduling, capacity planning, pathway design), DES is the natural starting point. The others become relevant when feedback loops or adaptive behaviour are central to the question, rather than incidental features of it.
+
+In practice, the boundaries between these methods are blurry. The goal at the conceptual modelling stage is not to pick the "correct" method with certainty, but to make a **justified and reasonable choice** given the question you are asking.
+
+## Components of a conceptual model
+
+@Robinson2014 break a conceptual model down into five key components:
+
+* Objectives
+* Inputs
+* Outputs
+* Content
+* Assumptions and simplifications
+
+### Objectives
+
+State clearly what question the model is being built to answer, and what constraints apply. If you cannot write a one-sentence answer to "what decision will this model inform?", the objective is not ready yet.
+
+There are two levels of objectives to consider:
+
+::: {.blue-table}
+
+| Level | Description |
+| - | -- |
+| **Modelling objectives** | What do you hope to achieve by the end of the study? What targets are you aiming for? What scenarios are in scope? |
+| **Project objectives** | Practical constraints that shape the model including timescale, required flexibility, run speed, visual display requirements, and ease of use for intended users. |
+
+:::
+
+### Inputs
+
+List the **parameters you plan to vary**, and the ranges you'll vary them over.
+
+Ideally, also decide *how* inputs will be supplied (e.g., within a script, read from a file, entered via a user interface) since this affect how the model code is designed. This will depend on the needs of the intended users.
+
+### Outputs
+
+List the **statistics the model needs to produce** (e.g. mean waiting time, resource utilisation, queue length) and decide how they will be reported.
+
+Outputs should map directly onto the objectives: if a statistic does not help answer the question, it probably does not need to be there.
+
+### Content
+
+Model content has two dimensions (@Robinson2014):
+
+::: {.blue-table}
+
+| Dimension | Description |
+| - | -- |
+| **Scope** | Which parts of the system are included in the model. |
+| **Level of detail** | How finely to represent each included component. |
+
+:::
+
+Content can be represented using:
+
+- Component lists
+- Process flow diagrams
+- Activity cycle diagrams
+- Logic flow diagrams
+
+### Assumptions and simplifications
+
+Document every place where you depart from the real system, distinguishing two types (@Robinson2014):
+
+::: {.blue-table}
+
+| Concept | Definition |
+| - | -- |
+| **Assumption** | Arise from incomplete knowledge - you do not know exactly how something works, so you use the best available information. |
+| **Simplification** | Deliberate design choices - you *could* model something in more detail, but you opt for a simpler representation. |
+
+::::
+
+Both need to be recorded. Assumptions may need revisiting if better data become available; simplifications should be justified against their impact on validity.
+
+## What makes a good model?
+
+A good model (@Robinson2014):
+
+- Produces **sufficiently accurate results** for the purpose at hand (*validity*).
+- Is **believed** by the clients and stakeholders (*credibility*).
+- Is **feasible to build** within constraints of available data, time, and expertise.
+- Has **utility** - it is easy enough to use, sufficiently flexible, adequately visual, and quick to run.
+
+Overarching all four criteria is the requirement to build the **simplest model possible** to meet the objectives of the simulation study. Simpler models are faster to build and run, easier to understand and explain, and require less data.
+
+Models can be simplified by removing components or by representing components more simply - for example (@Robinson2014):
+
+* Replace a detailed section of an operation with a simple time delay.
+* Rather than modelling a component explicitly, sample its effect from a statistical distribution (e.g. sample a delivery time directly rather than simulating the delivery process).
+* Omit rare events from the base model; optionally explore them as separate scenarios.
+* Divide a large model into two or more sub-models that can be run independently. This improves run speed but is only successful when there is no feedback between parts.
+
+A simplification is **good** if it brings the benefits of faster model development and run speed (feasibility and utility) while maintaining sufficient accuracy (validity) and credibility [@Robinson2014].
+
+A practical way to calibrate this is to **prototype**: build the simplest plausible model first, then add scope or detail incrementally and check whether outputs change meaningfully. Stop when they stop changing.
+
+## References
+
+::: {#refs}
+:::
+
+<br><br>

pages/guide/setup/conceptual_resources/references.bib

@@ -0,0 +1,24 @@
+@book{Robinson2014,
+  author    = {Robinson, Stewart},
+  title     = {Simulation: The Practice of Model Development and Use},
+  edition   = {3},
+  year      = {2024},
+  publisher = {Bloomsbury Academic},
+  address   = {London},
+  isbn      = {9781352011401}
+}
+
+@article{Marshall2015,
+	title = {Applying {Dynamic} {Simulation} {Modeling} {Methods} in {Health} {Care} {Delivery} {Research}—{The} {SIMULATE} {Checklist}: {Report} of the {ISPOR} {Simulation} {Modeling} {Emerging} {Good} {Practices} {Task} {Force}},
+	volume = {18},
+	issn = {1098-3015},
+	url = {https://www.sciencedirect.com/science/article/pii/S1098301514047640},
+	doi = {https://doi.org/10.1016/j.jval.2014.12.001},
+	abstract = {Health care delivery systems are inherently complex, consisting of multiple tiers of interdependent subsystems and processes that are adaptive to changes in the environment and behave in a nonlinear fashion. Traditional health technology assessment and modeling methods often neglect the wider health system impacts that can be critical for achieving desired health system goals and are often of limited usefulness when applied to complex health systems. Researchers and health care decision makers can either underestimate or fail to consider the interactions among the people, processes, technology, and facility designs. Health care delivery system interventions need to incorporate the dynamics and complexities of the health care system context in which the intervention is delivered. This report provides an overview of common dynamic simulation modeling methods and examples of health care system interventions in which such methods could be useful. Three dynamic simulation modeling methods are presented to evaluate system interventions for health care delivery: system dynamics, discrete event simulation, and agent-based modeling. In contrast to conventional evaluations, a dynamic systems approach incorporates the complexity of the system and anticipates the upstream and downstream consequences of changes in complex health care delivery systems. This report assists researchers and decision makers in deciding whether these simulation methods are appropriate to address specific health system problems through an eight-point checklist referred to as the SIMULATE (System, Interactions, Multilevel, Understanding, Loops, Agents, Time, Emergence) tool. It is a primer for researchers and decision makers working in health care delivery and implementation sciences who face complex challenges in delivering effective and efficient care that can be addressed with system interventions. On reviewing this report, the readers should be able to identify whether these simulation modeling methods are appropriate to answer the problem they are addressing and to recognize the differences of these methods from other modeling approaches used typically in health technology assessment applications.},
+	number = {1},
+	journal = {Value in Health},
+	author = {Marshall, Deborah A. and Burgos-Liz, Lina and IJzerman, Maarten J. and Osgood, Nathaniel D. and Padula, William V. and Higashi, Mitchell K. and Wong, Peter K. and Pasupathy, Kalyan S. and Crown, William},
+	year = {2015},
+	keywords = {decision making, dynamic simulation modeling, health care delivery, methods},
+	pages = {5--16},
+}

pages/guide/setup/environment.qmd

@@ -428,6 +428,20 @@ dependencies:
 
 When working on a project from scratch, you will often build up your environment organically and iteratively as you find more packages you want to use.
 
+#### Deleting the environment
+
+To delete your environment, first deactivate it:
+
+```{.bash}
+conda deactivate envname
+```
+
+You can then run:
+
+```{.bash}
+conda remove -n envname --all
+```
+
 ::::
 
 :::: {.r-content}

pages/guide/style_docs/documentation.qmd

@@ -196,7 +196,9 @@ Creating a small website to accompany your repository can be a really clear and
 
 ::: {.python-content}
 
-There are many tools available. We would recommend **Quarto** as a modern, versatile tool with support for multiple programming language - we used it to create this website.
+There are many tools available. We would recommend **Quarto** as a modern, versatile tool with support for multiple programming language - we used it to create this website. We have a separate tutorial on how to set up a Quarto website - check it out here: <https://pythonhealthdatascience.github.io/quarto-tutorial/>
+
+<iframe width="100%" height="500" src="https://pythonhealthdatascience.github.io/quarto-tutorial/" title="Quarto tutorial"></iframe>
 
 Some older solutions include Jupyter Book, Sphinx and MkDocs.