TreeScan/README.qmd at main · EpiForeSITE/TreeScan · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
---
format: gfm
---

<!-- README.md is generated from README.qmd. Please edit that file -->

```{r}
#| include: false
devtools::load_all(quiet = TRUE)
```

# treescanr

**treescanr** is a lightweight R interface to
[TreeScan](https://www.treescan.org), the tree-based scan statistic, for
syndromic surveillance with ICD-10-CM coded emergency department visits. It
packages the core of the epiENGAGE TreeScan implementation (see
`treescan_project/` for the original scripts) as a small set of pipeable
functions:

| Function | Purpose |
|---|---|
| `ts_visits()`, `ts_visits_nssp()` | Standardize visit-level data |
| `ts_counts()` | Build the count file of incident diagnoses |
| `ts_prm_template()`, `ts_prm_set()` | Build the TreeScan parameter file |
| `ts_run()` | Run TreeScan and read the results |
| `ts_results()` | Reload results from a previous run |

## Installation

```r
# install.packages("remotes")
remotes::install_github("EpiForeSITE/TreeScan")
```

You also need the **command-line (non-graphical)** version of TreeScan
(>= 2.4.1), available at <https://www.treescan.org/download_treescan.html>
(account required). Tell treescanr where it is:

```r
options(treescanr.binary = "~/TreeScan/treescan64")  # or set TREESCAN_BIN
```

## Quick start

The package ships a small synthetic dataset with a cluster of viral
gastroenteritis (A08.4) in the last days of June 2026:

```{r}
library(treescanr)
ex <- function(f) system.file("extdata", f, package = "treescanr")

counts <- read.csv(ex("toy_visits.csv")) |>
  ts_visits() |>
  ts_counts(end_date = "2026-06-30", tree_wide = ex("toy_tree_wide.txt"), seed = 1)

head(counts)
```

Running TreeScan takes one more step. Since treescanr is meant for routine
(daily or weekly) use, write the results to a **persistent location** so you
can reload them in later sessions:

```r
dir <- tools::R_user_dir("treescanr", "data")

res <- counts |>
  ts_run(tree = ex("toy_tree.csv"), dir = file.path(dir, "2026-06-30", "lag1"))
res

# Later, in a new session
ts_results(file.path(dir, "2026-06-30", "lag1"))
```

See `vignette("treescanr")` for a complete routine workflow.

## Development

A [devcontainer](.devcontainer/) with R, Quarto, and TreeScan is available as
the **private** image `ghcr.io/epiforesite/treescanr-dev` (developers only,
since TreeScan requires accepting its license). The same image runs
`R CMD check` in GitHub Actions, including the tests that call TreeScan.
To rebuild it after downloading a new TreeScan Linux release:

```sh
.devcontainer/build.sh ~/Downloads/treescan.2.4.1.tar.gz
```

Please cite TreeScan and its methodology papers when publishing results; see
the TreeScan User Guide.