opensyndrome

Your R package to interact with Open Syndrome definitions!

Apply Open Syndrome Definitions (OSD) to tabular health data in R: download and cache definitions, map your dataset's columns to OSD concepts, and classify records by inclusion/exclusion criteria.

A focused R subset of open-syndrome-python, sharing the same on-disk cache (~/.open_syndrome/).

Status: early development. The classification engine is being built test-first; the public API grows one verified slice at a time.

Working now: download/cache and load definitions (os_download_definitions(), os_load(), os_list()), inspect them (os_required_fields(), os_describe(), os_validate()), map columns (os_read_profile() / os_validate_profile()), and classify (os_filter() / os_label()). Next: bundled example data and the getting-started vignette.

Usage (current API)

library(opensyndrome)

# 1. Get definitions (cached in ~/.open_syndrome/v1, shared with Python)
os_download_definitions()
os_list(disease = "Dengue", country = "United States")
dengue <- os_load("dengue_usa")          # by name, local file, or URL

# 2. See what the definition needs, then map your columns
os_required_fields(dengue)
os_describe(dengue)
profile <- os_read_profile("mapping.yaml", "ambulatory_care")
os_validate_profile(profile, my_data)    # catch mapping mistakes early

# 3. Classify
cases    <- os_filter(my_data, dengue, profile)                       # matching rows
labelled <- os_label(my_data, list(dengue = dengue, zika = zika), profile)  # a column each

A definition is a plain named list (as parsed from OSD JSON). Criteria that can't be evaluated against your columns are skipped with a warning by default; set on_unresolvable = "error" to stop instead.

Install

# install.packages("remotes")
remotes::install_github("OpenSyndrome/open-syndrome-r")

Run from source

install.packages(c("remotes", "devtools", "usethis"))
remotes::install_deps(dependencies = TRUE)  # from the repo root
devtools::load_all()
devtools::test()

The cache lives at ~/.open_syndrome/v1 (shared with the Python package). Point it elsewhere with the OPENSYNDROME_HOME environment variable.

Using your own local definitions

The definitions published by the Open Syndrome Initiative (the community definitions) always live in the cache. To add definitions of your own that are not published on GitHub, point OPENSYNDROME_DEFINITIONS_DIR to a directory you maintain; the package never writes to it. Put the variables in your .Renviron (see usethis::edit_r_environ()) or set them with Sys.setenv().

OPENSYNDROME_DEFINITIONS_DIR=./my-definitions

To ignore the community definitions altogether and use only yours, also set OPENSYNDROME_LOCAL_DEFINITIONS_ONLY=1 (true, yes and on also work). os_list() and os_load() then read your directory only.

os_definition_dirs() returns the directories read, in order:

OPENSYNDROME_DEFINITIONS_DIR	OPENSYNDROME_LOCAL_DEFINITIONS_ONLY	Result
unset	unset	community
set	unset	community, local
set	set	local
unset	set	error

It also accepts local_dir and local_only arguments that override the environment variables, and os_list() takes an explicit dirs argument. When the same definition name exists in more than one directory, the first one in that order wins.

Contributing

Development is strictly test-driven (red → green → refactor): write the failing testthat test first, confirm it fails, then implement.

usethis::use_test("thing")   # add tests/testthat/test-thing.R
devtools::test()             # run the suite
devtools::document()         # regenerate NAMESPACE + man/ after roxygen changes

Tests live in tests/testthat/; each R/<topic>.R has a matching test-<topic>.R.