# maisiedaisie/toronto-shelter-opioid-risk architecture

> Architecture diagram of the GitHub repository maisiedaisie/toronto-shelter-opioid-risk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maisiedaisie/toronto-shelter-opioid-risk
- Repository: https://github.com/maisiedaisie/toronto-shelter-opioid-risk

## Overview

This repository is a reproducible R-based geospatial analysis pipeline, not an application server. Its purpose is to estimate how many suspected opioid-poisoning events in Toronto occur near shelter sites, then convert those raw proximity counts into population-adjusted risk measures.

The main inputs are public CSV datasets in `data-files/`:
- TPaS suspected overdose events linked to intersections and neighbourhoods for 2025
- Toronto Shelter & Support Services shelter site locations
- 2021 census tract populations for Toronto

The code assumes additional external datasets may be downloaded separately, as described in the setup docs. That creates a clear boundary between bundled inputs and user-supplied source files.

The repository is organized as a staged R workflow in `R-code/`. The scripts are intended to run in order:
1. `01-data-environment.R` loads packages, establishes the R environment, and transforms raw CSVs into analysis-ready spatial data.
2. `02-data-validation.R` checks that those derived dataframes/objects were created correctly and fails loudly if something is missing or malformed.
3. `03-simple-analysis.R` performs the core proximity count analysis, tallying overdose events within 200 m and 500 m buffers around each shelter.
4. `04-data-analysis.R` performs the more advanced statistical layer, using census population data to derive standardized incidence ratio / risk ratio style estimates.

`run-simple-analysis.R` is a convenience entry point for the simpler workflow, while the markdown files in `information-and-notes/` provide the operational boundary for users: `QUICKSTART.md` for a lightweight reproducible path, `FULLSETUP.md` for the full analysis, and `DATANOTES.md` for provenance and limitations.

The dependency boundary is explicit: `renv.lock` pins the R package versions needed to reproduce the analysis. The README also states R 3.5.4 as the expected runtime, which matters for compatibility of the spatial/statistical packages used.

The primary data flow is:
raw public health / shelter / census inputs -> R environment setup -> spatial transformation and validation -> buffer-based event counting -> population-adjusted risk estimation -> tabular outputs written to the working directory.

The dominant analytical concept is spatial proximity. Shelter locations act as anchor points, and overdose events are counted within fixed-radius catchments. The census tract population file supplies the denominator for adjusted risk calculations, so the pipeline crosses from simple location counting into epidemiologic comparison.

The repository’s outputs are analytical artifacts, not interactive services: ranked shelter-level event counts, risk estimates, and associated uncertainty/statistical summaries. The README also references mapping and spatial statistics such as Moran’s I and kernel density as part of the broader analysis scope.

A useful architecture diagram would show three layers:
- source data and external downloads
- sequential R processing/validation/statistical scripts
- generated CSV outputs and downstream figures/reports

The key implementation boundary is that each stage depends on the previous one, so the scripts are intentionally linear rather than independent. This is reinforced in the README’s warning not to mix the quickstart and full-setup workflows, since they would duplicate steps and potentially corrupt the working state.

