Start here: setup and connect

Read one guide at a time. The first two describe THIP access; the last three run independently with synthetic data and no credentials.

Guide	Purpose
1. Start here	Installation, setup and table discovery (this page)
2. Prepare and filter sources	Tables, dates and lazy ICD filtering
3. Retrieve time windows	Entry keys, boundaries and batching
4. Flag conditions locally	Custom lists, matching and aggregation
5. Worked cohort example	Short end-to-end synthetic analysis

The remote snippets below are not executed during package builds. Run them in your authorized THIP R session. Column-name arguments use strings such as date = "adm"; ordinary dplyr verbs handle general manipulation.

Install or load thipR

If thipR is already installed, use library(thipR) and continue to configuration below. On your own computer, install it like any other package:

install.packages("pak")  # Once, if needed
pak::pak("Songyosr/thipR")

In a THIP notebook, install into R’s standard personal library in your home folder, which is kept between sessions. R defines this library but does not create the folder, so create it once first:

# Once per THIP account
lib <- Sys.getenv("R_LIBS_USER")
dir.create(lib, recursive = TRUE, showWarnings = FALSE)
.libPaths(c(lib, .libPaths()))  # Only needed in this first session
install.packages("pak")
pak::pak("Songyosr/thipR")
library(thipR)

From then on R finds the folder automatically at start-up, so later sessions need only library(thipR). If you installed an earlier version into ~/R/thipR-library, reinstall with the lines above; you can then delete that folder.

Installing thipR does not grant THIP database access. Installation needs network access and package dependencies. The database driver, ClickHouseHTTP, installs automatically; thipR is tested with version 1.1.2 and warns once if a newer, untested version is installed. For a reproducible study, install a tested release, for example pak::pak("Songyosr/thipR@v0.2.1").

Restart an existing R kernel after upgrading an already-loaded package. A source archive (.tar.gz) is another installation option; builds that include vignettes support vignette("getting-started", package = "thipR") locally.

Configure once, connect each session

library(thipR)
thip_setup()

Run this once, in a notebook cell inside your THIP account. You will see, in order:

1. Two text prompts: Database host: and then Database username:. Enter the values provided by the THIP team. Port 8123, database thip and scheme http use their defaults and are not asked for.
2. A masked password box: Database password:. Typed characters show as dots.
3. A short pause while a read-only check connects and then disconnects.
4. One confirmation line: “THIP configuration saved with owner-only permissions and loaded in this session.”

thip_setup()
#> Database host: <host provided by the THIP team>
#> Database username: <your database username>
#> Database password: (masked box)
#> THIP configuration saved with owner-only permissions and loaded in this session.

Setup saves six THIP_DB_* lines to your ~/.Renviron with owner-only permissions. In later sessions, call thip_connect() only. If the check fails, nothing is saved and you can simply run thip_setup() again.

Message or symptom	Meaning and what to do
“THIP configuration already exists”	Setup was done before. Use thip_connect(), or thip_setup(overwrite = TRUE) to replace the saved values.
“THIP connection verification failed”	The host, username or password is wrong, or the database is unreachable. Nothing was saved; run setup again.
“host must be a hostname without a URL, path or credentials”	Enter only the host name, without http://, a port or a path.
“Input unavailable or cancelled”	A prompt was cancelled or could not be shown. Run setup in an interactive notebook cell.
No masked password box outside Jupyter	In RStudio or a terminal, install the askpass package.

The .Renviron file is protected by file permissions; it is plaintext, not encrypted. If the platform already supplies the THIP_DB_* variables, skip setup. Never type credentials into notebook code or commit them to a repository. A Jupyter API token is not used by thipR.

library(thipR)
library(dplyr)
con <- thip_connect()
thip_tables(con)
thip_columns(con, "nhso2568")

thip_connect() uses two DB threads by default. Row/time limits inherit the platform settings unless supplied explicitly; overflow raises an error, not silent truncation. The package does not impose an arbitrary collection cap. DB thread settings are separate from R’s data.table thread settings. Metadata from an individual _local shard does not describe the entire distributed table.

Finish a session

DBI::dbDisconnect(con)

Supported API and compatibility

New code should use tables = ... and dplyr::collect(). Singular thip_table(table = ...) and thip_collect() are deprecated compatibility interfaces. thip_disconnect() is also deprecated; use DBI::dbDisconnect(). No connection argument is needed for thip_filter_icd() or thip_window() when the source already carries it.

The tested backend is ClickHouseHTTP 1.1.2. Older versions are refused; a newer version warns once per session, or stops with a clear message if it changed the connection structure thipR relies on. Vignette builds do not certify a live backend: opt-in read-only smoke scripts in inst/examples/ cover that path. Next: prepare and filter sources.