dev-workflow.qmd

# A simulation modeller as a software developer: a workflow {#dev-workflow}

## The "big picture"

Agent-based modelling (ABM) is more than coding—it is an iterative and cumulative research process that benefits from software engineering principles. Each simulation model can be seen as a small research *software project*, and the modeller as its *developer*.
Thinking like a software developer helps to ensure that the model is:

* **Reproducible:** anyone (including your future self) can run it and obtain the same results.
* **Transparent:** the model’s assumptions, mechanisms, and implementation are easy to inspect.
* **Collaborative:** colleagues can contribute, review, or reuse your code and data.
* **Extensible:** improvements, corrections, or new experiments can be added without breaking the project.
* **Reusable:** others can build on your work.

We can recast the generic modelling steps into a software development workflow represented as:

1. **Conceptual model:** Defines the system, processes, and hypotheses. Identify inputs (data), outputs, and validation criteria.  
2. **Implementation or "implemented model":** Translate the conceptual model into executable code (e.g., in NetLogo). Expanded through "coding sessions".  
4. **Version control:** After each coding session, commit your changes with Git (locally) and push them to a remote repository in GitHub. When working directly in the remote repository in your browser, you will need to commit changes to each file individually. When changing your model in NetLogo, you will have to open the `.nlogo` or `.nlogox` file in a text editor and copy-paste its contents into the remote version (not recommended).
5. **Experimentation:** Run simulations manually in NetLogo, or systematic experiments using NetLogo’s *BehaviorSpace* or custom procedures in NetLogo, external files (e.g., datasets generated in R), or executing NetLogo from R.  
6. **Analysis:** Process and visualise simulation outputs in R, write up results.  
7. **Publication**: publish and share your complete project repository, including analysis outputs (specific outputs can be used for an article).

```{r, echo=FALSE}
DiagrammeR::grViz("
digraph dev_workflow {

graph [layout = dot, rankdir = TB, overlap = false]

node [shape = box]
A [label = '💡 Conceptualise']
B [label = '📝 Design']
C [label = '🧱 Programme']
D [label = '🔄 Commit changes']
E [label = '🧪 Experiment/simulate']
F [label = '📊 Analyse']
G [label = '📢 Publish']

A -> B -> C -> D -> E -> F -> G
}")
```

In practice, these stages overlap and repeat. Conceptual choices affect implementation; analysis reveals bugs or design flaws; revisions are documented in version control.

```{r, echo=FALSE}
DiagrammeR::grViz("
digraph dev_workflow {

graph [layout = dot, rankdir = TB, overlap = false]

node [shape = box]
A [label = '💡 Conceptualise']
B [label = '📝 Design']
C [label = '🧱 Programme']
D [label = '🔄 Commit changes']
E [label = '🧪 Experiment/simulate']
F [label = '📊 Analyse']
G [label = '📢 Publish']
H [label = '🔁 Revise', shape = circle]

A -> B -> C -> D -> E -> F -> G
C -> H D -> H E -> H F -> H G -> H
H -> B H -> C H -> D H -> E H -> F H -> G
}")
```

The goal is *incremental improvement* rather than perfection at once. Treat this as a *living process*: your repository should tell the story of how your model evolved.

In practice, your workflow should go over these steps in time in a safe, but tentative way: 

```
💡📝 First conceptual model with enough definitions (variables, parameters, agents, functions)
        ↓
🧱 First programming session creating a few model elements (not runnable)
        ↓
🔄 Commit changes: "add netlogo file"
        ↓
🔁📝 Rethinking a few definitions
        ↓
🧱 Second programming session updating the model with new definitions (not runnable)
        ↓
🔄 Commit changes: "update netlogo file"
        ↓
🧱 Third programming session creating a minimal set of procedures for initialisation (runnable)
        ↓
🔄 Commit changes: "update netlogo file"
        ↓
...
        ↓
🧪📊 Run a few simulations and observe the model dynamics (also output variables)
        ↓
🔁🧱 Refine a model procedure, not quite behaving as intended
        ↓
...
        ↓
...
```

---

## Tools and services checklist

To follow best practices, every simulation modeller should maintain a working toolkit and a structured workflow environment. Below is a checklist tailored to this course.

| Category                          | Tool / Service                   | Purpose                                                   | Key Concepts / Skills                                  |
| --------------------------------- | -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
| **Version control**               | **Git**                          | Track changes to your project files                       | Commits, branches, merges, history                     |
|                                   | **GitHub**                       | Host and share repositories online                        | README, issues, pull requests, releases                |
| **Model implementation**          | **NetLogo**                      | Main platform for building agent-based models             | Interface design, procedures, agents, patches, globals |
| **Data analysis & visualization** | **R** (later in the course)     | Process simulation results, generate plots and statistics | R scripts, data frames, ggplot2, tidyverse             |
|                                   | **RStudio** (optional)          | More agility using R (UI elements for common operations), allows seamless use of notebook formats, other script extensions and git                        | initial configuration, creating projects, package installation, notebook interaction                |
| **Interoperability**              | **RNetLogo** (optional)          | Run NetLogo from R for batch experiments                  | Automation, reproducibility, less flexibility            |
| **Documentation**                 | **Markdown (.md)**               | Write guides, notebooks, and documentation                | Formatting, headings, links, code blocks               |
|                                   | **README.md**                    | Front page of your GitHub repository                      | Summary, usage, citation                               |
|                                   | **BibTeX (.bib)** and software like **Zotero**  | Manage bibliographic database, faster import and export of references, citation style agnostic   | BibTeX entries, citation in any kind of document       |
| **Reproducible environment**      | **Project folders**              | Organise code, data, results, and docs                    | Clear structure, consistent naming                     |
|                                   | a general-purpose IDE (e.g. **VS Code**)  | Quick edit and manage all files with easy git integration and other features. Particularly useful for editing files not directly related to NetLogo or R.   | integrated file editing and management, essential when using other programming languages (e.g. HTML, Python).                   |
| **Collaboration and feedback**    | **GitHub Issues / Discussions** (optional)  | Record bugs, ideas, and model questions                   | Issue tracking, commenting              |
| **Archival and citation**         | **Zenodo** (later in the course) | Assign a DOI to your final model                          | Versioned release, FAIR principles                     |

### Minimal setup for this course

By the next session, you will have:

* [ ] Created a **GitHub account**.
* [ ] Created a simple repository for your model(s).
* [ ] Set up a structured folder for your project and write a minimal README file.
* [ ] Added these to your GitHub repository.
* [ ] Created a **Zenodo account**.
* [ ] Linked GitHub to Zenodo for future publication.

When using your own computer to work in a local repository:

* [ ] Installed **Git** (and **GitHub Desktop**) on your computer.  
* [ ] Installed **NetLogo**, and **R** (and **RStudio**).  
* [ ] Configured Git (username, email, SSH key or HTTPS). This is necessary when using version control locally in your computer.  

Also recommended:  

* [ ] Installed **VS Code** or equivalent (for editing text and code files).  
* [ ] Install **Zotero** or equivalent and create a user account.  

---

### Summary

A good modeller is a good *steward of code*. The tools are not the goal—they are supports for clarity, reproducibility, and collaboration. In this course, you will gradually assemble your own simulation software project, learning to combine conceptual, technical, and organisational skills.