Main entry points: [`R-code/01-data-environment.R`](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/01-data-environment.R) (Environment setup), [`R-code/03-simple-analysis.R`](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/03-simple-analysis.R) (Simple analysis), [`R-code/04-data-analysis.R`](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/04-data-analysis.R) (Advanced analysis), [`R-code/02-data-validation.R`](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/02-data-validation.R) (Data validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Source data"]
  node_n1["Overdose events<br/>CSV input"]
  node_n2["Neighbourhood events<br/>CSV input"]
  node_n3["Shelter sites<br/>CSV input"]
  node_n4["Census populations<br/>CSV input"]
  node_n5["External data<br/>downloaded inputs"]
end

subgraph group_workflow["R workflow"]
  node_n6["Environment setup<br/>R stage"]
  node_n7["Data validation<br/>R stage"]
  node_n8["Simple analysis<br/>R stage"]
  node_n9["Advanced analysis<br/>R stage<br/>[04-data-analysis.R]"]
  node_n10["Simple runner<br/>R entrypoint"]
  node_n11["Runtime pin<br/>dependency lock<br/>[renv.lock]"]
end

subgraph group_docs["Setup notes"]
  node_n12["Quickstart<br/>setup guide<br/>[QUICKSTART.md]"]
  node_n13["Full setup<br/>setup guide<br/>[FULLSETUP.md]"]
  node_n14["Data notes<br/>provenance<br/>[DATANOTES.md]"]
end

subgraph group_outputs["Results"]
  node_n15["Shelter counts<br/>tabular output"]
  node_n16["Risk estimates<br/>statistical output"]
  node_n17["Figures<br/>visual output"]
  node_n18["Summary tables<br/>report output"]
end

node_n1 -->|"raw input"| node_n6
node_n2 -->|"raw input"| node_n6
node_n3 -->|"raw input"| node_n6
node_n4 -->|"raw input"| node_n6
node_n5 -.->|"optional input"| node_n6
node_n11 -->|"pins packages"| node_n6
node_n6 -->|"derived objects"| node_n7
node_n7 -->|"validated data"| node_n8
node_n7 -->|"validated data"| node_n9
node_n10 -->|"invokes"| node_n8
node_n12 -.->|"instructions"| node_n10
node_n13 -.->|"instructions"| node_n6
node_n8 -->|"writes"| node_n15
node_n8 -->|"writes"| node_n18
node_n9 -->|"writes"| node_n16
node_n9 -->|"writes"| node_n18
node_n9 -->|"writes"| node_n17
node_n14 -.->|"context"| node_n8

click node_n1 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-ems-calls-suspected-overdose-2025-by-intersection.csv"
click node_n2 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/tpas-suspected-overdose-2025-by-neighbourhood.csv"
click node_n3 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-shelter-sites-apr26.csv"
click node_n4 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-census-tract-populations-2021.csv"
click node_n6 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/01-data-environment.R"
click node_n7 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/02-data-validation.R"
click node_n8 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/03-simple-analysis.R"
click node_n9 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/04-data-analysis.R"
click node_n10 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/run-simple-analysis.R"
click node_n11 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/renv.lock"
click node_n12 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/QUICKSTART.md"
click node_n13 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/FULLSETUP.md"
click node_n14 "https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/DATANOTES.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n6,node_n7,node_n8,node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n17,node_n18 toneRose
```

## Components

### Source data

Bundled CSV inputs plus separately downloaded source files used by the analysis.

- [Overdose events](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-ems-calls-suspected-overdose-2025-by-intersection.csv): CSV input · Toronto suspected opioid-poisoning events linked to intersections. · `data-files/toronto-ems-calls-suspected-overdose-2025-by-intersection.csv`
- [Neighbourhood events](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/tpas-suspected-overdose-2025-by-neighbourhood.csv): CSV input · Suspected overdose events aggregated by neighbourhood. · `data-files/tpas-suspected-overdose-2025-by-neighbourhood.csv`
- [Shelter sites](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-shelter-sites-apr26.csv): CSV input · Toronto shelter and support services site locations used as spatial anchors. · `data-files/toronto-shelter-sites-apr26.csv`
- [Census populations](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/data-files/toronto-census-tract-populations-2021.csv): CSV input · 2021 Toronto census tract populations used as denominators for adjusted risk estimates. · `data-files/toronto-census-tract-populations-2021.csv`
- **External data**: downloaded inputs · Additional source files expected to be obtained separately during setup.

### R workflow

Linear staged scripts that prepare data, validate it, and run the proximity and risk analyses.

- [Environment setup](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/01-data-environment.R): R stage · Loads packages, establishes the runtime, and reshapes raw inputs into analysis-ready spatial objects. · `R-code/01-data-environment.R`
- [Data validation](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/02-data-validation.R): R stage · Checks that derived objects exist and are structurally sound before analysis continues. · `R-code/02-data-validation.R`
- [Simple analysis](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/03-simple-analysis.R): R stage · Counts overdose events within fixed-radius buffers around each shelter. · `R-code/03-simple-analysis.R`
- [Advanced analysis](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/R-code/04-data-analysis.R): R stage · Combines proximity counts with census denominators to estimate standardized risk measures. · `R-code/04-data-analysis.R`
- [Simple runner](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/run-simple-analysis.R): R entrypoint · Convenience script for the simpler workflow path. · `run-simple-analysis.R`
- [Runtime pin](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/renv.lock): dependency lock · Pinned R package versions for reproducibility. · `renv.lock`

### Setup notes

User-facing instructions and provenance notes that define the operational boundary.

- [Quickstart](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/QUICKSTART.md): setup guide · Lightweight reproducible setup path for the simple workflow. · `information-and-notes/QUICKSTART.md`
- [Full setup](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/FULLSETUP.md): setup guide · Complete setup and execution instructions for the full analysis. · `information-and-notes/FULLSETUP.md`
- [Data notes](https://github.com/maisiedaisie/toronto-shelter-opioid-risk/blob/main/information-and-notes/DATANOTES.md): provenance · Source notes, limitations, and interpretation guidance. · `information-and-notes/DATANOTES.md`

### Results

Generated analytical artifacts written to the working directory.

- **Shelter counts**: tabular output · Shelter-level event counts within 200 m and 500 m catchments.
- **Risk estimates**: statistical output · Population-adjusted risk ratios or standardized incidence style estimates.
- **Figures**: visual output · Maps and spatial-statistics figures referenced by the analysis narrative.
- **Summary tables**: report output · Derived tables and uncertainty summaries written to the working directory.

## Connections

- Overdose events → Environment setup: raw input · Event records are loaded into the analysis environment.
- Neighbourhood events → Environment setup: raw input · Neighbourhood-level event data is transformed alongside intersection records.
- Shelter sites → Environment setup: raw input · Shelter locations become spatial anchor points.
- Census populations → Environment setup: raw input · Population denominators are prepared for later adjustment.
- External data → Environment setup: optional input · External source files may be incorporated during setup.
- Runtime pin → Environment setup: pins packages · The locked dependency set constrains the runtime environment.
- Environment setup → Data validation: derived objects · Validation checks the objects created by environment setup.
- Data validation → Simple analysis: validated data · Simple analysis depends on passing data checks.
- Data validation → Advanced analysis: validated data · Advanced analysis uses the same validated spatial objects.
- Simple runner → Simple analysis: invokes · Convenience entry point for the simple workflow.
- Quickstart → Simple runner: instructions · Quickstart points users at the lightweight runner.
- Full setup → Environment setup: instructions · Full setup describes the staged workflow and environment preparation.
- Simple analysis → Shelter counts: writes · Buffer-based event tallies are emitted as tabular results.
- Simple analysis → Summary tables: writes · The simple pipeline also produces summary tables.
- Advanced analysis → Risk estimates: writes · Population-adjusted risk measures are generated here.
- Advanced analysis → Summary tables: writes · Advanced statistics and uncertainty summaries are written out.
- Advanced analysis → Figures: writes · Broader spatial-statistics outputs include mapping and figure artifacts.
- Data notes → Simple analysis: context · Provenance notes frame interpretation of the analytical outputs.
